Creative Lab 피규어 API

사진을 두 단계에 걸쳐 치비 스타일의 수집용 3D 피규어로 변환합니다. 프로토타입 작업은 사진으로부터 콘셉트 이미지를 생성합니다. 빌드 작업은 해당 이미지를 텍스처가 적용된 3D 모델로 변환하며, 프로토타입 작업의 ID를 input_task_id로 사용합니다.

POST /openapi/creative-lab/figure/v1/prototype
POST /openapi/creative-lab/figure/v1/build

POST/openapi/creative-lab/figure/v1/prototype

Figure 프로토타입 작업 생성

사진으로부터 치비 스타일의 콘셉트 이미지를 하나 생성합니다. 3D 모델을 빌드하려면 이 작업의 ID를 input_task_id로 빌드 엔드포인트에 전달하세요. 작업의 필드에 대해서는 Figure 프로토타입 작업 객체를 참고하세요.

Request

POST

/openapi/creative-lab/figure/v1/prototype

# Stage 1: generate a chibi-style concept image
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Prototype example

Start with a source portrait, then generate the prototype image used by the build stage.

Source portrait used as the Creative Lab Figure input — Prototype input

Chibi-style figurine prototype image generated from the source photo — Prototype output

매개변수

Name
image_url
Type
string
필수
Description
치비 피규어로 변환할 사진으로, 공개 URL이거나 data URI(data:image/jpeg;base64,<your base64-encoded image data>)여야 합니다.
이미지는 최대 20MB의 JPG, JPEG, PNG, 또는 WebP 파일이어야 합니다.
Name
name
Type
string
Description
작업의 이름으로, 최대 100자까지 입력할 수 있습니다. 작업의 name 필드에 그대로 반환됩니다. 이름이 더 길면 400이 반환됩니다.
Name
remove_background
Type
boolean
기본값 false
Description
프로토타입 이미지에서 배경을 제거할지 여부입니다. true로 설정하면 투명한 RGBA PNG가 반환되어, 대상을 어떤 배경에든 배치할 수 있습니다. 빌드 역시 배경이 제거된 이미지를 기반으로 시작됩니다. Meshy가 배경을 제거할 수 없는 경우, 배경이 포함된 이미지가 반환되며 작업은 여전히 성공으로 처리됩니다.

반환 값

result 필드에는 새로 생성된 프로토타입 작업의 ID가 담깁니다. status가 SUCCEEDED가 될 때까지 작업을 가져오거나 스트리밍하세요. 그런 다음 해당 ID를 input_task_id로 빌드 엔드포인트에 전달하세요.

실패 모드

Name
400 - Bad Request
Description
요청을 실행할 수 없습니다. 예를 들면:
- image_url이 누락되었습니다.
- 이미지가 JPG, JPEG, PNG, 또는 WebP 파일이 아닙니다.
- 이미지가 너무 작거나, 20MB를 초과하거나, 최대 픽셀 수를 초과합니다.
- Meshy가 이미지를 다운로드할 수 없습니다. 예를 들어 URL이 404를 반환하거나 시간이 초과되는 경우입니다.
- data URI가 유효한 base64가 아닙니다.
- 이미지가 NSFW로 표시되었습니다.
오류 메시지에 어떤 문제가 발견되었는지 표시됩니다. 요청을 수정한 뒤 다시 보내세요.
Name
401 - Unauthorized
Description
API 키가 누락되었거나 유효하지 않습니다. Authorization 헤더를 확인하세요.
Name
402 - Payment Required
Description
다음 중 하나에 해당합니다:
- 계정에 크레딧이 충분하지 않습니다.
- API 키, 작업 공간, 또는 구성원이 크레딧 한도에 도달했습니다.
- 계정이 무료 플랜을 사용 중입니다.
크레딧과 플랜을 확인한 뒤 다시 시도하세요.
Name
403 - Forbidden
Description
팀에서 IP 필터링이 켜져 있고, Meshy가 해당 이미지를 제3자 지적 재산으로 표시했습니다. 사용 권한이 있는 이미지를 보내세요.
Name
429 - Too Many Requests
Description
다음 한도 중 하나에 도달했습니다:
- 속도 제한을 초과하는 요청을 보냈습니다. 몇 초 기다린 뒤 다시 시도하세요. 속도 제한을 참고하세요.
- 대기 중이거나 실행 중인 작업이 너무 많습니다. 일부가 끝날 때까지 기다린 뒤 다시 시도하세요.
- 크레딧이 남아 있지 않은 무제한 플랜에서, 크레딧 없이 실행할 수 있는 작업 수에 도달했습니다. 작업이 끝나기를 기다리거나 크레딧을 추가하세요.
Name
500 - Internal Server Error
Description
Meshy에서 서버 오류가 발생했습니다. 예를 들어 이미지에 대한 지적 재산 검사를 실행할 수 없었기 때문일 수 있습니다. Meshy는 작업을 생성하지 않으며, 청구된 크레딧이 있다면 환불합니다. 요청을 다시 시도하세요.

POST/openapi/creative-lab/figure/v1/build

피규어 빌드 작업 생성

성공한 프로토타입 작업으로부터 텍스처가 적용된 3D 피규어를 생성합니다. 필드에 대한 자세한 내용은 피규어 빌드 작업 객체를 참조하세요.

Request

POST

/openapi/creative-lab/figure/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

Response

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}

Build example

빌드 작업은 선택한 프로토타입 이미지를 다운로드 가능한 텍스처 적용 3D 모델로 변환합니다.

Creative Lab Figure build model preview — Build model preview

매개변수

Name
input_task_id
Type
string
필수
Description
빌드할 프로토타입 작업의 ID입니다. POST /openapi/creative-lab/figure/v1/prototype으로 해당 계정이 생성한 작업이어야 하며, 상태가 SUCCEEDED여야 합니다.
API를 통해 생성한 피규어 프로토타입 작업이 아닌 ID는 404를 반환하며, 웹 앱에서 만든 프로토타입도 마찬가지입니다.
Name
name
Type
string
Description
작업의 이름으로, 최대 100자까지 지정할 수 있습니다. 작업의 name 필드에 그대로 반환됩니다. 이보다 긴 이름은 400을 반환합니다.

반환값

result 필드에 새 빌드 작업의 ID가 담겨 있습니다. status가 SUCCEEDED가 될 때까지 작업을 조회하거나 스트리밍하세요. 그런 다음 model_urls.glb에서 텍스처가 적용된 GLB를 다운로드하세요. OBJ를 원하는 경우 model_urls.obj와 함께 model_urls.mtl에서 머티리얼 파일을 다운로드하세요.

실패 모드

Name
400 - Bad Request
Description
요청을 실행할 수 없습니다. 예를 들면:
- input_task_id가 없거나 유효한 작업 ID가 아닙니다.
- 프로토타입 작업의 상태가 SUCCEEDED가 아닙니다. 아직 실행 중이라면 기다렸다가 다시 시도하세요. 실패했거나 취소되었다면 새 프로토타입 작업을 생성하세요.
- 프로토타입 작업은 성공했지만 이미지가 없습니다. 새 프로토타입 작업을 생성하세요.
오류 메시지에 어떤 문제가 발견되었는지 나와 있습니다.
Name
401 - Unauthorized
Description
API 키가 없거나 유효하지 않습니다. Authorization 헤더를 확인하세요.
Name
402 - Payment Required
Description
다음 중 하나에 해당합니다:
- 계정에 크레딧이 충분하지 않습니다.
- API 키, 작업 공간 또는 멤버가 크레딧 한도에 도달했습니다.
- 계정이 무료 요금제를 사용 중입니다.
크레딧과 요금제를 확인한 후 다시 시도하세요.
Name
404 - Not Found
Description
input_task_id가 해당 계정이 API로 생성한 피규어 프로토타입 작업과 일치하지 않습니다. 웹 앱에서 만든 프로토타입도 404를 반환합니다. 프로토타입 생성 응답의 result ID를 전송하세요.
Name
429 - Too Many Requests
Description
다음 한도 중 하나에 도달했습니다:
- 속도 제한이 허용하는 것보다 더 많은 요청을 보냈습니다. 몇 초 기다렸다가 다시 시도하세요. 속도 제한을 참조하세요.
- 대기 중이거나 실행 중인 작업이 너무 많습니다. 일부가 완료될 때까지 기다렸다가 다시 시도하세요.
- 크레딧이 남아 있지 않은 무제한 요금제에서 크레딧 없이 실행할 수 있는 작업 수에 도달했습니다. 작업이 완료되기를 기다리거나 크레딧을 추가하세요.

GET/openapi/creative-lab/figure/v1/(prototype|build)/:id

Figure 작업 조회

프로토타입 또는 빌드 작업을 반환합니다. 경로는 작업의 단계와 일치해야 합니다. /prototype/:id를 통해 요청한 빌드 작업은 404를 반환하며, /build/:id를 통해 요청한 프로토타입 작업도 마찬가지로 404를 반환합니다.

필드에 대해서는 Figure 프로토타입 작업 객체 및 Figure 빌드 작업 객체를 참고하세요.

Request

GET

/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-figure-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-figure-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?Expires=***"
    }
  ],
  "remove_lighting": true
}

매개변수

Name
id
Type
path
Description
생성 응답의 작업 ID입니다.

반환값

경로의 단계에 맞는 프로토타입 작업 객체 또는 빌드 작업 객체입니다.

실패 모드

Name
400 - Bad Request
Description
id가 유효한 작업 ID가 아닙니다. 생성 응답의 result ID를 전송하세요.
Name
403 - Forbidden
Description
팀에서 IP Filtering이 켜져 있고, Meshy가 작업의 이미지를 제3자 지적 재산권 문제로 플래그했습니다. Enterprise 플랜을 사용하는 팀은 이 오류가 발생하지 않습니다. 사용 권한이 있는 이미지로 프로토타입 작업을 생성하세요.
Name
404 - Not Found
Description
이 ID를 가진 Figure 작업이 계정에 존재하지 않거나, 작업의 단계가 경로와 일치하지 않습니다. ID를 확인하고, 작업에 맞게 /prototype 또는 /build를 사용하세요.
Name
500 - Internal Server Error
Description
Meshy가 지적 재산권 검사를 실행하지 못했습니다. 요청을 다시 시도하세요.

DELETE/openapi/creative-lab/figure/v1/(prototype|build)/:id

Figure 작업 삭제

Figure 작업을 취소합니다. PENDING 작업을 취소하면 크레딧이 환불됩니다. IN_PROGRESS 작업은 이미 워커가 처리를 시작했기 때문에 환불 없이 취소됩니다. 최종 상태(SUCCEEDED, FAILED, 또는 CANCELED)인 작업은 취소할 수 없습니다.

경로는 작업의 단계와 일치해야 합니다. 예를 들어, 빌드 작업의 ID로 /prototype/:id에 DELETE를 실행하면 404가 반환됩니다.

Request

DELETE

/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).

경로 매개변수

Name
id
Type
path
Description
취소할 작업의 ID입니다.

반환값

빈 본문을 가진 204 No Content.

실패 모드

Name
400 - Bad Request
Description
다음 중 하나에 해당합니다:
- id가 유효한 작업 ID가 아닙니다. 생성 응답의 result ID를 보내세요.
- 작업이 이미 최종 상태(SUCCEEDED, FAILED, 또는 CANCELED)이므로 취소할 수 없습니다.
Name
404 - Not Found
Description
해당 계정에 이 ID를 가진 Figure 작업이 없거나, 작업의 단계가 경로와 일치하지 않습니다. ID를 확인하고 작업에 맞게 /prototype 또는 /build를 사용하세요.

GET/openapi/creative-lab/figure/v1/(prototype|build)/:id/stream

Figure 작업 스트리밍

Figure 작업의 업데이트를 Server-Sent Events(SSE)로 스트리밍합니다. 경로는 작업의 단계와 일치해야 합니다. 예를 들어 build 작업의 ID로 /prototype/:id/stream에 요청하는 것처럼 일치하지 않으면, 스트림은 status_code: 404와 함께 error 이벤트 하나를 보내고 닫힙니다.

Request

GET

/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream

curl -N https://api.meshy.ai/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (wrong stage or task not found)
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// Every frame is the full task object; fields not yet populated are null / empty.
// The following PENDING frame is shortened to the fields that change.
event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-figure-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 30,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?Expires=***"
    }
  ],
  "remove_lighting": true
}

매개변수

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

반환 값

prototype 또는 build 작업 객체의 스트림입니다. 각 이벤트는 Figure 작업 조회가 반환하는 것과 동일한 전체 작업 객체를 담고 있습니다. 작업이 PENDING 또는 IN_PROGRESS 상태인 동안에는 출력 필드가 아직 비어 있으며(null, [], 또는 {}), finished_at은 null입니다.

IP Filtering이 작업 결과를 차단하는 경우, 스트림은 그 자리에 get 요청이 반환했을 status_code와 함께 error 이벤트 하나를 보냅니다.

GET/openapi/creative-lab/figure/v1/(prototype|build)

Figure 작업 목록 조회

한 단계(stage)의 Figure 작업을 한 번에 한 페이지씩 반환합니다. 경로(path)가 단계를 선택합니다. /prototype은 프로토타입 작업만 반환하고, /build는 빌드 작업만 반환합니다.

Request

GET

/openapi/creative-lab/figure/v1/prototype

# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/build?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-figure-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123486000,
    "expires_at": 1729382686000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

경로 매개변수

Name
stage
Type
path
필수
Description
조회할 단계로, prototype 또는 build입니다.

쿼리 매개변수

Name
page_num
Type
integer
기본값 1
Description
반환할 페이지로, 1부터 255까지입니다. 0은 첫 페이지를 반환합니다. 0에서 255 범위를 벗어난 값은 400을 반환합니다.
Name
page_size
Type
integer
기본값 10
Description
페이지당 작업 수로, 최대 100입니다. 101에서 255 사이의 값은 100개의 작업을 반환하며, 0은 기본값을 사용합니다. 0에서 255 범위를 벗어난 값은 400을 반환합니다.
Name
sort_by
Type
string
기본값 -created_at
Description
정렬 순서입니다.
사용 가능한 값:
- -created_at: 최신순
- +created_at: 오래된순

반환값

경로의 단계에 해당하는 프로토타입 작업 객체 또는 빌드 작업 객체의 배열입니다.

The Figure prototype task object

프로토타입 작업은 사진으로부터 치비 스타일의 콘셉트 이미지를 생성합니다. 이미지를 3D 모델로 전환하려면 작업의 ID를 빌드 엔드포인트에 input_task_id로 전달하세요.

Properties

Example Figure Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-figure-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Name
id
Type
string
Description
작업 ID입니다. 이 형식에 의존하지 마세요.
Name
type
Type
string
Description
작업 유형이며, 항상 creative-lab-figure-prototype입니다.
Name
name
Type
string
Description
작업을 생성할 때 보낸 name이며, 보내지 않은 경우 ""입니다.
Name
status
Type
string
Description
작업의 상태입니다.
사용 가능한 값:
- PENDING: 대기열에서 대기 중
- IN_PROGRESS: 결과 생성 중
- SUCCEEDED: 최종 상태이며, 결과가 있음
- FAILED: 최종 상태이며, 사유는 task_error에 있음
- CANCELED: 최종 상태이며, 결과 없음
Name
progress
Type
integer
Description
작업 완료 비율로, 0에서 100 사이입니다. 작업이 시작되기 전에는 0이고, 성공하면 100입니다.
Name
created_at
Type
timestamp
Description
작업이 생성된 시간으로, Unix 밀리초 단위입니다.
Name
started_at
Type
timestamp
Description
워커가 작업을 시작한 시간으로, Unix 밀리초 단위입니다. 그 전까지는 null입니다.
Name
finished_at
Type
timestamp
Description
작업이 최종 상태에 도달한 시간으로, Unix 밀리초 단위입니다. 그 전까지는 null입니다.
Name
expires_at
Type
timestamp
Description
작업 결과가 만료되는 시간으로, Unix 밀리초 단위입니다. finished_at으로부터 3일 후이며, 작업이 완료되기 전까지는 created_at으로부터 3일 후입니다. API 결과를 무기한 보관하는 Enterprise 계정의 경우 약 100년 후입니다. 에셋 보존을 참고하세요.
Name
preceding_tasks
Type
integer
Description
작업이 PENDING 상태일 때 대기열에서의 위치입니다. 1은 다음 차례로 시작됨을 의미합니다. 작업이 대기열에서 빠지면 0이 되며, 목록 결과에서는 항상 0입니다.
Name
task_error
Type
object
Description
작업이 실패한 이유입니다. status가 FAILED가 아니면 null입니다. 오류를 참고하세요.
Name
consumed_credits
Type
integer
Description
환불을 반영한 후 해당 작업에 청구된 크레딧 수입니다. 오류를 반환하는 요청은 청구되지 않습니다. 실패한 작업은 Meshy가 환불하므로 0입니다. 취소는 작업이 PENDING 상태인 동안에만 환불됩니다. Meshy가 청구 내역을 읽지 못하면 get 또는 스트림 응답에서는 이 필드가 생략되며, 목록 요청은 500을 반환합니다. 이 경우 요청을 다시 시도하세요.
Name
image_urls
Type
array of strings
Description
콘셉트 이미지의 다운로드 URL입니다. 작업이 성공한 후에는 배열에 URL이 하나 있으며, 그 전까지는 비어 있습니다.

피규어 빌드 작업 객체

빌드 작업은 성공한 프로토타입 작업으로부터 텍스처가 적용된 3D 피규어를 생성합니다. 이 작업의 model_urls, thumbnail_url, texture_urls 필드는 이미지로 3D 작업 객체와 동일한 형식을 가집니다.

속성

Example Figure Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-figure-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?Expires=***"
    }
  ],
  "remove_lighting": true
}

Name
id
Type
string
Description
작업 ID입니다. 형식에 의존하지 마세요.
Name
type
Type
string
Description
작업 유형이며, 항상 creative-lab-figure-build입니다.
Name
name
Type
string
Description
작업을 생성할 때 보낸 name이며, 보내지 않았다면 ""입니다.
Name
status
Type
string
Description
작업의 상태입니다.
사용 가능한 값:
- PENDING: 대기열에서 대기 중
- IN_PROGRESS: 결과 생성 중
- SUCCEEDED: 결과와 함께 완료됨
- FAILED: task_error에 사유와 함께 완료됨
- CANCELED: 결과 없이 완료됨
Name
progress
Type
integer
Description
작업 완료 비율로, 0에서 100까지입니다. 작업이 시작되기 전까지는 0이며, 성공하면 100이 됩니다.
Name
created_at
Type
timestamp
Description
작업이 생성된 시각으로, 유닉스 밀리초 단위입니다.
Name
started_at
Type
timestamp
Description
워커가 작업을 시작한 시각으로, 유닉스 밀리초 단위입니다. 시작되기 전까지는 null입니다.
Name
finished_at
Type
timestamp
Description
작업이 최종 상태에 도달한 시각으로, 유닉스 밀리초 단위입니다. 도달하기 전까지는 null입니다.
Name
expires_at
Type
timestamp
Description
작업 결과가 만료되는 시각으로, 유닉스 밀리초 단위입니다. finished_at 이후 3일이며, 작업이 끝나기 전까지는 created_at 이후 3일로 표시됩니다. API 결과를 무기한 보관하는 Enterprise 계정의 경우 약 100년 후입니다. 에셋 보존을 참고하세요.
Name
preceding_tasks
Type
integer
Description
작업이 PENDING 상태일 때 대기열에서의 위치입니다. 1은 다음에 시작됨을 의미합니다. 작업이 대기열을 벗어나면 0이며, 목록 결과에서는 항상 0입니다.
Name
task_error
Type
object
Description
작업이 실패한 이유입니다. status가 FAILED가 아닌 한 null입니다. 오류를 참고하세요.
Name
consumed_credits
Type
integer
Description
환불 후 작업에 청구된 크레딧 수입니다. 오류를 반환하는 요청은 청구되지 않습니다. Meshy가 환불하므로 실패한 작업은 0입니다. 취소는 작업이 PENDING 상태일 때만 환불됩니다. Meshy가 청구 내역을 읽을 수 없는 경우, get 또는 스트림 응답에서는 해당 필드가 생략되며, 목록 요청은 500을 반환합니다. 이 경우 요청을 다시 시도하세요.
Name
prompt
Type
string
Description
피규어 빌드 작업에서는 항상 ""입니다.
Name
negative_prompt
Type
string
Description
prompt와 마찬가지로 피규어 빌드 작업에서는 항상 ""입니다.
Name
texture_prompt
Type
string
Description
prompt와 마찬가지로 피규어 빌드 작업에서는 항상 ""입니다.
Name
texture_image_url
Type
string
Description
prompt와 마찬가지로 피규어 빌드 작업에서는 항상 ""입니다.
Name
model_urls
Type
object
Description
텍스처가 적용된 GLB와, MTL 파일이 포함된 OBJ 파일로 제공되는 3D 모델의 다운로드 URL입니다.
- Name
  glb
  Type
  string
  Description
  텍스처가 적용된 GLB 파일의 다운로드 URL입니다.
- Name
  obj
  Type
  string
  Description
  지오메트리와 UV가 포함된 OBJ 파일의 다운로드 URL입니다.
- Name
  mtl
  Type
  string
  Description
  obj와 함께 사용되는 MTL 머티리얼 파일의 다운로드 URL입니다. obj와 texture_urls[0].base_color의 텍스처와 함께 사용하세요.
Name
thumbnail_url
Type
string
Description
모델 미리보기 이미지의 다운로드 URL입니다.
Name
texture_urls
Type
array
Description
텍스처 맵으로, 베이스 컬러 맵을 담은 객체 하나로 이루어진 배열입니다.
- Name
  base_color
  Type
  string
  Description
  베이스 컬러 맵의 다운로드 URL입니다.
Name
remove_lighting
Type
boolean
Description
Meshy가 베이스 컬러 텍스처에서 하이라이트와 그림자를 제거했는지 여부입니다.