API pro vícebarevný tisk

Převeďte 3D model na vícebarevný soubor 3MF pro 3D tisk. Vyberte paletu až 16 barev a předvolbu slicer pro značku vaší tiskárny.

POST/openapi/v1/print/multi-color

Vytvoření úlohy vícebarevného tisku

Vytvoří úlohu vícebarevného tisku, která převede 3D model na vícebarevný soubor 3MF pro 3D tisk. Úloha běží na pozadí. Jak dlouho úloha obvykle trvá, se dozvíte v části Doby zpracování.

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"
}

Parametry

Name
input_task_id
Type
string
Povinné
Description
Povinné, pokud neodešlete model_url. ID úlohy, jejíž model chcete vytisknout, například úlohy Obrázek na 3D, Více obrázků na 3D, Text na 3D, Remesh nebo Retexturování. Úloha musí být vytvořena pomocí API a musí mít stav SUCCEEDED.
Vícebarevný tisk čte soubor GLB dané úlohy, který smí mít nejvýše 8 000 000 ploch. Model s více plochami vrátí 400. V takovém případě na něm nejprve spusťte úlohu Remesh a místo toho odešlete ID této úlohy Remesh.

Name
model_url
Type
string
Povinné
Description
Povinné, pokud neodešlete input_task_id. Model k vytisknutí jako veřejná URL adresa nebo jako Data URI. Pokud odešlete obojí, Meshy použije input_task_id.
Adresa URL typu http nebo https musí odkazovat na soubor .glb nebo .fbx o velikosti nejvýše 400 MB. Data URI musí obsahovat soubor GLB zakódovaný v base64 o velikosti nejvýše 100 MB. Použijte data:model/gltf-binary;base64,. Soubor .fbx odešlete jako adresu URL typu http nebo https.
Soubor větší než 100 MB musí navíc splňovat tato pravidla:
- Smí mít nejvýše 8 000 000 ploch. Meshy počítá plochy jako trojúhelníky, takže čtyřúhelník se počítá jako 2 a síť nakreslená vícekrát se počítá jednou za každou kopii.
- Soubor FBX musí být binární FBX verze 7.1 nebo novější.
- Soubor GLB nesmí používat kompresi Draco.

Name
max_colors
Type
integer
výchozí 4
Description
Maximální počet barev ve výsledné paletě, od 1 do 16. Chcete-li použít výchozí hodnotu, parametr vynechte, místo abyste odeslali 0.
Name
style
Type
string
výchozí realistic
Description
Barevný styl souboru 3MF.
Dostupné hodnoty:
- realistic: vzorkuje barvy přímo z textury modelu pro jemné, fotorealistické detaily a vytváří větší soubor.
- cartoon: zplošťuje barvy do čistých, jednolitých oblastí pro stylizovaný vzhled a vytváří menší soubor.
Model musí mít barvu. realistic vyžaduje jedinou základní barevnou texturu s UV souřadnicemi na každé části sítě a cartoon navíc přijímá i barvy vrcholů. Meshy odmítne netexturovaný (bílý) model. Viz model_missing_texture.
Name
max_depth
Type
integer
výchozí 4
Description
Hloubka subdivize, kterou Meshy používá ke vzorkování barev textury na síť, od 3 do 6. 0 má stejný účinek jako vynechání parametru. Vyšší hodnoty zachytí jemnější barevné detaily a vytvoří větší soubor. Používá se pouze u stylu realistic, styl cartoon jej ignoruje.
Name
printer_brand
Type
string
výchozí bambu
Description
Značka tiskárny, jejíž předvolbu slicer Meshy zapíše do souboru 3MF. Soubor se pak otevře ve slicer dané značky s odpovídající tiskárnou, filamentem a profilem procesu. Předvolba používá výchozí tiskárnu dané značky s tryskou 0,4 mm.
Dostupné hodnoty:
- bambu
- anycubic
- creality
- elegoo
- flashforge
- prusa
- qidi
- snapmaker
- ankermake
Jakákoli jiná hodnota vrátí 400.

Návratová hodnota

Pole result v odpovědi obsahuje ID nové úlohy vícebarevného tisku.

Způsoby selhání

Name
400 - Bad Request
Description
Požadavek nelze spustit. Chybová zpráva uvádí, jaký problém byl zjištěn. Například:
- Chybějící parametr: Nebyl odeslán ani model_url, ani input_task_id.
- Neplatný formát modelu: Soubor model_url není soubor .glb ani .fbx.
- Nedostupná URL adresa: Meshy nemůže stáhnout soubor model_url.
- Soubor modelu je příliš velký: Soubor model_url je větší než 400 MB jako adresa URL typu http nebo https, nebo větší než 100 MB jako Data URI.
- Příliš mnoho ploch: Soubor model_url je větší než 100 MB a má více než 8 000 000 ploch. Snižte počet ploch a soubor odešlete znovu.
- ASCII FBX nad 100 MB: Soubor model_url je ASCII FBX větší než 100 MB. Odešlete jej jako binární FBX nebo GLB.
- Nečitelný soubor modelu: Soubor model_url je větší než 100 MB a Meshy nedokáže přečíst jeho hlavičku. Jde například o GLB komprimovaný pomocí Draco, nebo o binární FBX starší než 7.1.
- Hlavička modelu je příliš složitá: Soubor model_url je větší než 100 MB a jeho hlavička obsahuje příliš mnoho sítí, uzlů nebo záznamů ke kontrole. Snižte počet objektů v souboru a odešlete jej znovu.
- Neplatná vstupní úloha: input_task_id neodkazuje na úspěšnou úlohu.
- Příliš mnoho ploch ve vstupní úloze: Model úlohy input_task_id má více než 8 000 000 ploch. Spusťte na něm úlohu Remesh a místo toho odešlete ID této úlohy Remesh.
- Neplatný max_colors: max_colors je záporné nebo větší než 16.
- Neplatný style: style není realistic ani cartoon.
- Neplatný max_depth: max_depth je mimo rozsah 3 až 6 a není 0.
- Neplatný printer_brand: printer_brand není žádná z dostupných hodnot.
- Chybí zdroj barvy: Modelu chybí barva, kterou style vyžaduje. realistic vyžaduje jedinou základní barevnou texturu s UV souřadnicemi na každé části sítě. cartoon přijímá základní barevnou texturu nebo barvy vrcholů. Model nejprve otexturujte, nebo pro model s barvami vrcholů použijte cartoon. Meshy kontroluje nahraný soubor .fbx až po normalizaci úlohy, takže úloha selže místo toho s chybou model_missing_texture.
Opravte požadavek a odešlete jej znovu. Viz Chyby.
Name
401 - Unauthorized
Description
API klíč chybí nebo je neplatný. Zkontrolujte hlavičku Authorization.
Name
402 - Payment Required
Description
Například:
- Nedostatek kreditů: Účet nemá dostatek kreditů pro tuto úlohu, nebo účet dosáhl limitu kreditů. Zkontrolujte svůj zůstatek kreditů a zkuste to znovu.
- Bezplatný plán: Vytvoření úlohy vyžaduje placený plán. Upgradujte svůj plán v nastavení předplatného a zkuste to znovu.
Name
403 - Forbidden
Description
input_task_id je model typu basreliéf, který tento koncový bod nedokáže vytisknout. Zpráva zní This model type does not support this operation. Odešlete jiný model.
Name
404 - Not Found
Description
input_task_id neodpovídá žádné z vašich úloh. Zkontrolujte ID úlohy a odešlete požadavek znovu.
Name
429 - Too Many Requests
Description
Překročili jste svůj limit rychlosti. Počkejte a zkuste to znovu. Viz Limity rychlosti.

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

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

Vrátí úlohu vícebarevného tisku podle jejího 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
}

Parametry

Name
id
Type
path
Description
ID úlohy z odpovědi na vytvoření.

Návratová hodnota

Objekt úlohy vícebarevného tisku.

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

Smazání úlohy Multi-Color Print

Trvale smaže úlohu Multi-Color Print, včetně jejích modelů a dat. Smazání nelze vrátit zpět.

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

Parametry cesty

Name
id
Type
path
Description
ID úlohy, kterou chcete smazat.

Stav úlohy

Smazání úlohy ve stavu PENDING vrátí kredity, které byly použity při jejím vytvoření.

Úlohu ve stavu IN_PROGRESS nelze smazat. Požadavek vrátí 409 Conflict, a úloha dál běží. Meshy nevrací kredity za úlohu, která už byla spuštěna, takže její smazání by vás stálo jak kredity, tak výsledek. Počkejte, dokud nedosáhne stavu SUCCEEDED, FAILED nebo CANCELED, a poté ji smažte.

Smazání úlohy v konečném stavu (SUCCEEDED, FAILED nebo CANCELED) nevrací kredity.

Návratové hodnoty

200 OK, když je úloha smazána, nebo 409 Conflict, když je úloha ve stavu IN_PROGRESS.

GET/openapi/v1/print/multi-color

Seznam úloh vícebarevného tisku

Vrátí seznam vašich úloh vícebarevného 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,
    "expires_at": 1700259201000,
    "task_error": null,
  "consumed_credits": 10
  }
]

Parametry

Name
page_num
Type
integer
výchozí 1
Description
Číslo stránky, která se má vrátit. Číslování stránek začíná od 1.
Name
page_size
Type
integer
výchozí 10
Description
Počet úloh na stránku, maximálně 100.
Name
sort_by
Type
string
Description
Pořadí řazení.
Dostupné hodnoty:
- +created_at: od nejstarších
- -created_at: od nejnovějších

Návratová hodnota

Stránkovaný seznam objektů úloh vícebarevného tisku.

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

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

Streamuje aktualizace úlohy vícebarevného tisku jako 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
}

Parametry

Name
id
Type
path
Description
ID úlohy z odpovědi na vytvoření.

Návratová hodnota

Proud objektů úlohy vícebarevného tisku jako Server-Sent Events.

Každá událost obsahuje celý objekt úlohy ve stejném tvaru, v jakém jej vrací koncový bod Get. Dokud je úloha ve stavu PENDING nebo IN_PROGRESS, její výsledková pole ještě nemají hodnoty.

Objekt úlohy Multi-Color Print

Objekt úlohy Multi-Color Print popisuje jednu konverzi 3D modelu na vícebarevný soubor 3MF. Obsahuje stav, progress a soubor 3MF, pokud úloha uspěje.

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 úlohy. Považujte jej za neprůhledný řetězec a nespoléhejte na jeho formát.
Name
type
Type
string
Description
Typ úlohy, vždy print-multi-color.
Name
model_urls
Type
object
Description
Adresy URL ke stažení vytištěného modelu, jedna pro každý formát souboru. Formát, který úloha nevygenerovala, nemá klíč, místo aby obsahoval prázdný řetězec.
- Name
  3mf
  Type
  string
  Description
  Vícebarevný soubor 3MF.
Name
progress
Type
integer
Description
Kolik procent úlohy je hotovo, vyjádřeno v procentech. Je 0, dokud úloha nezačne, a 100, jakmile uspěje.
Name
status
Type
string
Description
Stav úlohy, jedna z hodnot PENDING, IN_PROGRESS, SUCCEEDED, FAILED nebo CANCELED.
Name
preceding_tasks
Type
integer
Description
Počet úloh před touto úlohou ve frontě. Hodnota má smysl pouze tehdy, dokud je úloha ve stavu PENDING.
Name
created_at
Type
timestamp
Description
Čas vytvoření úlohy, v milisekundách Unix.
Name
started_at
Type
timestamp
Description
Čas zahájení úlohy, v milisekundách Unix. Je 0, dokud úloha nezačne.
Name
finished_at
Type
timestamp
Description
Čas dokončení úlohy, v milisekundách Unix. Je 0, dokud úloha neskončí.
Name
expires_at
Type
timestamp
Description
Čas, kdy vyprší platnost výsledku úlohy, v milisekundách Unix. Je 0, dokud úloha neskončí.
Name
task_error
Type
object
Description
Podrobnosti o chybě, pokud úloha selže. Viz Chyby.
Name
consumed_credits
Type
integer
Description
Počet kreditů, které úloha spotřebovala. Přítomno, pokud je stav PENDING, IN_PROGRESS nebo SUCCEEDED. U úlohy se stavem FAILED je 0, protože Meshy v případě selhání úlohy kredity vrací.