Creative Lab Vinyl Figure API

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

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

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

Vinyl Figure 프로토타입 작업 생성

사진으로부터 vinyl-figure 스타일의 콘셉트 이미지를 하나 생성합니다. 3D 모델을 빌드하려면, 이 작업의 ID를 input_task_id로 빌드 엔드포인트에 전달하세요. 작업의 필드에 대해서는 The Vinyl Figure prototype task object를 참고하세요.

Request

POST

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

# Stage 1: generate a vinyl-figure-style concept image
curl https://api.meshy.ai/openapi/creative-lab/vinyl-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": "019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de"
}

Prototype example

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

Source photo used as the Creative Lab Vinyl Figure input — Prototype input

Big-head vinyl figure prototype image generated from the source photo — Prototype output

파라미터

Name
image_url
Type
string
필수
Description
빅헤드 vinyl figure로 변환할 사진으로, 공개 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 Filtering이 활성화되어 있으며, Meshy가 이미지를 제3자 지식재산권 문제로 플래그했습니다. 사용 권한이 있는 이미지를 보내세요.
Name
429 - Too Many Requests
Description
다음 제한 중 하나에 도달했습니다:
- 속도 제한을 초과하는 요청을 보냈습니다. 몇 초 기다린 후 다시 시도하세요. Rate limits를 참고하세요.
- 대기 중이거나 실행 중인 작업이 너무 많습니다. 일부가 완료될 때까지 기다린 후 다시 시도하세요.
- 크레딧이 남아 있지 않은 무제한 플랜에서, 크레딧 없이 실행할 수 있는 작업 수에 도달했습니다. 작업이 완료되기를 기다리거나 크레딧을 추가하세요.
Name
500 - Internal Server Error
Description
Meshy에서 서버 오류가 발생했습니다. 예를 들어 이미지에 대한 지식재산권 검사를 실행할 수 없었던 경우입니다. Meshy는 작업을 생성하지 않으며, 청구된 크레딧이 있다면 환불합니다. 요청을 다시 시도하세요.

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

비닐 피규어 빌드 작업 생성하기

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

Request

POST

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

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de"
  }'

Response

{
  "result": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef"
}

매개변수

Name
input_task_id
Type
string
필수
Description
빌드할 프로토타입 작업의 ID입니다. 이는 POST /openapi/creative-lab/vinyl-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/vinyl-figure/v1/(prototype|build)/:id

비닐 피규어 작업 가져오기

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

각 필드에 대한 설명은 비닐 피규어 prototype 작업 객체와 비닐 피규어 build 작업 객체를 참고하세요.

Request

GET

/openapi/creative-lab/vinyl-figure/v1/prototype/019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/prototype/019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/build/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de",
  "type": "creative-lab-vinyl-figure-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1752969600000,
  "started_at": 1752969604000,
  "finished_at": 1752969630000,
  "expires_at": 1753228830000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef",
  "type": "creative-lab-vinyl-figure-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1752969700000,
  "started_at": 1752969710000,
  "finished_at": 1752969735000,
  "expires_at": 1753228935000,
  "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/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/texture_0.png?Expires=***"
    }
  ]
}

매개변수

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

반환 값

경로의 단계와 일치하는 prototype 작업 객체 또는 build 작업 객체입니다.

실패 모드

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

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

비닐 피규어 작업 삭제

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

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

Request

DELETE

/openapi/creative-lab/vinyl-figure/v1/prototype/019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/prototype/019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de \
  -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를 가진 비닐 피규어 작업이 귀하의 계정에 존재하지 않거나, 작업의 단계가 경로와 일치하지 않습니다. ID를 확인하고 작업에 맞게 /prototype 또는 /build를 사용하세요.

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

Vinyl 피규어 작업 스트리밍

Vinyl 피규어 작업의 업데이트를 서버 전송 이벤트(SSE)로 스트리밍합니다. 경로는 작업의 단계와 일치해야 합니다. 예를 들어 build 작업의 ID로 /prototype/:id/stream을 호출하는 것처럼 일치하지 않으면, 스트림은 status_code: 404와 함께 하나의 error 이벤트를 전송하고 닫힙니다.

Request

GET

/openapi/creative-lab/vinyl-figure/v1/build/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/stream

curl -N https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/build/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/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": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef",
  "type": "creative-lab-vinyl-figure-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1752969700000,
  "started_at": 1752969710000,
  "finished_at": 1752969735000,
  "expires_at": 1753228935000,
  "task_error": null,
  "consumed_credits": 30,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/texture_0.png?Expires=***"
    }
  ]
}

매개변수

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

반환 값

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

IP Filtering이 작업 결과를 차단하면, 스트림은 그 자리에 하나의 error 이벤트를 전송하며, 이때의 status_code는 get 요청이 반환했을 값과 동일합니다.

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

Vinyl Figure 작업 목록 조회

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

Request

GET

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

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

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

Response (List Prototype Tasks)

[
  {
    "id": "019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de",
    "type": "creative-lab-vinyl-figure-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1752969600000,
    "started_at": 1752969604000,
    "finished_at": 1752969630000,
    "expires_at": 1753228830000,
    "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: 오래된순

반환값

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

비닐 피규어 프로토타입 작업 객체

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

속성

Example Vinyl Figure Prototype Task Object

{
  "id": "019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de",
  "type": "creative-lab-vinyl-figure-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1752969600000,
  "started_at": 1752969604000,
  "finished_at": 1752969630000,
  "expires_at": 1753228830000,
  "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-vinyl-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 Vinyl Figure Build Task Object

{
  "id": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef",
  "type": "creative-lab-vinyl-figure-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1752969700000,
  "started_at": 1752969710000,
  "finished_at": 1752969735000,
  "expires_at": 1753228935000,
  "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/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/texture_0.png?Expires=***"
    }
  ]
}

Name
id
Type
string
Description
작업 ID입니다. 형식에 의존하지 마세요.
Name
type
Type
string
Description
작업 유형이며, 항상 creative-lab-vinyl-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 또는 stream 응답에서는 이 필드가 생략되며, 목록 조회 요청은 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입니다.