다색 프린트 API

3D 모델을 3D 프린팅을 위한 다색 3MF 형식으로 변환하며, 최대 16가지 색상의 컬러 팔레트를 구성할 수 있습니다.

POST/openapi/v1/print/multi-color

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

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

파라미터

input_task_id 또는 model_url 중 하나만 필수입니다. 둘 다 제공된 경우, input_task_id가 우선합니다.

  • Name
    model_url
    Type
    string
    필수
    Description

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

  • Name
    max_colors
    Type
    integer
    기본값 4
    Description

    출력 팔레트의 최대 색상 수입니다.

    유효 범위: 1에서 16까지.

  • Name
    style
    Type
    string
    기본값 realistic
    Description

    생성된 3MF 파일의 시각적 색상 스타일입니다.

    사용 가능한 값:

    • realistic: 모델의 텍스처에서 직접 색상을 샘플링하여 세밀하고 사진 같은 디테일을 제공합니다. 더 큰 파일을 생성합니다.
    • cartoon: 색상을 깨끗하고 균일한 영역으로 평탄화하여 스타일리시한 외관을 제공합니다. 더 작은 파일을 생성합니다.

반환값

응답의 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 사이여야 합니다.
    • 잘못된 스타일: 값은 realistic 또는 cartoon이어야 합니다.
  • 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
  }'

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부터 시작하며 기본값입니다.

  • 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 프린트 작업 스트리밍

이 엔드포인트는 Server-Sent Events (SSE)를 사용하여 다중 색상 3D 프린트 작업에 대한 실시간 업데이트를 스트리밍합니다.

매개변수

  • Name
    id
    Type
    path
    Description

    스트리밍할 다중 색상 3D 프린트 작업의 고유 식별자입니다.

반환값

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

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

    작업의 진행 상황입니다. 작업이 아직 시작되지 않은 경우 이 속성은 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
}