다색 프린트 API

3D 모델을 3D 프린팅을 위한 다색 3MF 파일로 변환하세요. 최대 16가지 색상의 팔레트와 프린터 브랜드에 맞는 슬라이서 프리셋을 선택하세요.

POST/openapi/v1/print/multi-color

다색 프린트 작업 생성

3D 모델을 3D 프린팅용 다색 3MF 파일로 변환하는 다색 프린트 작업을 생성합니다. 이 작업은 백그라운드에서 실행됩니다. 작업이 일반적으로 걸리는 시간은 처리 시간을 참고하세요.

Request

POST

/openapi/v1/print/multi-color

# Convert a 3D model to a multi-color 3MF with a Creality slicer preset
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,
    "printer_brand": "creality"
  }'

Response

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

파라미터

Name
input_task_id
Type
string
필수
Description
model_url을 보내지 않는 한 필수입니다. 출력하려는 모델을 가진 작업의 ID로, 예를 들어 이미지로 3D, 멀티 이미지로 3D, 텍스트로 3D, 리메시, 또는 리텍스처 작업이 있습니다. 해당 작업은 API로 생성한 것이어야 하며, 상태가 SUCCEEDED여야 합니다.
다색 프린트는 작업의 GLB 파일을 읽으며, 이 파일은 최대 8,000,000개의 면을 가질 수 있습니다. 면이 더 많은 모델은 400을 반환합니다. 이 경우, 먼저 리메시 작업을 실행한 다음 해당 리메시 작업의 ID를 대신 보내세요.

Name
model_url
Type
string
필수
Description
input_task_id를 보내지 않는 한 필수입니다. 출력할 모델로, 공개 URL 또는 data URI 형식입니다. 둘 다 보내면 Meshy는 input_task_id를 사용합니다.
http 또는 https URL은 최대 400MB의 .glb 또는 .fbx 파일을 가리켜야 합니다. data URI는 최대 100MB의 base64 GLB 파일을 담아야 합니다. data:model/gltf-binary;base64,를 사용하세요. .fbx 파일은 http 또는 https URL로 보내세요.
100MB를 초과하는 파일은 다음 규칙도 따라야 합니다:
- 최대 8,000,000개의 면을 가질 수 있습니다. Meshy는 면을 삼각형 단위로 계산하므로, 사각형은 2개로 계산되고, 여러 번 그려진 메시는 복사본마다 한 번씩 계산됩니다.
- FBX 파일은 바이너리 FBX 7.1 이상이어야 합니다.
- GLB 파일은 Draco 압축을 사용하지 않아야 합니다.

Name
max_colors
Type
integer
기본값 4
Description
출력 팔레트에 포함될 최대 색상 수로, 1부터 16까지입니다. 기본값을 사용하려면 0을 보내지 말고 아예 생략하세요.
Name
style
Type
string
기본값 realistic
Description
3MF 파일의 색상 스타일입니다.
사용 가능한 값:
- realistic: 모델의 텍스처에서 직접 색상을 샘플링하여 정교하고 사실적인 디테일을 만들며, 파일 크기가 더 커집니다.
- cartoon: 색상을 균일한 영역으로 단순화하여 스타일화된 느낌을 만들며, 파일 크기가 더 작아집니다.
모델에는 색상이 있어야 합니다. realistic은 모든 메시 부분에 UV가 있는 단일 베이스 컬러 텍스처가 필요하며, cartoon은 버텍스 컬러도 허용합니다. Meshy는 텍스처가 없는(흰색) 모델을 거부합니다. model_missing_texture를 참고하세요.
Name
max_depth
Type
integer
기본값 4
Description
Meshy가 텍스처 색상을 메시에 샘플링할 때 사용하는 세분화 깊이로, 3부터 6까지입니다. 0은 생략한 것과 동일합니다. 값이 클수록 더 세밀한 색상 디테일을 포착하며, 파일 크기가 더 커집니다. realistic 스타일에서만 사용되며, cartoon은 이를 무시합니다.
Name
printer_brand
Type
string
기본값 bambu
Description
Meshy가 3MF 파일에 기록할 슬라이서 프리셋의 프린터 브랜드입니다. 이렇게 생성된 파일은 해당 브랜드의 슬라이서에서 일치하는 프린터, 필라멘트, 공정 프로필과 함께 열립니다. 프리셋은 해당 브랜드의 기본 프린터와 0.4mm 노즐을 사용합니다.
사용 가능한 값:
- bambu
- anycubic
- creality
- elegoo
- flashforge
- prusa
- qidi
- snapmaker
- ankermake
다른 값을 보내면 400을 반환합니다.

반환값

응답의 result 필드에는 새로 생성된 다색 프린트 작업의 ID가 담겨 있습니다.

실패 모드

Name
400 - Bad Request
Description
요청을 실행할 수 없습니다. 오류 메시지에서 발견된 문제를 알려줍니다. 예를 들면:
- 파라미터 누락: model_url과 input_task_id 중 어느 것도 보내지 않았습니다.
- 잘못된 모델 형식: model_url 파일이 .glb 또는 .fbx 파일이 아닙니다.
- 접근 불가능한 URL: Meshy가 model_url 파일을 다운로드할 수 없습니다.
- 모델 파일이 너무 큼: model_url 파일이 http 또는 https URL에서 400MB를 초과하거나, data URI로 100MB를 초과합니다.
- 면이 너무 많음: model_url 파일이 100MB를 초과하며 8,000,000개 이상의 면을 가지고 있습니다. 면 수를 줄인 다음 파일을 다시 보내세요.
- ASCII FBX가 100MB 초과: model_url 파일이 100MB를 초과하는 ASCII FBX입니다. 바이너리 FBX 또는 GLB로 보내세요.
- 읽을 수 없는 모델 파일: model_url 파일이 100MB를 초과하며, Meshy가 헤더를 읽을 수 없습니다. 예를 들어 Draco로 압축된 GLB이거나, 7.1 이전 버전의 바이너리 FBX인 경우입니다.
- 모델 헤더가 너무 복잡함: model_url 파일이 100MB를 초과하며, 헤더에 검사할 메시, 노드, 레코드가 너무 많습니다. 파일 내 객체 수를 줄인 다음 다시 보내세요.
- 잘못된 입력 작업: input_task_id가 성공한 작업이 아닙니다.
- 입력 작업의 면이 너무 많음: input_task_id 모델이 8,000,000개 이상의 면을 가지고 있습니다. 해당 모델에 리메시 작업을 실행한 다음, 리메시 작업의 ID를 대신 보내세요.
- 잘못된 max_colors: max_colors가 음수이거나 16을 초과합니다.
- 잘못된 style: style이 realistic 또는 cartoon이 아닙니다.
- 잘못된 max_depth: max_depth가 3에서 6 범위를 벗어나며, 0도 아닙니다.
- 잘못된 printer_brand: printer_brand가 사용 가능한 값 중 하나가 아닙니다.
- 색상 소스 없음: 모델에 style이 필요로 하는 색상이 없습니다. realistic은 모든 메시 부분에 UV가 있는 단일 베이스 컬러 텍스처가 필요합니다. cartoon은 베이스 컬러 텍스처 또는 버텍스 컬러를 허용합니다. 먼저 모델에 텍스처를 적용하거나, 버텍스 컬러가 있는 모델에는 cartoon을 사용하세요. Meshy는 작업이 .fbx 업로드를 정규화한 후에만 검사하므로, 해당 작업은 대신 model_missing_texture로 실패합니다.
요청을 수정한 다음 다시 보내세요. 오류를 참고하세요.
Name
401 - Unauthorized
Description
API 키가 없거나 유효하지 않습니다. Authorization 헤더를 확인하세요.
Name
402 - Payment Required
Description
예를 들면:
- 크레딧 부족: 계정에 이 작업을 수행할 충분한 크레딧이 없거나, 계정이 크레딧 한도에 도달했습니다. 크레딧 잔액을 확인한 다음 다시 시도하세요.
- 무료 플랜: 작업 생성에는 유료 플랜이 필요합니다. 구독 설정에서 플랜을 업그레이드한 다음 다시 시도하세요.
Name
403 - Forbidden
Description
input_task_id가 이 엔드포인트에서 출력할 수 없는 저부조(bas-relief) 모델입니다. 메시지는 This model type does not support this operation입니다. 다른 모델을 보내세요.
Name
404 - Not Found
Description
input_task_id가 사용자의 어떤 작업과도 일치하지 않습니다. 작업 ID를 확인한 다음 요청을 다시 보내세요.
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다. 잠시 기다린 다음 다시 시도하세요. 속도 제한을 참고하세요.

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

다색 프린트 작업 가져오기

ID로 다색 프린트 작업을 반환합니다.

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,
  "expires_at": 1700259201000,
  "task_error": null,
"consumed_credits": 10
}

매개변수

Name
id
Type
path
Description
생성 응답에서 받은 작업 ID입니다.

반환값

다색 프린트 작업 객체입니다.

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

다색 프린트 작업 삭제

다색 프린트 작업을 모델 및 데이터를 포함하여 영구적으로 삭제합니다. 삭제는 취소할 수 없습니다.

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

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

경로 매개변수

Name
id
Type
path
Description
삭제할 작업의 ID입니다.

작업 상태

PENDING 상태의 작업을 삭제하면 작업을 생성할 때 사용된 크레딧이 환불됩니다.

IN_PROGRESS 상태의 작업은 삭제할 수 없습니다. 요청은 409 Conflict를 반환하며, 작업은 계속 실행됩니다. Meshy는 이미 시작된 작업에 대해서는 환불을 해주지 않으므로, 이를 삭제하면 크레딧과 결과물을 모두 잃게 됩니다. 작업이 SUCCEEDED, FAILED, 또는 CANCELED 상태에 도달할 때까지 기다린 후 삭제하세요.

최종 상태(SUCCEEDED, FAILED, 또는 CANCELED)의 작업을 삭제해도 크레딧은 환불되지 않습니다.

반환값

작업이 삭제되면 200 OK를 반환하고, 작업이 IN_PROGRESS 상태이면 409 Conflict를 반환합니다.

GET/openapi/v1/print/multi-color

다색 프린트 작업 목록 조회

다색 프린트 작업 목록을 반환합니다.

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,
    "expires_at": 1700259201000,
    "task_error": null,
  "consumed_credits": 10
  }
]

매개변수

Name
page_num
Type
integer
기본값 1
Description
반환할 페이지 번호입니다. 페이지 번호는 1부터 시작합니다.
Name
page_size
Type
integer
기본값 10
Description
페이지당 작업 수이며, 최대 100까지 가능합니다.
Name
sort_by
Type
string
Description
정렬 순서입니다.
사용 가능한 값:
- +created_at: 오래된 순
- -created_at: 최신 순

반환값

다색 프린트 작업 객체의 페이지네이션된 목록입니다.

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

다색 프린트 작업 스트리밍

다색 프린트 작업의 업데이트를 Server-Sent Events(SSE)로 스트리밍합니다.

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.
// These examples are shortened. Each event holds the full task object.
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,
  "expires_at": 1700259201000,
  "task_error": null,
"consumed_credits": 10
}

파라미터

Name
id
Type
path
Description
생성 응답에서 받은 작업 ID입니다.

반환값

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

각 이벤트는 Get 엔드포인트가 반환하는 것과 동일한 형태로 전체 작업 객체를 담고 있습니다. 작업이 PENDING 또는 IN_PROGRESS 상태인 동안에는 결과 필드에 아직 값이 없습니다.

다색 프린트 작업 객체

다색 프린트 작업 객체는 3D 모델을 다색 3MF 파일로 변환하는 작업 하나를 나타냅니다. 작업이 성공하면 상태, progress, 3MF 파일을 담고 있습니다.

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,
  "expires_at": 1700259201000,
  "task_error": null,
"consumed_credits": 10
}

Name
id
Type
string
Description
작업 ID입니다. 불투명한 문자열로 취급하고, 형식에 의존하지 마세요.
Name
type
Type
string
Description
작업 유형으로, 항상 print-multi-color입니다.
Name
model_urls
Type
object
Description
프린트된 모델의 다운로드 URL이며, 파일 형식마다 하나씩 있습니다. 작업이 생성하지 않은 형식은 빈 문자열이 아니라 키 자체가 없습니다.
- Name
  3mf
  Type
  string
  Description
  다색 3MF 파일입니다.
Name
progress
Type
integer
Description
작업이 얼마나 진행되었는지를 백분율로 나타냅니다. 작업이 시작되기 전까지는 0이고, 성공하면 100입니다.
Name
status
Type
string
Description
작업 상태이며, PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED 중 하나입니다.
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
expires_at
Type
timestamp
Description
작업 결과가 만료되는 시간이며, 유닉스 밀리초 단위입니다. 작업이 종료되기 전까지는 0입니다.
Name
task_error
Type
object
Description
작업이 실패했을 때의 오류 세부 정보입니다. 오류를 참고하세요.
Name
consumed_credits
Type
integer
Description
작업이 사용한 크레딧 수입니다. 상태가 PENDING, IN_PROGRESS, SUCCEEDED일 때 존재합니다. FAILED 작업의 경우 Meshy가 작업 실패 시 크레딧을 환불하므로 0입니다.