Creative Lab Fidget Pixel API

사진을 두 단계에 걸쳐 멀티컬러, 3D 프린팅 가능한 픽셀 아트 피젯 보드로 변환합니다. 프로토타입 작업은 사진을 픽셀 아트 이미지로 변환합니다. 빌드 작업은 해당 이미지를 하나의 3MF 파일 안에 맞물리는 조각들로 변환하며, 프로토타입 작업의 ID를 input_task_id로 사용합니다.

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

두 POST endpoint 모두 유료 플랜이 필요합니다. 무료 플랜 계정의 요청은 402를 반환합니다.

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

Fidget Pixel 프로토타입 작업 생성

사진 한 장으로부터 픽셀 아트 이미지를 생성합니다. 조각을 만들려면 이 작업의 ID를 input_task_id로 build 엔드포인트에 전달하세요. 작업의 필드에 대해서는 The Fidget Pixel prototype task object를 참고하세요.

이미지가 마음에 들지 않으면 프로토타입 작업을 다시 만드세요. 각 작업은 개별적으로 요금이 청구됩니다.

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

매개변수

Name
image_url
Type
string
필수
Description
픽셀 아트로 변환할 사진으로, 공개 URL 또는 data URI(data:image/jpeg;base64,<your base64-encoded image data>) 형식입니다.
이미지는 최대 20MB의 JPG, JPEG, PNG, 또는 WebP 파일이어야 합니다. Meshy는 URL의 파일 확장자가 아니라 이미지 데이터로부터 형식을 감지합니다. 확장자가 없는 URL도 사용할 수 있으며, Meshy는 리디렉션을 따라갑니다.
Name
type
Type
string
필수
Description
사진에 담긴 대상을 나타내며, 이에 따라 픽셀 아트 스타일이 결정됩니다. 두 스타일은 뚜렷하게 다릅니다. 다른 값을 지정하면 400이 반환됩니다.
사용 가능한 값:
- person: 인물 사진(초상 또는 전신 사진). Meshy는 치비(chibi) 스타일의 픽셀 스프라이트를 그립니다.
- other: 반려동물, 사물, 마스코트, 로고, 풍경 등 그 외 모든 대상. Meshy는 비즈 아트(bead-art) 스타일의 픽셀 아이콘을 그립니다.
Name
name
Type
string
Description
작업의 이름으로, 최대 100자까지 가능합니다. 작업의 name 필드에 그대로 반환됩니다. 더 긴 이름을 지정하면 400이 반환됩니다.

반환 값

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

실패 모드

Name
400 - Bad Request
Description
요청을 실행할 수 없습니다. 예를 들면:
- image_url 또는 type이 누락되었습니다.
- type이 person 또는 other가 아닙니다.
- 이미지가 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
다음 한도 중 하나에 도달했습니다:
- 속도 제한을 초과하는 요청을 보냈습니다. 몇 초 기다린 뒤 다시 시도하세요. 속도 제한을 참고하세요.
- 대기 중이거나 실행 중인 작업이 너무 많습니다. 일부가 완료될 때까지 기다린 뒤 다시 시도하세요.
- 무제한 플랜에서 크레딧이 남아 있지 않은 상태로, 크레딧 없이 실행할 수 있는 작업 수에 도달했습니다. 작업이 완료되기를 기다리거나 크레딧을 추가하세요.
Name
500 - Internal Server Error
Description
Meshy에서 서버 오류가 발생했습니다. 예를 들어 이미지에 대한 지적 재산 검사를 실행하지 못한 경우입니다. Meshy는 작업을 생성하지 않으며, 청구된 크레딧이 있다면 환불합니다. 요청을 다시 시도하세요.

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

Fidget Pixel 빌드 작업 생성하기

성공한 프로토타입 작업으로부터 3D 프린트가 가능한 조각들을 생성합니다. Meshy는 픽셀 아트 이미지를 그리드에 샘플링하고 최대 color_count 개의 색상으로 줄입니다. 피사체의 각 셀은 서로 맞물리는 조각이 되며, 배경은 프린트되지 않습니다.

결과물은 색상으로 프린트할 준비가 된 단일 다색 3MF 파일입니다. 각 조각은 회색 몸체와 픽셀 색상의 상단면을 가집니다. 필드에 대해서는 Fidget Pixel 빌드 작업 객체를 참조하세요.

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

매개변수

Name
input_task_id
Type
string
필수
Description
빌드할 프로토타입 작업의 ID입니다. POST /openapi/creative-lab/fidget-pixel/v1/prototype로 회원님의 계정이 생성한, 상태가 SUCCEEDED인 작업이어야 합니다.
API를 통해 생성된 Fidget Pixel 프로토타입 작업이 아닌 ID는 404를 반환하며, 웹 앱에서 만든 프로토타입도 마찬가지입니다.
Name
name
Type
string
Description
작업의 이름으로, 최대 100자까지 가능합니다. 작업의 name 필드로 돌아옵니다. 더 긴 이름은 400을 반환합니다.

`options`

조각의 모양과 크기에 대한 설정입니다. 모든 필드에는 기본값이 있으므로 변경하려는 필드만 보내면 됩니다. 0은 해당 필드의 기본값을 사용합니다. 이는 Creative Lab 웹 앱과 동일한 설정입니다. 다른 모양 설정은 고정되어 있으며, Meshy가 shape와 piece_size_mm를 기준으로 설정합니다.

Name
shape
Type
string
기본값 square
Description
각 조각의 바닥면 형태입니다. 다른 값은 400을 반환합니다.
사용 가능한 값:
- square: 정사각형 그리드 위의 정사각형 조각
- hex: 육각형 그리드 위의 육각형 조각으로, piece_size_mm이 6 또는 8로 설정됩니다
Name
grid_size
Type
integer
기본값 32
Description
보드 각 변을 따라 배치되는 그리드 셀의 수로, 16 또는 32입니다. 다른 값은 400을 반환합니다. 32 그리드는 더 많은 디테일을 유지합니다. 16 그리드는 같은 크기의 조각이 더 적게 생성되므로 보드 너비가 약 절반이 됩니다.
Name
piece_size_mm
Type
integer
기본값 8
Description
각 조각의 변 길이(밀리미터 단위)로, 6, 8, 또는 10입니다. 다른 값은 400을 반환합니다. grid_size와 함께 프린트된 보드의 크기를 결정합니다. 예를 들어, 8 mm 조각으로 이루어진 32 그리드는 한 변이 약 26.5 cm입니다.
10은 hex와 함께 사용할 수 없으며 400을 반환하는데, 대부분의 일반 소비자용 FDM 프린터에서는 경사진 육각형 면이 오버행되기 때문입니다.
Name
color_count
Type
integer
기본값 8
Description
픽셀 아트 팔레트의 최대 색상 수로, 1부터 8까지입니다. 범위를 벗어난 값은 400을 반환합니다. 프린트하려면 색상당 하나씩, 그리고 회색 몸체용으로 하나, 최대 color_count 더하기 하나의 필라멘트가 필요합니다.
Name
piece_height_mm
Type
integer
기본값 15
Description
각 조각의 높이(밀리미터 단위)로, 10부터 80까지입니다. 범위를 벗어난 값은 400을 반환합니다.

`output`

결과 파일에 대한 설정입니다.

Name
format
Type
string
기본값 3mf
Description
결과물의 파일 형식입니다. 다른 값은 400을 반환합니다.
사용 가능한 값:
- 3mf: model_urls.3mf로 반환되는 다색 model.3mf 파일 하나

반환값

result 필드에는 새 빌드 작업의 ID가 담깁니다. status가 SUCCEEDED가 될 때까지 작업을 조회하거나 스트리밍하세요. 그런 다음 model_urls.3mf에서 3MF 파일을 다운로드하세요.

실패 모드

Name
400 - Bad Request
Description
요청을 실행할 수 없습니다. 예를 들어:
- input_task_id가 누락되었거나 유효한 작업 ID가 아닙니다.
- 프로토타입 작업의 상태가 SUCCEEDED가 아닙니다. 아직 실행 중이라면 기다렸다가 다시 시도하세요. 실패했거나 취소된 경우 새 프로토타입 작업을 생성하세요.
- 프로토타입 작업은 성공했지만 이미지가 없습니다. 새 프로토타입 작업을 생성하세요.
- options 필드가 허용된 값의 범위를 벗어났습니다. 예를 들어 grid_size가 16이나 32가 아닌 경우입니다.
- piece_size_mm이 10이고 shape가 hex입니다. 육각형 조각은 6 mm와 8 mm만 지원합니다.
- output.format이 3mf가 아닙니다.
오류 메시지에 어떤 문제가 발견되었는지 표시됩니다.
Name
401 - Unauthorized
Description
API 키가 없거나 유효하지 않습니다. Authorization 헤더를 확인하세요.
Name
402 - Payment Required
Description
다음 중 하나에 해당합니다:
- 계정에 크레딧이 충분하지 않습니다.
- API 키, 작업 공간, 또는 구성원이 크레딧 한도에 도달했습니다.
- 계정이 무료 플랜을 사용 중입니다.
크레딧과 플랜을 확인한 후 다시 시도하세요.
Name
403 - Forbidden
Description
팀에서 IP Filtering이 켜져 있으며, Meshy가 프로토타입 작업의 이미지를 제3자 지적 재산권 문제로 표시했습니다. 사용 권한이 있는 이미지로 프로토타입 작업을 생성하세요.
Name
404 - Not Found
Description
input_task_id가 회원님의 계정이 API로 생성한 어떤 Fidget Pixel 프로토타입 작업과도 일치하지 않습니다. 웹 앱에서 만든 프로토타입 역시 404를 반환합니다. 프로토타입 생성 응답의 result ID를 보내세요.
Name
429 - Too Many Requests
Description
다음 중 하나의 한도에 도달했습니다:
- 속도 제한이 허용하는 것보다 많은 요청을 보냈습니다. 몇 초 기다린 후 다시 시도하세요. 속도 제한을 참조하세요.
- 대기 중이거나 실행 중인 작업이 너무 많습니다. 일부가 완료될 때까지 기다린 후 다시 시도하세요.
- 크레딧이 남아 있지 않은 무제한 플랜에서, 크레딧 없이 실행할 수 있는 작업 수에 도달했습니다. 작업이 완료되기를 기다리거나 크레딧을 추가하세요.
Name
500 - Internal Server Error
Description
Meshy에서 서버 오류가 발생했습니다. 예를 들어 프로토타입 작업의 이미지에 대한 지적 재산권 검사를 실행할 수 없었던 경우입니다. Meshy는 작업을 생성하지 않으며, 청구된 크레딧이 있다면 환불합니다. 요청을 다시 시도하세요.

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

Fidget Pixel 작업 가져오기

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

각 필드에 대해서는 Fidget Pixel prototype 작업 객체와 Fidget Pixel build 작업 객체를 참조하세요.

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

매개변수

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

반환값

경로의 단계에 맞는 prototype 작업 객체 또는 build 작업 객체입니다.

실패 모드

Name
400 - Bad Request
Description
id가 유효한 작업 ID가 아닙니다. 생성 응답의 result ID를 보내세요.
Name
403 - Forbidden
Description
팀에서 IP 필터링이 켜져 있고, Meshy가 prototype 작업의 이미지를 제3자 지식재산권 문제로 플래그 지정했습니다. Build 작업과 Enterprise 플랜의 팀에는 이 오류가 발생하지 않습니다. 사용 권한이 있는 이미지로 prototype 작업을 생성하세요.
Name
404 - Not Found
Description
이 ID를 가진 Fidget Pixel 작업이 귀하의 계정에 속해 있지 않거나, 작업의 단계가 경로와 일치하지 않습니다. ID를 확인하고 작업에 맞게 /prototype 또는 /build를 사용하세요.
Name
500 - Internal Server Error
Description
Meshy가 지식재산권 검사를 실행할 수 없었습니다. 요청을 재시도하세요.

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

Fidget Pixel 작업 삭제

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

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

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

경로 매개변수

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를 가진 Fidget Pixel 작업이 귀하의 계정에 속해 있지 않거나, 작업의 단계가 경로와 일치하지 않습니다. ID를 확인하고, 작업에 맞게 /prototype 또는 /build를 사용하세요.

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

Fidget Pixel 작업의 업데이트를 Server-Sent Events(SSE)로 스트리밍합니다. 경로는 작업의 단계와 일치해야 합니다. 일치하지 않는 경우, 예를 들어 build 작업의 ID로 /prototype/:id/stream을 호출하면 status_code: 404와 함께 하나의 error 이벤트가 전송되고 스트림이 종료됩니다. 유효한 작업 ID가 아닌 id인 경우에도 status_code: 400과 함께 동일하게 처리됩니다.

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

매개변수

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

반환값

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

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

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

Fidget Pixel 작업 목록 조회

한 단계(stage)에 해당하는 Fidget Pixel 작업을 한 번에 한 페이지씩 반환합니다. 경로가 단계를 선택합니다. /prototype은 prototype 작업만 반환하고, /build는 build 작업만 반환합니다.

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

경로 매개변수

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

반환 값

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

The Fidget Pixel prototype task object

prototype 작업은 사진을 픽셀 아트 이미지로 변환합니다. 이미지를 3D 프린팅이 가능한 조각으로 변환하려면 작업의 ID를 build 엔드포인트에 input_task_id로 전달하세요.

Properties

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

Name
id
Type
string
Description
작업 ID입니다. 형식에 의존하지 마세요.
Name
type
Type
string
Description
작업 유형이며, 항상 creative-lab-fidget-pixel-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
작업이 생성된 시각으로, 밀리초 단위의 유닉스 시간입니다.
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 응답에서는 이 필드가 생략되며, list 요청은 500을 반환합니다. 이 경우 요청을 재시도하세요.
Name
image_urls
Type
array of strings
Description
픽셀 아트 이미지를 위한 다운로드 URL입니다. 작업이 성공하면 배열에 URL이 하나 있으며, 그 전까지는 비어 있습니다.
URL은 서명되어 있으므로 Authorization 헤더 없이 가져오세요. 이 URL은 expires_at까지 유효합니다. 그 전에 작업을 다시 조회해도 새로 서명된 URL이 아니라 동일한 URL이 반환됩니다. 만료된 URL은 갱신할 수 없으므로, 그 전에 파일을 다운로드하여 저장하세요.

Fidget Pixel 빌드 태스크 객체

빌드 태스크는 성공한 프로토타입 태스크로부터 3D 프린트 가능한 조각들을 생성합니다. Meshy는 픽셀 아트 이미지를 그리드 위에 샘플링하고, 그 조각들을 하나의 다색 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=***"
  }
}

Name
id
Type
string
Description
태스크 ID입니다. 이 값의 형식에 의존하지 마세요.
Name
type
Type
string
Description
태스크 유형이며, 항상 creative-lab-fidget-pixel-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 응답에서는 이 필드가 생략되며, list 요청은 500을 반환합니다. 이 경우 요청을 다시 시도하세요.
Name
model_urls
Type
object
Description
파일 형식별로 키가 지정된 결과 다운로드 URL입니다. 이 객체는 보낸 output.format에 대한 항목 하나를 가지며, 태스크가 성공할 때까지는 비어 있습니다.
URL은 서명되어 있으므로 Authorization 헤더 없이 가져와야 합니다. 이 URL은 expires_at까지 유효합니다. 그 전에 태스크를 다시 조회해도 새로 서명된 URL이 아니라 동일한 URL이 반환됩니다. 만료된 URL은 갱신할 수 없으므로, 그 전에 파일을 다운로드하여 저장하세요.
- Name
  3mf
  Type
  string
  Description
  다색 3MF 파일의 다운로드 URL입니다. 각 조각은 회색 몸체와 해당 픽셀 색상의 윗면을 가집니다. output.format이 기본값인 3mf일 때 존재합니다.

엔드투엔드 예제

다음 cURL 및 Python 스크립트는 전체 흐름을 실행합니다. 각 스크립트는 사진으로부터 프로토타입 작업을 생성하고 성공할 때까지 기다립니다. 그런 다음 빌드 작업을 생성하고, 해당 작업을 기다렸다가 model_urls.3mf에서 3MF 파일을 다운로드합니다.

cURL 스크립트에는 curl과 jq가 필요하며, Python 스크립트에는 requests 패키지가 필요합니다. 스크립트를 실행하려면 다음 단계를 따르세요:

MESHY_API_KEY를 본인의 API 키로 설정합니다.
IMAGE_PATH를 로컬 사진의 경로로 설정하거나, IMAGE_URL을 공개 이미지 URL로 설정합니다.
선택 사항: 사람이 아닌 다른 피사체를 픽셀화하려면 PIXEL_TYPE을 other로 설정합니다.
스크립트를 실행합니다.

프로토타입 작업은 보통 몇 분 이내에 완료됩니다. 빌드 작업은 보통 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"