API pro vícebarevný tisk

Převeďte 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ření úlohy 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

Je vyžadován pouze jeden z parametrů input_task_id nebo model_url. Pokud jsou zadány oba, přednost má input_task_id.

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 adresa 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
style
Type
string
výchozí realistic
Description
Vizuální barevný styl vygenerovaného souboru 3MF.
Dostupné hodnoty:
- realistic: Odebírá barvy přímo z textury modelu pro jemné, fotorealistické detaily. Vytváří větší soubor.
- cartoon: Zplošťuje barvy do čistých, jednotných oblastí pro stylizovaný vzhled. Vytváří menší soubor.
Vstup musí obsahovat barvu: realistic vyžaduje jednu základní barevnou texturu s UV souřadnicemi na každé části sítě; cartoon také přijímá barvy jednotlivých vrcholů. Modely bez textury (bílé) jsou odmítnuty — viz model_missing_texture.

Návratové hodnoty

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

Způsoby selhání

Name
400 - Bad Request
Description
Požadavek byl nepřijatelný. Časté 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 adresa: 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ý style: Hodnota musí být realistic nebo cartoon.
- Chybí zdroj barev: Vstupní model nemá základní barevnou texturu (realistic vyžaduje jednu, s UV souřadnicemi, na každé části sítě) ani barvy vrcholů (cartoon přijímá kterékoli z toho). Model nejprve otexturujte, nebo pro modely s barvami vrcholů použijte cartoon. Nahrané soubory .fbx jsou zkontrolovány po normalizaci úlohou a selžou s chybou model_missing_texture.
Name
401 - Unauthorized
Description
Autentizace se nezdařila. Zkontrolujte prosím 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
  }'

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 získá úlohu vícebarevného 3D tisku podle jejího ID.

Parametry

Name
id
Type
path
Description
ID úlohy 3D tisku, kterou chcete získat.

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, která má být smazána.

Stav úlohy

Úloha, která je stále ve stavu PENDING, je smazána a kredity spotřebované v okamžiku vytvoření jsou vráceny.

Úlohu, která je již ve stavu IN_PROGRESS, nelze smazat: požadavek je odmítnut s chybou 409 Conflict a úloha běží dál. Kredity za úlohu, kterou už worker začal zpracovávat, není možné vrátit, takže smazání za běhu by vás stálo kredity i výsledek zároveň. Počkejte, až úloha dosáhne stavu SUCCEEDED, FAILED nebo CANCELED, a poté ji smažte.

Úloha v koncovém stavu (SUCCEEDED, FAILED nebo CANCELED) je smazána bez vrácení kreditů.

Návratová hodnota

Vrací 200 OK při úspěchu, nebo 409 Conflict, pokud je úloha ve stavu IN_PROGRESS.

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 is left 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."
}

GET/openapi/v1/print/multi-color

List Multi-Color 3D Print Tasks

Tento koncový bod 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á 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 100 položek.
Name
sort_by
Type
string
Description
Pole, podle kterého se má řadit. Dostupné hodnoty:
- +created_at: Seřadit podle času vytvoření vzestupně.
- -created_at: Seřadit podle času vytvoření sestupně.

Návratová hodnota

Vrací stránkovaný seznam objektů úlohy 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, kterou chcete streamovat.

Návratová hodnota

Vrací proud objektů úlohy 3D tisku ve formě Server-Sent Events.

U úloh ve stavu PENDING nebo IN_PROGRESS bude proud 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. I když jako implementační detail používáme pro id úlohy k-seřaditelné UUID, neměli byste dělat žádné předpoklady o formátu tohoto id.
Name
type
Type
string
Description
Typ úlohy 3D tisku. Hodnota je print-multi-color.
Name
model_urls
Type
object
Description
Stažitelná URL adresa souboru 3D modelu vygenerovaného službou Meshy. Vlastnost pro daný formát bude vynechána, pokud daný formát nebyl vygenerován, místo vrácení prázdného řetězce.
- Name
  3mf
  Type
  string
  Description
  Stažitelná URL adresa vícebarevného souboru 3MF.
Name
progress
Type
integer
Description
Průběh (progress) úlohy. Pokud úloha ještě nebyla zahájena, tato vlastnost bude 0. Jakmile úloha úspěšně skončí, hodnota se změní 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á smysl pouze tehdy, pokud je stav úlohy PENDING.
Name
created_at
Type
timestamp
Description
Časové razítko okamžiku vytvoření úlohy, v milisekundách.
Name
started_at
Type
timestamp
Description
Časové razítko okamžiku zahájení úlohy, v milisekundách. Pokud úloha ještě nebyla zahájena, tato vlastnost bude 0.
Name
finished_at
Type
timestamp
Description
Časové razítko okamžiku dokončení úlohy, 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. Úplný popis objektu task_error naleznete v části Chyby.
Name
consumed_credits
Type
integer
Description
Počet kreditů spotřebovaných touto úlohou. Je přítomen, pokud je stav úlohy PENDING, IN_PROGRESS nebo SUCCEEDED. Pro úlohy se stavem FAILED vrací 0 (v případě selhání jsou kredity 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
}