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ření úlohy pro vícebarevný 3D tisk

Tento koncový bod vytváří novou úlohu pro vícebarevný 3D tisk. Úloha převádí 3D model do vícebarevného souboru 3MF vhodného pro 3D tisk.

Parametry

Pouze jeden z input_task_id nebo model_url je požadován. Pokud jsou poskytnuty oba, input_task_id má prioritu.

Name
input_task_id
Type
string
Povinné
Description
ID úspěšné úlohy, kterou chcete 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ě přístupná 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
style
Type
string
výchozí realistic
Description
Vizuální barevný styl generovaného souboru 3MF.
Dostupné hodnoty:
- realistic: Vzorkuje barvy přímo z textury modelu pro jemný, fotorealistický detail. Produkuje větší soubor.
- cartoon: Zplošťuje barvy do čistých, jednotných oblastí pro stylizovaný vzhled. Produkuje menší soubor.

Návratové hodnoty

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

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 poskytnut buď model_url nebo input_task_id.
- Neplatný formát modelu: model_url odkazuje na soubor s nepodporovanou příponou (pouze .glb a .fbx jsou podporovány).
- Nedosažitelná URL: model_url nemohla být stažena.
- Neplatná vstupní úloha: input_task_id musí odkazovat na úspěšnou úlohu.
- Neplatný max_colors: Hodnota musí být mezi 1 a 16.
- Neplatný styl: Hodnota musí být realistic nebo cartoon.
Name
401 - Unauthorized
Description
Autentizace selhala. Zkontrolujte prosím svůj API klíč.
Name
402 - Payment Required
Description
Nedostatečné kredity pro provedení této úlohy.
Name
429 - Too Many Requests
Description
Překročili jste svůj limit rychlosti.

Požadavek

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

Odpověď

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

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

Načtení úlohy pro vícebarevný 3D tisk

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

Parametry

Name
id
Type
path
Description
ID úlohy pro 3D tisk, kterou chcete načíst.

Vrací

Objekt úlohy pro 3D tisk.

Požadavek

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

Odpověď

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

Vrátí

Vrátí 200 OK při úspěchu.

Požadavek

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

Odpověď

// Returns 200 Ok on success.

GET/openapi/v1/print/multi-color

Seznam úloh pro 3D tisk s více barvami

Tento koncový bod vám umožňuje získat seznam úloh pro 3D tisk s více barvami.

Parametry

Volitelné atributy

Name
page_num
Type
integer
Description
Číslo stránky pro stránkování. Začíná a výchozí 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 pro řazení. Dostupné hodnoty:
- +created_at: Řazení podle času vytvoření vzestupně.
- -created_at: Řazení podle času vytvoření sestupně.

Vrací

Vrací stránkovaný seznam Objektů úloh pro 3D tisk.

Požadavek

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

Odpověď

[
  {
    "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 pro úlohu vícebarevného 3D tisku ke streamování.

Vrací

Vrací stream Objektů úloh 3D tisku jako Server-Sent Events.

Pro úlohy ve stavu 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
Unikátní identifikátor pro úlohu. I když používáme k-tříditelné UUID pro id úloh jako implementační detail, neměli byste 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
Stáhnutelná URL adresa k souboru 3D modelu generovaného Meshy. Vlastnost pro formát bude vynechána, pokud formát není generován, místo vrácení prázdného řetězce.
- Name
  3mf
  Type
  string
  Description
  Stáhnutelná URL adresa k souboru multi-color 3MF.
Name
progress
Type
integer
Description
Progress úlohy. Pokud úloha ještě nezačala, tato vlastnost bude 0. Jakmile úloha uspěje, stane se 100.
Name
status
Type
string
Description
Stav úlohy. Možné hodnoty jsou PENDING, IN_PROGRESS, SUCCEEDED, FAILED.
Name
preceding_tasks
Type
integer
Description
Počet předcházejících úloh.
Hodnota tohoto pole je smysluplná pouze pokud je stav úlohy PENDING.
Name
created_at
Type
timestamp
Description
Časové razítko, kdy byla úloha vytvořena, v milisekundách.
Name
started_at
Type
timestamp
Description
Časové razítko, kdy byla úloha zahájena, v milisekundách. Pokud úloha ještě nezačala, tato vlastnost bude 0.
Name
finished_at
Type
timestamp
Description
Časové razítko, kdy byla úloha dokončena, v milisekundách. Pokud úloha ještě není dokončena, tato vlastnost bude 0.
Name
task_error
Type
object
Description
Podrobnosti o chybě pro neúspěšné úlohy. Pro úplnou referenci objektu task_error viz 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. Vrací 0 pro úlohy FAILED (kredity jsou v případě 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
}