API pro vícebarevný tisk

Převést 3D modely do vícebarevného formátu 3MF pro 3D tisk, s konfigurovatelnou barevnou paletou až 16 barev.

POST/openapi/v1/print/multi-color

Vytvořit úlohu vícebarevného 3D tisku

Tento koncový bod vytvoří novou úlohu vícebarevného 3D tisku. Úloha převede 3D model na vícebarevný soubor 3MF vhodný pro 3D tisk.

Parametry

Vyžadován je pouze jeden z input_task_id nebo model_url. Pokud jsou zadány oba, input_task_id má prioritu.

Name
input_task_id
Type
string
Povinné
Description
ID úspěšné úlohy, která se má použít jako vstup. Podporované typy úloh: Obrázek na 3D, Více obrázků na 3D, Text na 3D, Remesh a Retexturování. Úloha musí mít stav SUCCEEDED.

Name
model_url
Type
string
Povinné
Description
Veřejně dostupná URL nebo Data URI 3D modelu. Aktuálně podporujeme formáty .glb a .fbx.

Name
max_colors
Type
integer
výchozí 4
Description
Maximální počet barev ve výstupní paletě.
Platný rozsah: 1 až 16.
Name
max_depth
Type
integer
výchozí 4
Description
Hloubka quadtree pro přesnost barev. Vyšší hodnoty vytvářejí jemnější hranice barev, ale zvětšují velikost souboru.
Platný rozsah: 3 až 6.

Vrací

Vlastnost result odpovědi obsahuje id nově vytvořené úlohy 3D tisku.

Režimy selhání

Name
400 - Bad Request
Description
Požadavek byl nepřijatelný. Běžné příčiny:
- Chybějící parametr: Musí být zadán buď model_url, nebo input_task_id.
- Neplatný formát modelu: model_url odkazuje na soubor s nepodporovanou příponou (podporovány jsou pouze .glb a .fbx).
- Nedostupná URL: model_url se nepodařilo stáhnout.
- Neplatná vstupní úloha: input_task_id musí odkazovat na úspěšnou úlohu.
- Neplatné max_colors: Hodnota musí být mezi 1 a 16.
- Neplatné max_depth: Hodnota musí být mezi 3 a 6.
Name
401 - Unauthorized
Description
Autentizace selhala. Zkontrolujte svůj API klíč.
Name
402 - Payment Required
Description
Nedostatek kreditů k provedení této úlohy.
Name
429 - Too Many Requests
Description
Překročili jste svůj limit rychlosti.

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

Získání úlohy vícebarevného 3D tisku

Tento koncový bod načte úlohu vícebarevného 3D tisku podle jejího ID.

Parametry

Name
id
Type
path
Description
ID úlohy 3D tisku, která se má načíst.

Návratová hodnota

Objekt úlohy 3D tisku.

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

Smazání úlohy vícebarevného 3D tisku

Tento koncový bod trvale smaže úlohu vícebarevného 3D tisku, včetně všech souvisejících modelů a dat. Tato akce je nevratná.

Parametry cesty

Name
id
Type
path
Description
ID úlohy vícebarevného 3D tisku, kterou chcete smazat.

Návratové hodnoty

Při úspěchu vrací 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

Seznam úloh vícebarevného 3D tisku

Tento koncový bod vám umožňuje získat seznam úloh vícebarevného 3D tisku.

Parametry

Volitelné atributy

Name
page_num
Type
integer
Description
Číslo stránky pro stránkování. Začíná na 1 a výchozí hodnota je 1.
Name
page_size
Type
integer
Description
Limit velikosti stránky. Výchozí hodnota je 10 položek. Maximální povolená hodnota je 50 položek.
Name
sort_by
Type
string
Description
Pole, podle kterého se má řadit. Dostupné hodnoty:
- +created_at: Řadit podle času vytvoření vzestupně.
- -created_at: Řadit podle času vytvoření sestupně.

Vrací

Vrací stránkovaný seznam objektů úloh 3D tisku.

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

Streamování úlohy vícebarevného 3D tisku

Tento koncový bod streamuje aktualizace v reálném čase pro úlohu vícebarevného 3D tisku pomocí Server-Sent Events (SSE).

Parametry

Name
id
Type
path
Description
Jedinečný identifikátor úlohy vícebarevného 3D tisku, která se má streamovat.

Návratová hodnota

Vrací stream objektů úlohy 3D tisku jako Server-Sent Events.

U úloh PENDING nebo IN_PROGRESS bude stream odpovědi obsahovat pouze nezbytná pole progress a 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
}

Objekt úlohy 3D tisku

Name
id
Type
string
Description
Jedinečný identifikátor úlohy. Ačkoli jako implementační detail používáme pro id úloh k-sortable UUID, neměli byste si dělat žádné předpoklady o formátu id.
Name
type
Type
string
Description
Typ úlohy 3D tisku. Hodnota je print-multi-color.
Name
model_urls
Type
object
Description
URL ke stažení souboru 3D modelu vygenerovaného službou Meshy. Vlastnost pro určitý formát bude vynechána, pokud formát není vygenerován, místo aby se vracel prázdný řetězec.
- Name
  3mf
  Type
  string
  Description
  URL ke stažení vícebarevného souboru 3MF.
Name
progress
Type
integer
Description
Progress úlohy. Pokud úloha ještě nebyla spuštěna, tato vlastnost bude 0. Jakmile úloha úspěšně skončí, změní se na 100.
Name
status
Type
string
Description
Stav úlohy. Možné hodnoty jsou jedna z PENDING, IN_PROGRESS, SUCCEEDED, FAILED.
Name
preceding_tasks
Type
integer
Description
Počet předcházejících úloh.
Hodnota tohoto pole má význam pouze tehdy, když je stav úlohy PENDING.
Name
created_at
Type
timestamp
Description
Časové razítko okamžiku, kdy byla úloha vytvořena, v milisekundách.
Name
started_at
Type
timestamp
Description
Časové razítko okamžiku, kdy byla úloha spuštěna, v milisekundách. Pokud úloha ještě nebyla spuštěna, tato vlastnost bude 0.
Name
finished_at
Type
timestamp
Description
Časové razítko okamžiku, kdy byla úloha dokončena, v milisekundách. Pokud úloha ještě nebyla dokončena, tato vlastnost bude 0.
Name
task_error
Type
object
Description
Podrobnosti o chybě u neúspěšných úloh. Úplnou referenci objektu task_error najdete v části Chyby.
Name
consumed_credits
Type
integer
Description
Počet kreditů spotřebovaných touto úlohou. Přítomno, když je stav úlohy PENDING, IN_PROGRESS nebo SUCCEEDED. U úloh FAILED vrací 0 (kredity jsou při selhání vráceny).

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
}