Creative Lab Collapsible Fidget API

사진을 한 번의 작업으로 조립 없이 출력 가능한 접이식 피젯 장난감으로 변환합니다. 피사체의 실루엣은 평평하게 접히거나 다시 펼쳐지는 중첩된 동심원 고리가 됩니다. 이 장난감은 별도의 조립 없이 한 번에 출력됩니다.

POST /openapi/creative-lab/fidget-collapsible/v1

다른 Creative Lab endpoint와 달리, 이 endpoint는 별도의 prototype 단계와 build 단계가 없습니다. 선택할 후보 이미지도 없으며, 하나의 작업으로 사진을 3D 모델로 변환합니다.

요청에는 지오메트리 설정도 포함되어 있지 않습니다. 웹 앱에서는 크기, 레이어 수, 간격 너비, 벽 두께, 돌출 깊이, 부풀림 정도를 설정할 수 있습니다. 모든 API 작업은 이러한 값에 대해 동일한 기본값을 사용합니다.

POST/openapi/creative-lab/fidget-collapsible/v1

콜랩시블 피젯 작업 생성

사진으로부터 콜랩시블 피젯 모델을 생성합니다. 작업의 필드에 대해서는 콜랩시블 피젯 작업 객체를 참고하세요.

작업 1건당 6크레딧이 소요되며, 유료 플랜이 필요합니다.

Request

POST

/openapi/creative-lab/fidget-collapsible/v1

curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1 \
  -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"
}

매개변수

Name
image_url
Type
string
필수
Description
콜랩시블 피젯으로 변환할 사진으로, 공개 URL 또는 데이터 URI(data:image/jpeg;base64,<your base64-encoded image data>)로 지정합니다.
이미지는 최대 20MB의 JPG, JPEG, PNG, 또는 WebP 파일이어야 합니다.
피사체의 실루엣이 고리 모양이 되므로, 하나의 명확하고 닫힌 윤곽선을 가진 피사체가 가장 잘 작동합니다. 배경이 복잡하거나 피사체가 여러 개로 분리되어 있거나 형태가 매우 얇으면 중첩된 벽을 만들 공간이 부족할 수 있습니다. 이 경우 작업이 실패합니다.
Name
name
Type
string
Description
작업의 이름으로, 최대 100자까지 입력할 수 있습니다. 이 값은 작업의 name 필드로 반환되며, Meshy가 모델에 이를 새기지는 않습니다. 더 긴 이름을 지정하면 400이 반환됩니다.

반환 값

result 필드에는 새 작업의 ID가 담깁니다. status가 SUCCEEDED가 될 때까지 작업을 조회하거나 스트리밍하세요. 그런 다음 model_urls.stl에서 출력 가능한 STL 파일을 다운로드합니다. 모델을 먼저 미리 보려면 model_urls.glb가 존재할 때 해당 GLB 파일을 다운로드하세요.

실패 모드

Name
400 - Bad Request
Description
요청을 실행할 수 없습니다. 예를 들면:
- image_url이 누락된 경우.
- 이미지가 JPG, JPEG, PNG, 또는 WebP 파일이 아닌 경우.
- 이미지가 너무 작거나, 20MB를 초과하거나, 최대 픽셀 수를 초과한 경우.
- Meshy가 이미지를 다운로드할 수 없는 경우, 예를 들어 URL이 404를 반환하거나 시간 초과가 발생한 경우.
- 데이터 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는 작업을 생성하지 않으며, 청구된 크레딧이 있다면 환불합니다. 요청을 다시 시도하세요.

GET/openapi/creative-lab/fidget-collapsible/v1/:id

Collapsible Fidget 작업 가져오기

Collapsible Fidget 작업을 반환합니다. 이 엔드포인트로 생성된 작업만 반환됩니다. 다른 Creative Lab 엔드포인트에서 생성된 작업이나 웹 앱에서 생성된 작업은 404를 반환합니다.

필드에 대한 내용은 The Collapsible Fidget task object를 참조하세요.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

매개변수

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

반환값

Collapsible Fidget task object입니다.

실패 모드

Name
400 - Bad Request
Description
id가 유효한 작업 ID가 아닙니다. 생성 응답의 result ID를 전송하세요.
Name
403 - Forbidden
Description
팀에서 IP Filtering이 켜져 있고, Meshy가 작업의 이미지를 제3자 지식재산권 문제로 플래그 처리했습니다. Enterprise 플랜을 사용하는 팀은 이 오류가 발생하지 않습니다. 사용 권한이 있는 이미지로 작업을 생성하세요.
Name
404 - Not Found
Description
이 ID를 가진 Collapsible Fidget 작업이 계정에 없거나, 해당 작업이 이 엔드포인트로 생성되지 않았습니다. ID를 확인하세요.
Name
500 - Internal Server Error
Description
Meshy가 지식재산권 확인을 실행하지 못했습니다. 요청을 다시 시도하세요.

DELETE/openapi/creative-lab/fidget-collapsible/v1/:id

Collapsible Fidget 작업 삭제

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

Request

DELETE

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/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를 가진 Collapsible Fidget 작업이 계정에 없거나, 해당 작업이 이 엔드포인트로 생성되지 않았습니다. ID를 확인하세요.

GET/openapi/creative-lab/fidget-collapsible/v1/:id/stream

접이식 Fidget 작업 스트리밍

접이식 Fidget 작업의 업데이트를 Server-Sent Events(SSE)로 스트리밍합니다. 작업이 존재하지 않거나 이 엔드포인트로 생성되지 않은 경우, 스트림은 status_code: 404가 포함된 error 이벤트를 한 번 전송하고 종료됩니다.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (task not found, or not created through this endpoint)
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": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

매개변수

Name
id
Type
path
Description
생성 응답에서 제공된 작업 ID입니다.

반환 값

접이식 Fidget 작업 객체의 스트림입니다. 각 이벤트는 접이식 Fidget 작업 조회가 반환하는 것과 동일한 전체 작업 객체를 포함합니다. 작업이 PENDING 또는 IN_PROGRESS 상태인 동안에는 출력 필드가 여전히 비어 있으며(null, [], 또는 {}), finished_at은 null입니다.

IP 필터링이 작업 결과를 차단하는 경우, 스트림은 해당 자리에 get 요청이 반환했을 status_code를 포함한 error 이벤트를 한 번 전송합니다.

GET/openapi/creative-lab/fidget-collapsible/v1

Collapsible Fidget 작업 목록 조회

사용자의 Collapsible Fidget 작업을 한 번에 한 페이지씩 반환합니다. 이 엔드포인트로 생성된 작업만 포함됩니다.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-fidget-collapsible",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123512000,
    "expires_at": 1729382712000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
    }
  }
]

쿼리 매개변수

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: 오래된순

반환값

Collapsible Fidget 작업 객체의 배열입니다.

접이식 피젯 작업 객체

접이식 피젯(Collapsible Fidget) 작업은 사진을 출력 즉시 사용 가능한 접이식 피젯 모델로 변환합니다. 이는 단일 단계 작업이므로 체인으로 연결할 프로토타입 작업이 없습니다. 응답에는 Meshy가 작업 도중 생성하는 실루엣이 포함되지 않습니다.

Properties

Example Collapsible Fidget Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

Name
id
Type
string
Description
작업 ID입니다. 이 형식에 의존하지 마세요.
Name
type
Type
string
Description
작업 유형으로, 항상 creative-lab-fidget-collapsible입니다.
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
model_urls
Type
object
Description
3D 모델의 다운로드 URL로, 작업이 성공하기 전까지는 비어 있습니다. 성공한 작업은 항상 stl을 가지며, Meshy가 미리보기를 렌더링한 경우에만 glb를 갖습니다.
- Name
  stl
  Type
  string
  Description
  STL 파일의 다운로드 URL로, 출력에 사용할 파일입니다. 슬라이서에서 바로 열 수 있습니다.
- Name
  glb
  Type
  string
  Description
  3D 뷰어에서 모델을 미리 볼 수 있는 GLB 파일의 다운로드 URL입니다. 색상은 미리보기 용도로만 사용됩니다. STL 파일에는 색상이 없으므로, 출력된 피젯의 색상은 필라멘트의 색상을 따릅니다.
  Meshy가 미리보기를 렌더링할 수 없는 경우, model_urls에 glb 키가 없으므로 읽기 전에 키의 존재 여부를 확인하세요. SUCCEEDED 작업은 항상 stl을 가집니다.