리메시 API

리메시 API를 사용하면 다른 Meshy API(예: 이미지로 3D 또는 텍스트로 3D)로 생성된 기존 3D 모델을 리메시하고 다양한 형식으로 내보낼 수 있습니다. 이 섹션에서는 리메시 API 사용 방법에 대한 세부 정보를 제공합니다.

POST/openapi/v1/remesh

리메시 작업 삭제

이 엔드포인트는 관련된 모든 모델과 데이터를 포함하여 리메시 작업을 영구적으로 삭제합니다. 이 작업은 되돌릴 수 없습니다.

경로 매개변수

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

작업 상태

아직 PENDING 상태인 작업은 삭제되며, 생성 시 소비된 크레딧이 환불됩니다.

이미 IN_PROGRESS 상태인 작업은 삭제할 수 없습니다. 요청은 409 Conflict로 거부되며 작업은 계속 실행됩니다. 워커가 이미 시작한 작업에 대한 크레딧은 환불되지 않으므로, 실행 도중 삭제하면 크레딧과 결과 모두를 잃게 됩니다. SUCCEEDED, FAILED 또는 CANCELED 상태에 도달할 때까지 기다린 후 삭제하세요.

최종 상태(SUCCEEDED, FAILED 또는 CANCELED)에 있는 작업은 환불 없이 삭제됩니다.

반환값

성공 시 200 OK를 반환하며, 작업이 IN_PROGRESS인 경우 409 Conflict를 반환합니다.

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 is left 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."
}

GET/openapi/v1/remesh

리메시 작업 목록 조회

이 엔드포인트는 리메시 작업 목록을 조회할 수 있게 해줍니다.

매개변수

Name
page_num
Type
integer
기본값 1
Description
페이지네이션을 위한 페이지 번호입니다.
Name
page_size
Type
integer
기본값 10
Description
페이지 크기 제한입니다. 최대 허용치는 100개입니다.
Name
sort_by
Type
string
Description
정렬 기준 필드입니다.
사용 가능한 값:
- +created_at: 생성 시간 기준 오름차순으로 정렬합니다.
- -created_at: 생성 시간 기준 내림차순으로 정렬합니다.

반환값

리메시 작업 객체의 페이지네이션된 목록을 반환합니다.

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
  }
]

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

리메시 작업 스트리밍

이 엔드포인트는 Server-Sent Events(SSE)를 사용하여 리메시 작업의 실시간 업데이트를 스트리밍합니다.

Parameters

Name
id
Type
path
Description
스트리밍할 리메시 작업의 고유 식별자입니다.

Returns

리메시 작업 객체의 스트림을 Server-Sent Events 형태로 반환합니다.

PENDING 또는 IN_PROGRESS 상태의 작업의 경우, 응답 스트림에는 필요한 progress 및 status 필드만 포함됩니다.

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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,
}

리메시 태스크 객체

리메시 태스크 객체는 Meshy가 기존 3D 모델을 리메시하고 다양한 형식으로 내보내는 데 사용하는 작업 단위를 나타냅니다. 이 객체는 다음과 같은 속성을 가지고 있습니다:

Properties

Name
id
Type
string
Description
태스크의 고유 식별자입니다. 태스크 id의 구현 세부 사항으로 k-정렬 가능한 UUID를 사용하지만, id의 형식에 대해 어떠한 가정도 하지 않아야 합니다.
Name
type
Type
string
Description
리메시 태스크의 유형입니다. 값은 remesh입니다.
Name
model_urls
Type
object
Description
Meshy가 생성한 텍스처가 적용된 3D 모델 파일의 다운로드 가능한 URL입니다. 해당 형식이 생성되지 않은 경우 빈 문자열을 반환하는 대신 해당 형식에 대한 속성이 생략됩니다.
- Name
  glb
  Type
  string
  Description
  GLB 파일의 다운로드 가능한 URL입니다.
- Name
  fbx
  Type
  string
  Description
  FBX 파일의 다운로드 가능한 URL입니다.
- Name
  obj
  Type
  string
  Description
  OBJ 파일의 다운로드 가능한 URL입니다.
- Name
  usdz
  Type
  string
  Description
  USDZ 파일의 다운로드 가능한 URL입니다.
- Name
  blend
  Type
  string
  Description
  Blender 파일의 다운로드 가능한 URL입니다.
- Name
  stl
  Type
  string
  Description
  STL 파일의 다운로드 가능한 URL입니다.
- Name
  3mf
  Type
  string
  Description
  3MF 파일의 다운로드 가능한 URL입니다. target_formats를 통해 3mf가 요청된 경우에만 존재합니다.
Name
thumbnail_url
Type
string
Description
리메시된 모델로부터 렌더링된 미리보기 이미지의 다운로드 가능한 URL입니다.
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_url의 투명 배경(RGBA) 버전에 대한 다운로드 가능한 URL입니다. 태스크가 alpha_thumbnail: true로 생성되었고 투명 미리보기가 성공적으로 렌더링된 경우에만 존재하며, 그렇지 않으면 이 필드는 생략됩니다.
Name
progress
Type
integer
Description
태스크의 progress입니다. 태스크가 아직 시작되지 않았다면 이 속성은 0입니다. 태스크가 성공하면 100이 됩니다.
Name
status
Type
string
Description
태스크의 상태입니다. 가능한 값은 PENDING, IN_PROGRESS, SUCCEEDED, FAILED 중 하나입니다.
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
task_error
Type
object
Description
실패한 태스크에 대한 오류 세부 정보입니다. 전체 task_error 객체 참조는 오류를 참고하세요.
Name
consumed_credits
Type
integer
Description
이 태스크에서 소비된 크레딧 수입니다. 태스크 상태가 PENDING, IN_PROGRESS, 또는 SUCCEEDED일 때 존재합니다. FAILED 태스크의 경우 0을 반환합니다(실패 시 크레딧이 환불됩니다).

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
}

리메시 API

Remesh 작업 생성

파라미터

반환값

실패 모드

Request

Response

리메시 작업 조회

매개변수

반환값

Request

Response

리메시 작업 삭제

경로 매개변수

작업 상태

반환값

Request

Response

리메시 작업 목록 조회

매개변수

반환값

Request

Response

리메시 작업 스트리밍

Parameters

Returns

Request

Response Stream

리메시 태스크 객체

Properties

Example Remesh Task Object