다색 프린트 API

3D 프린팅을 위해 최대 16색까지 구성 가능한 컬러 팔레트를 사용하여 3D 모델을 다색 3MF 형식으로 변환합니다.

POST/openapi/v1/print/multi-color

멀티 컬러 3D 프린팅 작업 생성

이 엔드포인트는 새로운 멀티 컬러 3D 프린팅 작업을 생성합니다. 이 작업은 3D 모델을 3D 프린팅에 적합한 멀티 컬러 3MF 파일로 변환합니다.

파라미터

input_task_id 또는 model_url 중 하나만 필수입니다. 둘 다 제공된 경우 input_task_id가 우선순위를 갖습니다.

Name
input_task_id
Type
string
필수
Description
입력으로 사용할 성공한 작업의 ID입니다. 지원되는 작업 유형: 이미지로 3D, 멀티 이미지로 3D, 텍스트로 3D, 리메시, 및 리텍스처. 작업의 상태는 SUCCEEDED여야 합니다.

Name
model_url
Type
string
필수
Description
공개적으로 접근 가능한 3D 모델의 URL 또는 Data URI입니다. 현재 .glb 및 .fbx 형식을 지원합니다.

Name
max_colors
Type
integer
기본값 4
Description
출력 팔레트의 최대 색상 수입니다.
유효 범위: 1부터 16까지.
Name
max_depth
Type
integer
기본값 4
Description
색상 정밀도를 위한 쿼드트리 깊이입니다. 값이 높을수록 더 세밀한 색상 경계를 생성하지만 파일 크기가 증가합니다.
유효 범위: 3부터 6까지.

반환값

응답의 result 속성에는 새로 생성된 3D 프린팅 작업의 id가 포함됩니다.

실패 모드

Name
400 - Bad Request
Description
요청을 수락할 수 없습니다. 일반적인 원인:
- 누락된 파라미터: model_url 또는 input_task_id 중 하나를 제공해야 합니다.
- 잘못된 모델 형식: model_url이 지원되지 않는 확장자를 가진 파일을 가리킵니다(.glb 및 .fbx만 지원됨).
- 접근할 수 없는 URL: model_url을 다운로드할 수 없습니다.
- 잘못된 입력 작업: input_task_id는 성공한 작업을 참조해야 합니다.
- 잘못된 max_colors: 값은 1과 16 사이여야 합니다.
- 잘못된 max_depth: 값은 3과 6 사이여야 합니다.
Name
401 - Unauthorized
Description
인증에 실패했습니다. API 키를 확인하세요.
Name
402 - Payment Required
Description
이 작업을 수행하기에 크레딧이 부족합니다.
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다.

Request

POST

/openapi/v1/print/multi-color

# Convert a 3D model to multi-color 3MF for printing
curl https://api.meshy.ai/openapi/v1/print/multi-color \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "max_colors": 8,
    "max_depth": 5
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/print/multi-color/:id

멀티 컬러 3D 프린트 작업 조회

이 엔드포인트는 ID로 멀티 컬러 3D 프린트 작업을 조회합니다.

매개변수

Name
id
Type
path
Description
조회할 3D 프린트 작업의 ID입니다.

반환값

3D 프린트 작업 객체입니다.

Request

GET

/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl https://api.meshy.ai/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-multi-color",
  "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}

DELETE/openapi/v1/print/multi-color/:id

다중 색상 3D 프린트 작업 삭제

이 엔드포인트는 연결된 모든 모델 및 데이터를 포함하여 다중 색상 3D 프린트 작업을 영구적으로 삭제합니다. 이 작업은 되돌릴 수 없습니다.

경로 매개변수

Name
id
Type
path
Description
삭제할 다중 색상 3D 프린트 작업의 ID입니다.

반환값

성공 시 200 OK를 반환합니다.

Request

DELETE

/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.

GET/openapi/v1/print/multi-color

다중 색상 3D 프린트 작업 목록

이 엔드포인트를 사용하면 다중 색상 3D 프린트 작업 목록을 가져올 수 있습니다.

매개변수

선택적 속성

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

반환값

3D 프린트 작업 객체의 페이지네이션된 목록을 반환합니다.

Request

GET

/openapi/v1/print/multi-color

curl https://api.meshy.ai/openapi/v1/print/multi-color?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-multi-color",
    "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
  "consumed_credits": 10
  }
]

GET/openapi/v1/print/multi-color/:id/stream

멀티 컬러 3D 프린트 작업 스트리밍

이 엔드포인트는 SSE를 사용하여 멀티 컬러 3D 프린트 작업의 실시간 업데이트를 스트리밍합니다.

매개변수

Name
id
Type
path
Description
스트리밍할 멀티 컬러 3D 프린트 작업의 고유 식별자입니다.

반환값

3D 프린트 작업 객체의 스트림을 SSE로 반환합니다.

PENDING 또는 IN_PROGRESS 작업의 경우, 응답 스트림에는 필요한 progress 및 status 필드만 포함됩니다.

Request

GET

/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-multi-color",
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.3mf?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}

3D 프린트 작업 객체

Name
id
Type
string
Description
작업의 고유 식별자입니다. 구현 세부 사항으로 작업 id에 k-sortable UUID를 사용하지만, id 형식에 대해 어떤 가정도 해서는 안 됩니다.
Name
type
Type
string
Description
3D 프린트 작업의 유형입니다. 값은 print-multi-color입니다.
Name
model_urls
Type
object
Description
Meshy에서 생성한 3D 모델 파일을 다운로드할 수 있는 URL입니다. 형식이 생성되지 않은 경우 빈 문자열을 반환하는 대신 해당 형식의 속성이 생략됩니다.
- Name
  3mf
  Type
  string
  Description
  멀티 컬러 3MF 파일을 다운로드할 수 있는 URL입니다.
Name
progress
Type
integer
Description
작업의 progress입니다. 작업이 아직 시작되지 않은 경우 이 속성은 0입니다. 작업이 성공하면 이 값은 100이 됩니다.
Name
status
Type
string
Description
작업의 상태입니다. 가능한 값은 PENDING, IN_PROGRESS, SUCCEEDED, FAILED 중 하나입니다.
Name
preceding_tasks
Type
integer
Description
선행 작업 수입니다.
이 필드의 값은 작업 상태가 PENDING인 경우에만 의미가 있습니다.
Name
created_at
Type
timestamp
Description
작업이 생성된 시점의 타임스탬프(밀리초)입니다.
Name
started_at
Type
timestamp
Description
작업이 시작된 시점의 타임스탬프(밀리초)입니다. 작업이 아직 시작되지 않은 경우 이 속성은 0입니다.
Name
finished_at
Type
timestamp
Description
작업이 완료된 시점의 타임스탬프(밀리초)입니다. 작업이 아직 완료되지 않은 경우 이 속성은 0입니다.
Name
task_error
Type
object
Description
실패한 작업의 오류 세부 정보입니다. 전체 task_error 객체 참조는 오류를 참조하세요.
Name
consumed_credits
Type
integer
Description
이 작업에서 소비한 크레딧 수입니다. 작업 상태가 PENDING, IN_PROGRESS 또는 SUCCEEDED일 때 표시됩니다. FAILED 작업의 경우 0을 반환합니다(실패 시 크레딧은 환불됩니다).

The 3D Print Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-multi-color",
  "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}