Creative Lab — Collapsible Fidget API

원본 사진을 그 자리에서 바로 출력할 수 있는 접이식 피젯 장난감으로 바꿔줍니다: 대상의 실루엣이 여러 개의 겹쳐진 동심원 고리로 만들어져 평평하게 접히고 다시 늘어나며, 조립 없이 한 번에 통째로 출력됩니다.

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

다른 Creative Lab endpoint와 달리, 이 endpoint에는 프로토타입/빌드 단계 쌍이 없습니다 — 그중에서 고를 만한 중간 후보가 없으므로, 하나의 작업이 이미지를 처음부터 끝까지 3D 모델로 만들어 냅니다. 웹 앱에서 노출하는 지오메트리 제어 항목(크기, 레이어 수, 간격 너비, 벽 두께, 돌출 깊이, 불록함) 역시 요청에 포함되지 않습니다: 모든 작업은 동일한 서버 측 기본값으로 빌드됩니다.

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

접이식 피젯 태스크 생성하기

소스 사진으로부터 접이식 피젯 모델을 생성합니다. 응답 형태는 접이식 피젯 태스크 객체를 참고하세요.

각 태스크는 6 크레딧이 소요되며 유료 플랜이 필요합니다.

파라미터

Name
image_url
Type
string
필수
Description
Meshy가 접이식 피젯으로 변환할 소스 사진입니다. 현재 .jpg, .jpeg, .png, .webp 형식을 지원합니다.
이미지를 제공하는 방법은 두 가지입니다:
- 공개적으로 접근 가능한 URL: 공용 인터넷에서 접근 가능한 URL입니다.
- Data URI: 이미지를 base64로 인코딩한 data URI입니다. data URI 예시: data:image/jpeg;base64,<your base64-encoded image data>.
윤곽선이 하나로 명확하고 닫혀 있는 피사체가 가장 좋습니다 — 실루엣이 곧 링이 되기 때문입니다. 복잡한 배경, 여러 개의 분리된 피사체, 혹은 매우 얇은 형태는 중첩된 벽을 위한 공간이 부족해질 수 있으며, 이 경우 태스크는 태스크 오류와 함께 실패합니다.
Name
name
Type
string
Description
표시 용도의 선택적 태스크 이름입니다. 최대 100자입니다. 이는 태스크 라벨일 뿐이며, 모델에 새겨지는 것은 아닙니다.

반환값

응답의 result 속성에는 새로 생성된 접이식 피젯 태스크의 id가 담깁니다. 태스크 조회 엔드포인트를 폴링하거나 스트림을 구독하여 태스크가 SUCCEEDED에 도달할 때까지 기다린 후, model_urls.stl에서 인쇄 가능한 STL을 다운로드하세요 (미리 보고 싶다면 존재하는 경우 model_urls.glb에서 GLB도 함께 사용할 수 있습니다).

실패 모드

Name
400 - Bad Request
Description
요청이 허용되지 않았습니다. 일반적인 원인은 다음과 같습니다:
- 파라미터 누락: image_url은 필수입니다.
- 잘못된 이미지 형식: 제공된 image_url이 지원되는 형식(.jpg, .jpeg, .png, .webp)이 아닙니다.
- 이미지 크기 범위 초과: 이미지가 너무 작거나, 최대 파일 크기를 초과하거나, 최대 픽셀 수를 초과합니다.
- 접근 불가능한 URL: image_url을 다운로드할 수 없습니다 (404 또는 timeout).
- 잘못된 Data URI: base64 문자열의 형식이 올바르지 않습니다.
- 콘텐츠 플래그 처리됨: 입력 이미지가 NSFW moderation에 의해 플래그 처리되었습니다.
Name
401 - Unauthorized
Description
인증에 실패했습니다. API 키를 확인해 주세요.
Name
402 - Payment Required
Description
계정이 무료 플랜이거나(이 엔드포인트에서 태스크를 생성하려면 유료 플랜이 필요합니다), 크레딧이 부족합니다.
Name
403 - Forbidden
Description
입력 이미지가 지식재산권 침해로 플래그 처리되었습니다.
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다.

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

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

콜랩서블 피젯 작업 조회

유효한 작업 id가 주어지면 콜랩서블 피젯 작업을 조회합니다. 이 엔드포인트를 통해 생성된 작업만 여기서 조회할 수 있습니다 — 다른 Creative Lab 엔드포인트에서 생성되었거나 웹 앱에서 생성된 작업은 404를 반환합니다.

응답 형식에 대해서는 콜랩서블 피젯 작업 객체를 참고하세요.

매개변수

Name
id
Type
path
Description
조회할 콜랩서블 피젯 작업의 고유 식별자입니다.

반환값

응답에는 콜랩서블 피젯 작업 객체가 포함됩니다.

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=***"
  }
}

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

접이식 Fidget 작업 삭제

접이식 fidget 작업을 취소합니다. 작업이 아직 PENDING 상태인 경우, 생성 시 소모된 크레딧이 환불됩니다. 이미 IN_PROGRESS 상태인 작업은 환불 없이 취소됩니다 (워커가 이미 리소스를 소모하고 있을 수 있습니다). 이미 종료 상태 (SUCCEEDED, FAILED, CANCELED)에 도달한 작업은 취소할 수 없습니다.

경로 매개변수

Name
id
Type
path
Description
취소할 접이식 fidget 작업의 고유 식별자입니다.

반환값

성공 시 빈 본문과 함께 204 No Content를 반환합니다.

실패 모드

Name
400 - Bad Request
Description
작업이 이미 종료 상태이며 취소할 수 없습니다.
Name
404 - Not Found
Description
작업이 존재하지 않거나, 다른 사용자에게 속해 있거나, 이 엔드포인트를 통해 생성되지 않았습니다.

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).

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

콜랩시블 피젯 작업 스트리밍

Server-Sent Events(SSE)를 통해 콜랩시블 피젯 작업의 실시간 업데이트를 스트리밍합니다. 존재하지 않는 작업이나 이 엔드포인트를 통해 생성되지 않은 작업의 경우 status_code: 404가 포함된 단일 event: error 페이로드를 전송하고 스트림을 닫습니다.

매개변수

Name
id
Type
path
Description
스트리밍할 콜랩시블 피젯 작업의 고유 식별자입니다.

반환값

콜랩시블 피젯 작업 객체의 스트림을 Server-Sent Events로 반환합니다. 각 프레임은 해당 단계의 전체 작업 객체를 담고 있으며 — Get 엔드포인트가 반환하는 것과 동일한 형태입니다 — 따라서 작업이 PENDING 또는 IN_PROGRESS 상태인 동안에는 출력 필드가 아직 채워지지 않은 상태(null, [] 또는 {})이며 finished_at은 null입니다.

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 PENDING frame below is abbreviated 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=***"
  }
}

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

접이식 피젯 작업 목록 조회

사용자의 접이식 피젯 작업 목록을 페이지네이션 형태로 가져옵니다. 이 엔드포인트를 통해 생성된 작업만 포함됩니다.

쿼리 매개변수

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

반환값

접이식 피젯 작업 객체의 페이지네이션 목록을 반환합니다.

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=***"
    }
  }
]

The Collapsible Fidget Task Object

The Collapsible Fidget Task object는 원본 사진을 접이식(collapsible) 프린트-인-플레이스 피젯 모델로 변환하기 위해 Meshy가 추적하는 작업 단위입니다. 이 작업은 단일 단계 작업이며, 이어받을 프로토타입이 없고 중간 실루엣은 응답에 포함되지 않습니다.

Properties

Name
id
Type
string
Description
작업의 고유 식별자입니다. 구현 세부사항으로서 작업 id에 k-정렬 가능한 UUID를 사용하지만, id의 형식에 대해 어떠한 가정도 하지 않아야 합니다.
Name
type
Type
string
Description
작업의 유형입니다. 값은 creative-lab-fidget-collapsible입니다.
Name
name
Type
string
Description
작업 생성 시 제공된 작업 이름입니다. 이름이 제공되지 않은 경우 빈 문자열입니다.
Name
status
Type
string
Description
작업의 상태입니다. 가능한 값은 PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED 중 하나입니다.
Name
progress
Type
integer
Description
작업의 progress입니다. 작업이 아직 시작되지 않은 경우 이 속성은 0이 됩니다. 작업이 성공하면 100이 됩니다.
Name
created_at
Type
timestamp
Description
작업이 생성된 시각의 타임스탬프(밀리초 단위)입니다.
타임스탬프는 RFC 3339 표준을 따라 1970년 1월 1일 UTC 이후 경과한 밀리초 수를 나타냅니다. 예를 들어, 2023년 9월 1일 금요일 12:00:00 PM GMT는 1693569600000으로 표현됩니다. 이는 Meshy API의 모든 타임스탬프에 적용됩니다.
Name
started_at
Type
timestamp
Description
작업이 시작된 시각의 타임스탬프(밀리초 단위)입니다. 작업이 아직 시작되지 않은 경우 이 속성은 null이 됩니다.
Name
finished_at
Type
timestamp
Description
작업이 완료된 시각의 타임스탬프(밀리초 단위)입니다. 작업이 아직 완료되지 않은 경우 이 속성은 null이 됩니다.
Name
expires_at
Type
timestamp
Description
작업 결과가 만료되는 시각의 타임스탬프(밀리초 단위)입니다.
Name
preceding_tasks
Type
integer
Description
선행 작업의 수입니다.
이 필드의 값은 작업 상태가 PENDING일 때만 의미가 있습니다.
Name
task_error
Type
object
Description
실패한 작업에 대한 오류 세부 정보입니다. task_error 객체의 전체 참조는 오류를 참조하세요.
Name
consumed_credits
Type
integer
Description
이 작업에서 소비된 크레딧 수입니다. 작업 상태가 PENDING, IN_PROGRESS, SUCCEEDED일 때 존재합니다. FAILED 작업의 경우 0을 반환합니다(실패 시 크레딧은 환불됩니다).
Name
model_urls
Type
object
Description
생성된 3D 모델의 다운로드 가능한 URL입니다. 작업이 SUCCEEDED 상태가 되면 채워집니다: stl은 항상 존재하며, glb는 미리보기 렌더링이 성공한 경우에만 존재합니다.
- Name
  stl
  Type
  string
  Description
  STL 파일의 다운로드 가능한 URL입니다. 이는 인쇄 가능한 최종 산출물이므로, 곧바로 슬라이서로 전송하면 됩니다.
- Name
  glb
  Type
  string
  Description
  3D 뷰어에서 모델을 미리 보기 위한 GLB 파일의 다운로드 가능한 URL입니다. 색상은 미리보기 전용입니다: STL은 색상 정보를 포함하지 않으며, 인쇄된 피젯은 필라멘트에서 색상을 얻습니다. GLB는 최선의 노력으로 제공되는 항목이므로, 미리보기 렌더링을 사용할 수 없는 경우 키가 model_urls에서 완전히 생략됩니다. 따라서 이를 방어적으로 읽어야 합니다 — stl이 최종 산출물이며 SUCCEEDED 작업에는 항상 존재합니다.

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=***"
  }
}