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

Create a Multi-Color 3D Print Task

Tento koncový bod vytvoří nový úkol pro vícebarevný 3D tisk. Úkol převede 3D model na vícebarevný soubor 3MF vhodný pro 3D tisk.

Parametry

Je vyžadováno pouze jedno 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ě dokončeného úkolu, který se má použít jako vstup. Podporované typy úkolů: Obrázek na 3D, Více obrázků na 3D, Text na 3D, Remesh a Retexturování. Úkol 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: Vzorkuje barvy přímo z textury modelu pro jemné, fotorealistické detaily. Vytváří větší soubor.
- cartoon: Zploští 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 přijímá i barvy jednotlivých vrcholů. Netexturované (bílé) modely jsou odmítnuty — viz model_missing_texture.
Name
max_depth
Type
integer
výchozí 4
Description
Hloubka subdivize použitá k vzorkování barev textury na síť. Vyšší hodnoty zachytí jemnější barevné detaily za cenu většího souboru. Platí pouze pro styl realistic; u cartoon je ignorováno.
Platný rozsah: 3 až 6.
Name
printer_brand
Type
string
výchozí bambu
Description
Značka tiskárny, jejíž předvolba pro slicer je zapsána do souboru 3MF, takže se soubor otevře ve sliceru dané značky s odpovídajícím profilem tiskárny, filamentu a procesu. Každá značka používá svou výchozí tiskárnu s tryskou 0,4 mm.
Dostupné hodnoty: bambu, anycubic, creality, elegoo, flashforge, prusa, qidi, snapmaker, ankermake.

Návratové hodnoty

Vlastnost result v odpovědi obsahuje id nově vytvořeného úkolu 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áno 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í úkol: input_task_id musí odkazovat na úspěšně dokončený úkol.
- Neplatné max_colors: Hodnota musí být mezi 1 a 16.
- Neplatný style: Hodnota musí být realistic nebo cartoon.
- Neplatné max_depth: Hodnota musí být mezi 3 a 6.
- Neplatné printer_brand: Hodnota musí být jedna ze značek uvedených výše.
- Chybí zdroj barvy: Vstupní model nemá žádnou základní barevnou texturu (realistic vyžaduje jednu, s UV, na každé části sítě) ani barvy vrcholů (cartoon přijímá obojí). Nejprve model otexturujte, nebo pro modely s barvami vrcholů použijte cartoon. Nahrané soubory .fbx jsou zkontrolovány až po normalizaci v rámci úkolu a selžou s chybou model_missing_texture.
Name
401 - Unauthorized
Description
Autentizace selhala. Zkontrolujte prosím svůj API klíč.
Name
402 - Payment Required
Description
Nedostatek kreditů k provedení tohoto úkolu.
Name
429 - Too Many Requests
Description
Překročili jste limit rychlosti.

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

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

Načtení ú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, kterou chcete 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, 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
}