리메시 API

3D 모델의 메시를 새로운 topology와 면 수로 재구성하고, 원하는 형식으로 내보내세요. 모델은 Image to 3D 또는 Text to 3D와 같은 다른 Meshy 작업에서 가져오거나, 모델 파일에서 가져올 수 있습니다.

POST/openapi/v1/remesh

Remesh 작업 생성

Remesh 작업을 생성합니다. 작업은 백그라운드에서 실행됩니다. 작업이 보통 얼마나 걸리는지는 처리 시간을 참고하세요.

모델의 포맷을 변환하거나 크기를 조정하려면 Convert API 또는 Resize API를 사용하세요. 이 페이지의 지원 중단된 파라미터는 여전히 작동하지만, 새로운 통합은 해당 엔드포인트를 사용해야 합니다.

Request

POST

/openapi/v1/remesh

# Basic remesh with custom formats and resize
curl https://api.meshy.ai/openapi/v1/remesh \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["glb", "fbx"],
    "topology": "quad",
    "target_polycount": 50000,
    "resize_height": 1.0,
    "origin_at": "bottom"
  }'

# Quad remesh with auto-size
curl https://api.meshy.ai/openapi/v1/remesh \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["glb", "fbx"],
    "topology": "quad",
    "target_polycount": 50000,
    "auto_size": true
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

파라미터

Name
input_task_id
Type
string
필수
Description
model_url을 전송하지 않는 한 필수입니다. 리메시하려는 모델이 속한 작업의 ID로, 예를 들어 텍스트로 3D, 이미지로 3D, 리텍스처, 또는 리메시 작업일 수 있습니다. 해당 작업은 API로 생성했으며 상태가 SUCCEEDED여야 합니다.

Name
model_url
Type
string
필수
Description
input_task_id를 전송하지 않는 한 필수입니다. 리메시할 모델로, 공개 URL 또는 data URI 형태입니다. 둘 다 전송하면 Meshy는 input_task_id를 사용합니다.
모델은 http 또는 https URL인 경우 최대 400MB, data URI인 경우 최대 100MB의 GLB, glTF, OBJ, FBX, 또는 STL 파일이어야 합니다. data URI의 경우 MIME type application/octet-stream을 사용하세요.
100MB를 초과하는 파일은 다음 규칙도 따라야 합니다:
- GLB, glTF, FBX, 또는 OBJ 파일은 최대 10,000,000개의 면을 가질 수 있습니다. Meshy는 면을 삼각형으로 계산하므로, 사각형은 2개로 계산되고, 여러 번 그려진 메시는 복사본마다 1개씩 계산됩니다.
- FBX 파일은 바이너리 FBX 7.1 이상이어야 합니다.
- GLB 또는 glTF 파일은 Draco 압축을 사용하지 않아야 합니다.

Name
target_formats
Type
string[]
기본값 ["glb"]
Description
생성할 파일 포맷입니다.
사용 가능한 값:
- glb
- fbx
- obj
- usdz
- blend
- stl
- 3mf
Name
topology
Type
string
기본값 triangle
Description
리메시된 모델의 면 유형입니다.
사용 가능한 값:
- quad: 쿼드 중심 메시
- triangle: 디시메이션된 삼각형 메시
Name
target_polycount
Type
integer
기본값 30000
Description
목표로 하는 면의 수로, 100에서 300000 사이입니다. 모델의 지오메트리에 따라 결과가 목표값과 다를 수 있습니다. 범위를 벗어난 값은 400을 반환합니다.
Name
decimation_mode
Type
integer
Description
레벨별 적응형 면 수입니다. 이 값을 설정하면 Meshy는 target_polycount를 무시합니다.
사용 가능한 값:
- 1: 최상
- 2: 높음
- 3: 중간
- 4: 낮음
Name
resize_height
Type
number
⚠ 사용 중단
기본값 0
Description
대신 Resize API를 사용하세요. 모델 크기를 조정할 높이로, 미터 단위입니다. resize_height, resize_longest_side, auto_size 중 최대 하나만 전송하세요.
Name
resize_longest_side
Type
number
⚠ 사용 중단
기본값 0
Description
대신 Resize API를 사용하세요. 모델 바운딩 박스의 가장 긴 변을 조정할 길이로, 미터 단위입니다. resize_height, resize_longest_side, auto_size 중 최대 하나만 전송하세요.
Name
auto_size
Type
boolean
⚠ 사용 중단
기본값 false
Description
대신 Resize API를 사용하세요. AI 비전을 사용해 객체의 실제 높이를 추정하고 모델 크기를 그에 맞게 조정할지 여부입니다. resize_height, resize_longest_side, auto_size 중 최대 하나만 전송하세요.
Name
origin_at
Type
string
⚠ 사용 중단
기본값 bottom
Description
대신 Resize API를 사용하세요. 모델의 원점을 어디에 둘지로, bottom 또는 center입니다. 기본값은 resize_height, resize_longest_side, 또는 auto_size를 전송할 때 적용됩니다. 이들 중 하나도 전송하지 않으면 Meshy는 origin_at을 전송한 경우에만 원점을 이동합니다.

Name
convert_format_only
Type
boolean
⚠ 사용 중단
Description
대신 Convert API를 사용하세요. 모델을 target_formats로만 변환할지 여부입니다. true인 경우 Meshy는 topology, target_polycount, decimation_mode, resize_height, resize_longest_side, auto_size를 무시하지만 값은 여전히 검사하므로, 유효하지 않은 값은 400을 반환합니다. convert_format_only: true인 경우, target_formats가 비어 있거나 null이면 400을 반환합니다.

Name
alpha_thumbnail
Type
boolean
기본값 false
Description
배경이 투명한(RGBA) 미리보기도 함께 렌더링할지 여부로, 작업을 조회할 때 alpha_thumbnail_url로 반환됩니다. thumbnail_url은 변경되지 않습니다.

반환값

응답의 result 필드에 새 Remesh 작업의 ID가 담겨 있습니다.

실패 모드

Name
400 - Bad Request
Description
요청을 실행할 수 없습니다. 오류 메시지는 어떤 문제가 발견되었는지 알려줍니다. 예를 들어:
- 파라미터 누락: model_url과 input_task_id 중 어느 것도 전송되지 않았습니다.
- 유효하지 않은 입력 작업: input_task_id가 성공한 API 작업이 아니거나, 해당 AI 모델이 리메시를 지원하지 않습니다.
- 유효하지 않은 모델 포맷: model_url 파일의 확장자가 지원되지 않습니다.
- 도달할 수 없는 URL: Meshy가 model_url 파일을 다운로드할 수 없습니다.
- 모델 파일이 너무 큼: model_url 파일이 http 또는 https URL인 경우 400MB를 초과하거나, data URI인 경우 100MB를 초과합니다.
- 면이 너무 많음: model_url 파일이 100MB를 초과하고 면이 10,000,000개를 초과합니다. 면 수를 줄인 다음 파일을 다시 전송하세요.
- 100MB를 초과하는 ASCII FBX: model_url 파일이 100MB를 초과하는 ASCII FBX입니다. 바이너리 FBX 또는 GLB로 전송하세요.
- 읽을 수 없는 모델 파일: model_url 파일이 100MB를 초과하고, Meshy가 헤더를 읽을 수 없습니다. 예를 들어 Draco로 압축된 GLB 또는 glTF이거나, 7.1 이전의 바이너리 FBX입니다.
- 모델 헤더가 너무 복잡함: model_url 파일이 100MB를 초과하고, 헤더에 검사해야 할 메시, 노드, 또는 레코드가 너무 많습니다. 파일의 객체 수를 줄인 다음 다시 전송하세요.
- 유효하지 않은 topology: topology가 quad 또는 triangle이 아닙니다.
- 상호 배타적인 파라미터: 요청에 auto_size, resize_height, resize_longest_side 중 둘 이상이 포함되어 있습니다. 하나만 전송하세요.
요청을 수정한 다음 다시 전송하세요. 오류를 참고하세요.
Name
401 - Unauthorized
Description
API 키가 없거나 유효하지 않습니다. Authorization 헤더를 확인하세요.
Name
402 - Payment Required
Description
예를 들어:
- 크레딧 부족: 계정에 이 작업을 수행할 충분한 크레딧이 없거나, 계정이 크레딧 한도에 도달했습니다. 크레딧 잔액을 확인한 다음 다시 시도하세요.
- 무료 플랜: 작업을 생성하려면 유료 플랜이 필요합니다. 구독 설정에서 플랜을 업그레이드한 다음 다시 시도하세요.
Name
403 - Forbidden
Description
input_task_id가 양각(bas-relief) 모델이며, 이 엔드포인트는 이를 리메시할 수 없습니다. 메시지는 This model type does not support this operation입니다. 다른 모델을 전송하세요.
Name
404 - Not Found
Description
input_task_id가 귀하의 작업과 일치하지 않습니다. 작업 ID를 확인한 다음 요청을 다시 전송하세요.
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다. 잠시 기다린 다음 다시 시도하세요. 속도 제한을 참고하세요.

GET/openapi/v1/remesh/:id

리메시 작업 가져오기

ID로 리메시 작업을 반환합니다.

Request

GET

/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null
}

매개변수

Name
id
Type
path
Description
생성 응답에서 받은 작업 ID입니다.

반환값

리메시 작업 객체를 반환합니다.

DELETE/openapi/v1/remesh/:id

리메시 작업 삭제

리메시 작업을 모델과 데이터를 포함하여 영구적으로 삭제합니다. 삭제는 취소할 수 없습니다.

Request

DELETE

/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

경로 매개변수

Name
id
Type
path
Description
삭제할 작업의 ID입니다.

작업 상태

PENDING 상태의 작업을 삭제하면 작업 생성 시 사용된 크레딧이 환불됩니다.

IN_PROGRESS 상태의 작업은 삭제할 수 없습니다. 요청은 409 Conflict를 반환하며, 작업은 계속 실행됩니다. Meshy는 이미 시작된 작업에 대해서는 환불을 제공하지 않으므로, 이를 삭제하면 크레딧과 결과물을 모두 잃게 됩니다. 작업이 SUCCEEDED, FAILED, 또는 CANCELED 상태가 될 때까지 기다린 후 삭제하세요.

최종 상태(SUCCEEDED, FAILED, 또는 CANCELED)의 작업을 삭제해도 크레딧은 환불되지 않습니다.

반환값

작업이 삭제되면 200 OK를, 작업이 IN_PROGRESS 상태이면 409 Conflict를 반환합니다.

GET/openapi/v1/remesh

리메시 작업 목록 조회

회원님의 리메시 작업 목록을 반환합니다.

Request

GET

/openapi/v1/remesh

curl https://api.meshy.ai/openapi/v1/remesh?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "remesh",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null
  }
]

매개변수

Name
page_num
Type
integer
기본값 1
Description
반환할 페이지 번호이며, 최대 255까지 가능합니다. 더 큰 값을 입력하면 400이 반환됩니다.
Name
page_size
Type
integer
기본값 10
Description
페이지당 작업 수이며, 최대 100까지 가능합니다.
Name
sort_by
Type
string
Description
정렬 순서입니다.
사용 가능한 값:
- +created_at: 오래된 순
- -created_at: 최신 순

반환값

리메시 작업 객체의 페이지네이션 목록입니다.

GET/openapi/v1/remesh/:id/stream

리메시 작업 스트리밍

리메시 작업의 업데이트를 서버-전송 이벤트(SSE)로 스트리밍합니다.

Request

GET

/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// These examples are shortened. Each event holds the full task object.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
    "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
}

Parameters

Name
id
Type
path
Description
생성 응답에서 받은 작업 ID입니다.

Returns

리메시 작업 객체의 스트림을 서버-전송 이벤트(SSE)로 반환합니다.

각 이벤트는 Get 엔드포인트가 반환하는 것과 동일한 형태로 전체 작업 객체를 담고 있습니다. 작업이 PENDING 또는 IN_PROGRESS 상태인 동안에는 결과 필드에 아직 값이 없습니다.

리메시 작업 객체

리메시 작업 객체는 3D 모델의 리메시 작업 하나를 설명합니다. 이 객체는 작업이 성공했을 때의 상태, progress, 모델 파일을 담고 있습니다.

속성

Example Remesh Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5
}

Name
id
Type
string
Description
작업 ID입니다. 형식에 의존하지 말고 불투명한 문자열로 취급하세요.
Name
type
Type
string
Description
작업 유형으로, 항상 remesh입니다.
Name
model_urls
Type
object
Description
리메시된 모델의 다운로드 URL이며, 파일 형식마다 하나씩 제공됩니다. 작업이 생성하지 않은 형식은 빈 문자열이 아니라 키 자체가 없습니다.
- Name
  glb
  Type
  string
  Description
  GLB 파일입니다.
- Name
  fbx
  Type
  string
  Description
  FBX 파일입니다.
- Name
  obj
  Type
  string
  Description
  OBJ 파일입니다.
- Name
  usdz
  Type
  string
  Description
  USDZ 파일입니다.
- Name
  blend
  Type
  string
  Description
  Blender 파일입니다.
- Name
  stl
  Type
  string
  Description
  STL 파일입니다.
- Name
  3mf
  Type
  string
  Description
  3MF 파일입니다. target_formats에 3mf가 포함된 경우에만 존재합니다.
Name
thumbnail_url
Type
string
Description
리메시된 모델의 미리보기 이미지 다운로드 URL입니다.
Name
alpha_thumbnail_url
Type
string
Description
배경이 투명한(RGBA) 버전의 thumbnail_url 다운로드 URL입니다. alpha_thumbnail: true로 작업을 생성하고 Meshy가 투명 미리보기를 렌더링한 경우에만 존재합니다.
Name
progress
Type
integer
Description
작업이 완료된 정도를 백분율로 나타냅니다. 작업이 시작되기 전까지는 0이고, 성공하면 100입니다.
Name
status
Type
string
Description
작업 상태로, PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED 중 하나입니다.
Name
preceding_tasks
Type
integer
Description
대기열에서 이 작업보다 앞에 있는 작업의 수입니다. 이 값은 작업이 PENDING 상태일 때만 의미가 있습니다.
Name
created_at
Type
timestamp
Description
작업이 생성된 시각으로, 유닉스 밀리초 단위입니다.
Name
started_at
Type
timestamp
Description
작업이 시작된 시각으로, 유닉스 밀리초 단위입니다. 작업이 시작되기 전까지는 0입니다.
Name
finished_at
Type
timestamp
Description
작업이 종료된 시각으로, 유닉스 밀리초 단위입니다. 작업이 종료되기 전까지는 0입니다.
Name
expires_at
Type
timestamp
Description
작업의 다운로드 URL이 만료되는 시각으로, 유닉스 밀리초 단위입니다. 작업이 종료되기 전까지는 0입니다.
Name
texture_urls
Type
array
Description
작업이 성공했을 때 모델의 텍스처 맵 다운로드 URL입니다: 텍스처 세트마다 하나씩인 객체의 배열입니다. 각 객체는 base_color URL을 가지며, metallic, roughness, normal, emission, metallic_roughness URL도 가질 수 있습니다. 작업이 성공하기 전까지는 null이며, 모델에 텍스처 맵이 없으면 빈 배열입니다.
Name
task_error
Type
object
Description
작업이 실패했을 때의 오류 세부 정보입니다. 오류를 참고하세요.
Name
consumed_credits
Type
integer
Description
작업이 사용한 크레딧 수입니다. 상태가 PENDING, IN_PROGRESS, SUCCEEDED일 때 존재합니다. FAILED 작업의 경우 Meshy가 크레딧을 환불하므로 0입니다.