Creative Lab — Fidget Pixel API

원본 사진을 다양한 색상의 3D 프린팅 가능한 픽셀 아트 피젯 보드로 변환하는 작업은 두 단계로 진행됩니다. 프로토타입 단계는 사진을 픽셀 아트 이미지로 변환하고, 빌드 단계는 해당 이미지를 16×16 또는 32×32 격자에 샘플링하여 각 픽셀을 맞물리는 정사각형 또는 육각형 조각으로 변환한 후, 각 오브젝트가 색상 정보를 담고 있는 단일 3MF 파일로 제공되므로 다중 필라멘트 슬라이서가 각 조각을 올바른 색상으로 출력할 수 있습니다. 두 단계는 input_task_id를 통해 연결됩니다.

POST /openapi/creative-lab/fidget-pixel/v1/prototype
POST /openapi/creative-lab/fidget-pixel/v1/build

두 POST 엔드포인트 모두 유료 구독 플랜이 필요합니다. 무료 플랜 계정에서의 요청은 402 Payment Required로 거부됩니다.

POST/openapi/creative-lab/fidget-pixel/v1/prototype

Create a Fidget Pixel Prototype Task

소스 사진으로부터 단일 픽셀 아트 이미지를 생성합니다. 반환된 작업 ID는 build 엔드포인트에 input_task_id로 전달하는 값입니다. 결과가 원하는 대로 나오지 않으면 다른 결과를 얻기 위해 이 엔드포인트를 다시 호출하세요 — 각 호출은 별도로 과금됩니다. 응답 형태에 대해서는 The Fidget Pixel Prototype Task Object 를 참고하세요.

파라미터

Name
image_url
Type
string
필수
Description
Meshy가 픽셀화할 소스 사진입니다. 현재 .jpg, .jpeg, .png, .webp 형식을 지원합니다.
형식은 이미지 데이터를 디코딩하여 감지되며, URL의 파일 확장자로 감지되지 않습니다 — 확장자가 없는 URL이나 리다이렉트되는 URL도 바이트가 지원되는 형식으로 디코딩되기만 하면 정상적으로 동작합니다. HTTP 리다이렉트는 따라갑니다.
이미지를 제공하는 방법은 두 가지입니다:
- 공개적으로 접근 가능한 URL: 공용 인터넷에서 접근 가능한 URL입니다.
- Data URI: 이미지의 base64로 인코딩된 data URI입니다. data URI의 예: data:image/jpeg;base64,<your base64-encoded image data>.
Name
type
Type
string
필수
Description
사진이 무엇을 보여주는지를 나타냅니다. 픽셀화 스타일을 결정하므로 신중하게 선택하세요 — 두 값은 눈에 띄게 다른 결과를 만들어냅니다. 사용 가능한 값:
- person — 피사체가 사람(인물 사진 또는 전신)인 경우. 피사체의 치비 스타일 픽셀 스프라이트를 생성합니다.
- other — 그 외 모든 것: 반려동물, 사물, 마스코트, 로고, 풍경. 피사체의 비즈 아트 스타일 픽셀 아이콘을 생성합니다.
Name
name
Type
string
Description
표시용 선택적 작업 이름입니다. 최대 100자입니다.

반환값

응답의 result 속성에는 새로 생성된 fidget pixel prototype 작업의 id가 포함됩니다. Get a Task 엔드포인트를 폴링하거나 stream을 구독하여 작업이 SUCCEEDED 상태에 도달할 때까지 기다린 다음, 해당 ID를 build 엔드포인트에 input_task_id로 전달하세요.

실패 모드

Name
400 - Bad Request
Description
요청을 수락할 수 없습니다. 일반적인 원인:
- 파라미터 누락: image_url과 type은 모두 필수입니다.
- 잘못된 type: type은 person 또는 other여야 합니다.
- 잘못된 이미지 형식: 제공된 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
이 작업을 수행하기에 크레딧이 부족하거나, API 키가 무료 요금제 계정에 속해 있습니다.
Name
403 - Forbidden
Description
입력 이미지가 지식재산권 moderation에 의해 플래그되었습니다 (Content flagged for intellectual property violation). 지식재산권 필터링이 활성화된 Enterprise 계정만 차단되며, 아무것도 과금되지 않습니다.
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다.
Name
500 - Internal Server Error
Description
지식재산권 검사 자체를 완료할 수 없습니다 (Unable to perform intellectual property check, please try again). 지식재산권 필터링이 활성화된 Enterprise 계정은 이 검사에서 실패 시 안전하게 차단되며, 아무것도 과금되지 않습니다 — 요청을 다시 시도하세요.

Request

POST

/openapi/creative-lab/fidget-pixel/v1/prototype

# Stage 1: pixelize the source photo
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/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>",
    "type": "person"
  }'

Response

{
  "result": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7"
}

POST/openapi/creative-lab/fidget-pixel/v1/build

Fidget Pixel 빌드 태스크 생성

성공한 프로토타입 태스크로부터 3D 프린팅 가능한 조각들을 생성합니다. 빌드는 프로토타입의 픽셀 아트 이미지를 요청된 그리드에 샘플링하고, 최대 color_count개의 색상으로 양자화한 뒤, 그리드 셀마다 서로 맞물리는 조각을 하나씩 생성합니다. 결과물은 단일 3MF 파일이며, 그 안의 모든 조각은 각각의 색상이 태그된 별도의 오브젝트로 존재하여 멀티 필라멘트 슬라이서에서 바로 사용할 수 있습니다. 응답 형태에 대해서는 Fidget Pixel 빌드 태스크 객체를 참고하세요.

파라미터

Name
input_task_id
Type
string
필수
Description
동일한 OpenAPI 엔드포인트를 통해 생성된 프로토타입 태스크의 태스크 ID입니다. 프로토타입은 동일한 Meshy 계정으로 생성되었어야 하며 SUCCEEDED 상태에 도달했어야 합니다.
webapp을 통해 생성된 프로토타입 태스크는 허용되지 않습니다 — 빌드 엔드포인트는 POST /openapi/creative-lab/fidget-pixel/v1/prototype으로 생성된 프로토타입 태스크만 허용하며, 그 외의 출처는 404로 거부합니다.
Name
name
Type
string
Description
표시용 선택적 태스크 이름입니다. 최대 100자입니다.

`options`

선택적 조각 지오메트리입니다. 모든 필드에는 기본값이 있으므로 재정의하려는 값만 전송하면 됩니다. 이는 Creative Lab webapp에서 노출하는 것과 동일한 컨트롤이며, 플러그 높이, 캡 스케일 및 기타 제조 프리셋은 shape와 piece_size_mm로부터 파생되며 별도로 노출되지 않습니다.

Name
shape
Type
string
기본값 square
Description
각 조각의 형태입니다. 사용 가능한 값:
- square (기본값) — 정사각형 그리드 위의 정사각형 조각.
- hex — 육각형 그리드 위의 육각형 조각. 육각형 조각은 6 및 8 mm에서만 사용할 수 있습니다.
Name
grid_size
Type
integer
기본값 32
Description
보드의 각 변을 따라 배치되는 조각의 수입니다. 사용 가능한 값: 16 또는 32. 32 그리드는 더 많은 디테일을 유지하며, 16 그리드는 동일한 대상에 대해 더 적고 큰 조각을 의미합니다.
Name
piece_size_mm
Type
integer
기본값 8
Description
각 조각의 변 길이(밀리미터)입니다. 사용 가능한 값: 6, 8, 또는 10. grid_size와 함께 이 값은 인쇄된 보드 크기를 결정합니다 — 예를 들어 32 × 8 mm ≈ 한 변당 26 cm. shape: "hex"의 경우 10은 사용할 수 없습니다(경사진 육각형 면이 대부분의 소비자용 FDM 프린터에서 오버행을 발생시키기 때문입니다).
Name
color_count
Type
integer
기본값 8
Description
이미지가 양자화되는 팔레트의 최대 색상 수입니다. 범위: [1, 8]. 각 색상은 슬라이서에서 하나의 필라멘트가 됩니다.
Name
piece_height_mm
Type
integer
기본값 15
Description
각 조각의 높이(밀리미터)입니다. 범위: [10, 80].

`output`

선택적 출력 형식 선택기입니다. 기본값은 3mf이며, 현재로서는 유일하게 지원되는 값입니다.

Name
format
Type
string
기본값 3mf
Description
빌드가 반환하는 산출물입니다. 사용 가능한 값:
- 3mf (기본값) — model_urls.3mf에 단일 model.3mf를 반환하며, 조각마다 하나의 오브젝트가 있고 각 오브젝트에는 조각 색상이 첨부되어 있습니다.

반환값

응답의 result 속성에는 새로 생성된 fidget pixel 빌드 태스크의 태스크 id가 포함됩니다. 태스크 가져오기 엔드포인트를 폴링하거나 스트림을 구독하여 태스크가 SUCCEEDED에 도달할 때까지 기다린 다음, model_urls.3mf에서 산출물을 다운로드하세요.

실패 모드

Name
400 - Bad Request
Description
요청이 허용되지 않았습니다. 일반적인 원인:
- 파라미터 누락: input_task_id가 필요합니다.
- 유효하지 않은 UUID: input_task_id가 유효한 UUID가 아닙니다.
- 부모 태스크가 성공하지 않음: 참조된 프로토타입 태스크가 아직 SUCCEEDED에 도달하지 않았습니다.
- 후보 없음: 프로토타입 태스크는 성공했지만 픽셀 아트 이미지를 생성하지 못했습니다; 새 프로토타입을 생성하세요.
- 옵션 범위 초과: options 필드 중 하나가 허용된 집합 또는 범위를 벗어났습니다 — 예를 들어 options.grid_size must be 16 or 32, 또는 options.piece_size_mm=10 is not supported for shape=hex; hex pieces are available in 6 and 8 mm.
- 지원되지 않는 형식: output.format은 3mf이어야 합니다.
Name
401 - Unauthorized
Description
인증에 실패했습니다. API 키를 확인해 주세요.
Name
402 - Payment Required
Description
이 태스크를 수행하기에 크레딧이 부족하거나, API 키가 무료 플랜 계정에 속해 있습니다.
Name
403 - Forbidden
Description
참조된 프로토타입의 이미지가 지적 재산권 moderation에 의해 플래그되었습니다. 지적 재산권 필터링이 활성화된 Enterprise 계정만 차단되며, 아무것도 청구되지 않습니다.
Name
404 - Not Found
Description
참조된 프로토타입 태스크가 존재하지 않거나, 다른 사용자에게 속해 있거나, webapp을 통해 생성되었습니다(오직 API 모드 프로토타입 태스크만 빌드로 연결됩니다).
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다.
Name
500 - Internal Server Error
Description
참조된 프로토타입의 지적 재산권 판정을 확립할 수 없었습니다(Unable to perform intellectual property check, please try again). 지적 재산권 필터링이 활성화된 Enterprise 계정은 이 검사에서 실패 시 요청을 차단합니다(fail closed); 아무것도 청구되지 않으니 요청을 다시 시도하세요.

Request

POST

/openapi/creative-lab/fidget-pixel/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
    "options": {
      "shape": "square",
      "grid_size": 32,
      "piece_size_mm": 8,
      "color_count": 8,
      "piece_height_mm": 15
    },
    "output": {
      "format": "3mf"
    }
  }'

Response

{
  "result": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98"
}

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

Fidget Pixel 작업 조회하기

유효한 작업 id가 주어지면 프로토타입 또는 빌드 작업을 조회합니다. URL 경로는 작업의 단계와 일치해야 합니다 — /prototype/:id를 통해 조회한 빌드 작업은 404를 반환하며, 그 반대의 경우도 마찬가지입니다.

응답 형태에 대해서는 Fidget Pixel 프로토타입 작업 객체와 Fidget Pixel 빌드 작업 객체를 참고하세요.

매개변수

Name
id
Type
path
Description
조회할 fidget pixel 작업의 고유 식별자입니다.

반환값

응답에는 fidget pixel 작업 객체가 포함됩니다. 그 형태는 어느 단계가 요청되었는지에 따라 달라집니다.

실패 모드

Name
400 - Bad Request
Description
id가 유효한 UUID가 아닙니다 (Invalid ID).
Name
403 - Forbidden
Description
해당 작업의 이미지가 지적 재산권 모더레이션에 의해 플래그 처리되었습니다. 지적 재산권 필터링이 활성화된 Enterprise 계정만 차단됩니다.
Name
404 - Not Found
Description
작업이 존재하지 않거나, 다른 사용자에게 속해 있거나, 해당 단계가 URL 경로와 일치하지 않습니다.
Name
500 - Internal Server Error
Description
지적 재산권 검사를 완료할 수 없습니다 (Unable to perform intellectual property check, please try again). 지적 재산권 필터링이 활성화된 Enterprise 계정은 실패 시 요청을 차단 처리합니다. 요청을 재시도하세요.

Request

GET

/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
  "type": "creative-lab-fidget-pixel-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001000000,
  "started_at": 1757001005000,
  "finished_at": 1757001178000,
  "expires_at": 1757260378000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
  ]
}

Build Response

{
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

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

Fidget Pixel 작업 삭제

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

URL 경로는 작업의 단계와 일치해야 합니다 — /prototype/:buildId에 대한 DELETE는 404를 반환합니다.

경로 매개변수

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

반환값

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

실패 모드

Name
400 - Bad Request
Description
요청이 허용되지 않았습니다. 일반적인 원인:
- 잘못된 ID: id가 유효한 UUID가 아닙니다.
- 종료 상태: 작업이 이미 SUCCEEDED, FAILED 또는 CANCELED 상태이므로 취소할 수 없습니다.
Name
404 - Not Found
Description
작업이 존재하지 않거나, 다른 사용자에게 속해 있거나, 해당 단계가 URL 경로와 일치하지 않습니다.

Request

DELETE

/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

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

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

Fidget Pixel 작업 스트리밍

Server-Sent Events(SSE)를 통해 fidget pixel 작업의 실시간 업데이트를 스트리밍합니다. URL 경로는 작업의 단계와 일치해야 합니다 — /prototype/:buildId/stream에서 스트림을 열면 status_code: 404와 함께 단일 event: error 페이로드가 발생하고 스트림이 닫히며, 잘못된 형식의 id도 status_code: 400(Invalid ID)과 함께 동일하게 동작합니다.

매개변수

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

반환값

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

Request

GET

/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/stream

curl -N https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/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 for the stage; fields not yet populated are null / empty.
event: message
data: {
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "PENDING",
  "progress": 0,
  "created_at": 1757001300000,
  "started_at": null,
  "finished_at": null,
  "expires_at": 1757260500000,
  "preceding_tasks": 2,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {}
}

event: message
data: {
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

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

Fidget Pixel 작업 목록 조회

단일 단계에 대한 fidget pixel 작업의 페이지네이션된 목록을 조회합니다. URL 경로가 단계를 선택합니다 — /prototype은 prototype 작업을 반환하고, /build는 build 작업을 반환합니다. 다른 단계의 작업은 어느 응답에도 포함되지 않습니다.

경로 매개변수

Name
stage
Type
path
필수
Description
prototype 또는 build 중 하나입니다. 컬렉션은 URL과 일치하는 단계의 작업만 반환합니다 — /prototype을 가져오면 build 작업이 반환되지 않으며, 그 반대도 마찬가지입니다.

쿼리 매개변수

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: 생성 시간 내림차순으로 정렬합니다.

반환값

단계별 작업 객체의 페이지네이션된 목록을 반환합니다 — /prototype을 조회할 때는 the fidget pixel prototype task object, /build를 조회할 때는 the fidget pixel build task object입니다.

Request

GET

/openapi/creative-lab/fidget-pixel/v1/prototype

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

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

Response (List Prototype Tasks)

[
  {
    "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
    "type": "creative-lab-fidget-pixel-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1757001000000,
    "started_at": 1757001005000,
    "finished_at": 1757001178000,
    "expires_at": 1757260378000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
    ]
  }
]

Fidget Pixel Prototype Task 객체

Fidget Pixel Prototype Task 객체는 소스 사진을 픽셀 아트 이미지로 픽셀화하기 위해 Meshy가 추적하는 작업 단위입니다. 이 단계의 출력은 input_task_id를 통해 빌드 단계로 연결됩니다.

속성

Name
id
Type
string
Description
작업의 고유 식별자입니다. 구현 세부사항으로는 k-정렬 가능한 UUID를 작업 id에 사용하지만, id의 형식에 대해 어떠한 가정도 해서는 안 됩니다.
Name
type
Type
string
Description
작업의 유형입니다. 값은 creative-lab-fidget-pixel-prototype입니다.
Name
name
Type
string
Description
작업이 생성될 때 제공된 작업 이름입니다. 이름이 제공되지 않은 경우 빈 문자열입니다.
Name
status
Type
string
Description
작업의 상태입니다. 가능한 값은 PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED 중 하나입니다.
Name
progress
Type
integer
Description
작업의 진행 상황입니다. 작업이 아직 시작되지 않은 경우 이 속성은 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
작업 결과가 만료되는 시점의 타임스탬프이며, 밀리초 단위로, 작업이 완료된 후 3일입니다. 엔터프라이즈 계정은 API 결과를 무기한 보관하며(자세한 내용은 에셋 보존 참조), 이 경우 이 타임스탬프는 약 100년 후로 설정됩니다.
Name
preceding_tasks
Type
integer
Description
선행 작업의 개수입니다.
이 필드의 값은 작업 상태가 PENDING인 경우에만 의미가 있습니다.
Name
task_error
Type
object
Description
실패한 작업에 대한 오류 세부 정보입니다. 전체 task_error 객체 참조는 오류를 참조하세요.
Name
consumed_credits
Type
integer
Description
이 작업에서 소비된 크레딧 수입니다. SUCCEEDED에 도달한 작업은 해당 단계의 전체 금액이 청구됩니다. 생성조차 되지 않은 작업(요청 시점의 4xx, moderation 거부 포함)은 전혀 청구되지 않습니다. FAILED에 도달한 작업은 0을 반환합니다 — 요금이 환불됩니다. DELETE를 통한 취소는 작업이 아직 PENDING 상태인 경우에만 환불되며, 이미 IN_PROGRESS 상태인 작업은 작업이 이미 소비되었기 때문에 요금이 계속 청구됩니다.
Name
image_urls
Type
array of strings
Description
이 prototype 작업으로 생성된 픽셀 아트 이미지의 다운로드 가능한 URL입니다. 현재 API는 항상 정확히 하나의 이미지를 반환하지만, 이 필드는 향후 개정에서 호환성을 깨지 않고 여러 후보를 제공할 수 있도록 배열로 되어 있습니다. 작업이 SUCCEEDED에 도달하기 전까지는 비어 있습니다.
이것들은 서명된 URL입니다. Authorization 헤더 없이 가져와야 합니다. finished_at 이후 3일인 expires_at까지 유효하며, 이 기간 내에 작업을 다시 읽으면 새로 서명된 URL이 아닌 동일한 URL이 반환됩니다. 그 전에 직접 파일을 다운로드하여 저장하세요 — 만료된 링크를 새로 고칠 방법은 없습니다.

Example Fidget Pixel Prototype Task Object

{
  "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
  "type": "creative-lab-fidget-pixel-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001000000,
  "started_at": 1757001005000,
  "finished_at": 1757001178000,
  "expires_at": 1757260378000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
  ]
}

Fidget Pixel 빌드 태스크 객체

Fidget Pixel 빌드 태스크 객체는 성공한 프로토타입 태스크로부터 출력 가능한 조각을 생성하기 위해 Meshy가 추적하는 작업 단위입니다. 빌드는 프로토타입의 픽셀 아트 이미지를 요청된 그리드에 샘플링하여 색상이 태그된 단일 3MF를 게시합니다.

속성

Name
id
Type
string
Description
태스크의 고유 식별자입니다.
Name
type
Type
string
Description
태스크의 유형입니다. 값은 creative-lab-fidget-pixel-build입니다.
Name
name
Type
string
Description
태스크가 생성될 때 제공된 태스크 이름입니다. 이름이 제공되지 않은 경우 빈 문자열입니다.
Name
status
Type
string
Description
태스크의 상태입니다. 가능한 값은 PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED 중 하나입니다.
Name
progress
Type
integer
Description
태스크의 진행 상황입니다. 태스크가 아직 시작되지 않은 경우 이 속성은 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
태스크 결과가 만료되는 시각의 타임스탬프이며, 밀리초 단위입니다 — 태스크가 완료된 후 3일입니다. Enterprise 계정은 API 결과를 무기한 보관합니다(에셋 보존 참조). 이 경우 이 타임스탬프는 약 100년 후로 설정됩니다.
Name
preceding_tasks
Type
integer
Description
선행 태스크의 개수입니다. 상태가 PENDING일 때만 의미가 있습니다.
Name
task_error
Type
object
Description
실패한 태스크에 대한 오류 세부 정보입니다. 전체 task_error 객체 참조는 오류를 참고하세요.
Name
consumed_credits
Type
integer
Description
이 태스크에서 소비된 크레딧 수입니다. SUCCEEDED에 도달한 태스크는 해당 단계의 전체 금액이 청구됩니다. 생성되지 않은 태스크(요청 시점의 4xx, moderation 거부 포함)는 전혀 청구되지 않습니다. FAILED에 도달한 태스크는 0을 반환합니다 — 청구된 금액이 환불됩니다. DELETE를 통한 취소는 태스크가 아직 PENDING인 동안에만 환불되며, 이미 IN_PROGRESS 상태인 태스크는 작업이 이미 소비되었으므로 계속 청구됩니다.
Name
model_urls
Type
object
Description
생성된 산출물에 대한 다운로드 가능한 URL이며, 형식별로 키가 지정됩니다. 빌드 요청의 output.format을 통해 요청된 형식 하나만 정확히 포함합니다. 태스크가 SUCCEEDED에 도달하기 전까지는 비어 있습니다.
이는 서명된 URL입니다. Authorization 헤더 없이 가져오세요. 이 URL은 finished_at으로부터 3일 후인 expires_at까지 유효하며, 그 기간 내에 태스크를 다시 읽으면 새로 서명된 URL이 아니라 동일한 URL이 반환됩니다. 만료되기 전에 직접 파일을 다운로드하여 저장하세요 — 만료된 링크를 새로고침할 방법은 없습니다.
- Name
  3mf
  Type
  string
  Description
  3MF 파일에 대한 다운로드 가능한 URL입니다. 조각마다 하나의 객체가 있으며, 각 객체는 팔레트 색상으로 태그되어 있어 멀티 필라멘트 슬라이서가 색상별로 필라멘트를 할당할 수 있습니다. output.format이 3mf(기본값)였을 때 존재합니다.

Example Fidget Pixel Build Task Object

{
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

End-to-End Example

전체 흐름은 다음과 같습니다: 사진으로부터 프로토타입을 생성하고, SUCCEEDED 상태가 될 때까지 폴링한 다음, 이를 기반으로 빌드를 생성하고, 빌드가 SUCCEEDED 상태가 될 때까지 폴링한 후, model_urls에서 3MF를 다운로드합니다.

프로토타입은 보통 몇 분 이내에 완료되며, 빌드는 일반적으로 1분도 채 걸리지 않고 완료됩니다. 실제 통합에서는 빌드에 크레딧을 소비하기 전에 프로토타입의 image_urls 항목을 최종 사용자에게 보여주고 확인(또는 프로토타입 재실행)을 받도록 하는 것이 좋습니다.

Complete flow

POST

/openapi/creative-lab/fidget-pixel/v1

#!/usr/bin/env bash
set -euo pipefail

# Requires curl and jq. Point IMAGE_PATH at a local photo, or IMAGE_URL at a public one:
#   export MESHY_API_KEY=msy_...
#   export IMAGE_PATH=./portrait.jpg          # or: export IMAGE_URL=https://...
#   export PIXEL_TYPE=person                  # or: other
: "${MESHY_API_KEY:?export MESHY_API_KEY first}"
if [[ -z "${IMAGE_PATH:-}" && -z "${IMAGE_URL:-}" ]]; then
  echo "export IMAGE_PATH (local file) or IMAGE_URL (public url) first" >&2
  exit 1
fi
PIXEL_TYPE=${PIXEL_TYPE:-person}

BASE="https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1"
AUTH="Authorization: Bearer $MESHY_API_KEY"

# api METHOD URL [curl args...] -> prints the response body, non-zero on failure.
# Note we do not use -f/--fail: it discards the body, and the body is the only
# place the reason appears.
api() {
  local method=$1 url=$2 out http_code body
  shift 2
  out=$(curl --silent --show-error --max-time 60 --write-out $'\n%{http_code}' \
    -X "$method" "$url" -H "$AUTH" "$@") || return 1
  http_code=${out##*$'\n'}
  body=${out%$'\n'*}
  if ((http_code >= 400)); then
    echo "HTTP $http_code for $url: $body" >&2
    return 1
  fi
  printf '%s' "$body"
}

# Each task gets its own 40-minute budget.
poll() {
  local kind=$1 id=$2 delay=5 task_status deadline
  deadline=$(($(date +%s) + 2400))
  while :; do
    if (($(date +%s) >= deadline)); then
      echo "gave up waiting for $kind $id" >&2
      return 1
    fi
    task_status=$(api GET "$BASE/$kind/$id" | jq -r '.status')
    echo "$kind: $task_status"
    case "$task_status" in
    SUCCEEDED) return 0 ;;
    FAILED | CANCELED) return 1 ;;
    esac
    sleep "$delay"
    delay=$((delay * 2 > 30 ? 30 : delay * 2))
  done
}

# Build the request body in a file. A base64 data URI must never go on the
# command line or into an exported variable - a photo of any real size will
# exceed the OS argument limit.
BODY=$(mktemp)
trap 'rm -f "$BODY"' EXIT
if [[ -n "${IMAGE_PATH:-}" ]]; then
  # Declare the real type: the API accepts JPEG, PNG and WebP.
  case "$(printf '%s' "${IMAGE_PATH##*.}" | tr 'A-Z' 'a-z')" in
    png) MIME=image/png ;;
    webp) MIME=image/webp ;;
    *) MIME=image/jpeg ;;
  esac
  {
    printf '{"type":"%s","image_url":"data:%s;base64,' "$PIXEL_TYPE" "$MIME"
    base64 <"$IMAGE_PATH" | tr -d '\n'
    printf '"}'
  } >"$BODY"
else
  jq -n --arg t "$PIXEL_TYPE" --arg u "$IMAGE_URL" \
    '{type: $t, image_url: $u}' >"$BODY"
fi

# 1. Create the prototype task
PROTO_ID=$(api POST "$BASE/prototype" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 2. Wait for the pixel-art image (show image_urls[0] to a user in production)
poll prototype "$PROTO_ID"

# 3. Create the build task (defaults: square pieces, 32x32 grid, 8 mm, 8 colors, 15 mm tall)
jq -n --arg p "$PROTO_ID" \
  '{input_task_id: $p, options: {shape: "square", grid_size: 32, piece_size_mm: 8, color_count: 8, piece_height_mm: 15}, output: {format: "3mf"}}' >"$BODY"
BUILD_ID=$(api POST "$BASE/build" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 4. Wait for the pieces
poll build "$BUILD_ID"

# 5. Download the 3MF. This is a signed URL: no Authorization header,
#    and it stays valid for 3 days after the task finishes.
TASK=$(api GET "$BASE/build/$BUILD_ID")
curl --silent --show-error --fail --max-time 900 \
  -o fidget-pixel.3mf "$(jq -r '.model_urls["3mf"]' <<<"$TASK")"
echo "Done: fidget-pixel.3mf"