Multi-Color Print API

Converteer 3D-modellen naar meerkleuren-3MF-formaat voor 3D-printen, met een configureerbaar kleurenpalet van tot 16 kleuren.

POST/openapi/v1/print/multi-color

Een Multi-Color 3D-printtaak maken

Deze endpoint maakt een nieuwe multi-color 3D-printtaak aan. De taak converteert een 3D-model naar een multi-color 3MF-bestand dat geschikt is voor 3D-printen.

De taak wordt op de achtergrond uitgevoerd. Voor hoe lang dit gewoonlijk duurt, zie Verwerkingstijden.

Parameters

Slechts één van input_task_id of model_url is verplicht. Als beide worden opgegeven, krijgt input_task_id prioriteit.

Name
input_task_id
Type
string
Verplicht
Description
De ID van een geslaagde taak om als invoer te gebruiken. Ondersteunde taaktypes: Afbeelding naar 3D, Multi-afbeelding naar 3D, Tekst naar 3D, Remesh, en Hertextureren. De taak moet de status SUCCEEDED hebben.

Name
model_url
Type
string
Verplicht
Description
Publiek toegankelijke URL van een .glb- of .fbx-model, of een base64 data:-URL van een GLB (data:model/gltf-binary;base64,...). Een .fbx moet als http- of https-URL worden verzonden.
Maximale bestandsgrootte: 400 MB voor een http- of https-URL, 100 MB voor een data:-URI.
Een bestand groter dan 100 MB mag maximaal 8.000.000 vlakken bevatten. Vlakken worden geteld als driehoeken: een vierhoek telt als 2, en een mesh die meerdere keren wordt getekend telt één keer per kopie. Boven 100 MB moet een FBX-bestand binaire FBX 7.1 of nieuwer zijn, en mag een GLB-bestand geen Draco-compressie gebruiken.

Name
max_colors
Type
integer
standaard 4
Description
Maximaal aantal kleuren in het uitvoerpalet.
Geldig bereik: 1 tot 16.
Name
style
Type
string
standaard realistic
Description
Visuele kleurstijl van het gegenereerde 3MF-bestand.
Beschikbare waarden:
- realistic: Bemonstert kleuren rechtstreeks van de textuur van het model voor fijn, fotorealistisch detail. Produceert een groter bestand.
- cartoon: Verplat kleuren tot schone, uniforme gebieden voor een gestileerde look. Produceert een kleiner bestand.
De invoer moet kleur bevatten: realistic vereist één basiskleurtextuur met UV-coördinaten op elk mesh-onderdeel; cartoon accepteert ook kleuren per vertex. Modellen zonder textuur (wit) worden afgewezen — zie model_missing_texture.
Name
max_depth
Type
integer
standaard 4
Description
Onderverdelingsdiepte die wordt gebruikt om textuurkleuren op de mesh te bemonsteren. Hogere waarden leggen fijner kleurdetail vast, ten koste van een groter bestand. Geldt alleen voor de stijl realistic; wordt genegeerd voor cartoon.
Geldig bereik: 3 tot 6.
Name
printer_brand
Type
string
standaard bambu
Description
Printermerk waarvan de slicer-preset in de 3MF wordt geschreven, zodat het bestand in de slicer van dat merk wordt geopend met een bijpassende printer-, filament- en procesprofiel. Elk merk gebruikt zijn standaardprinter met een nozzle van 0,4 mm.
Beschikbare waarden: bambu, anycubic, creality, elegoo, flashforge, prusa, qidi, snapmaker, ankermake.

Resultaat

De eigenschap result van de response bevat de id van de nieuw aangemaakte 3D-printtaak.

Foutmodi

Name
400 - Bad Request
Description
Het verzoek was onacceptabel. Veelvoorkomende oorzaken:
- Ontbrekende parameter: Ofwel model_url ofwel input_task_id moet worden opgegeven.
- Ongeldig modelformaat: De model_url verwijst naar een bestand met een niet-ondersteunde extensie (alleen .glb en .fbx worden ondersteund).
- Onbereikbare URL: De model_url kon niet worden gedownload.
- Modelbestand te groot: Het model_url-bestand overschrijdt 400 MB (http- of https-URL) of 100 MB (data:-URI).
- Te veel vlakken: Het model_url-bestand is groter dan 100 MB en heeft meer dan 8.000.000 vlakken. Verminder het aantal vlakken en verstuur het bestand opnieuw.
- ASCII FBX groter dan 100 MB: Het model_url-bestand is een ASCII FBX groter dan 100 MB. Verstuur het als binaire FBX of GLB.
- Onleesbaar modelbestand: Het model_url-bestand is groter dan 100 MB en de header kan niet worden gelezen, bijvoorbeeld een Draco-gecomprimeerde GLB, of een binaire FBX ouder dan 7.1.
- Modelheader te complex: Het model_url-bestand is groter dan 100 MB en de header heeft te veel meshes, nodes of records om te controleren. Verminder het aantal objecten in het bestand en verstuur het opnieuw.
- Ongeldige invoertaak: De input_task_id moet verwijzen naar een geslaagde taak.
- Ongeldige max_colors: Waarde moet tussen 1 en 16 liggen.
- Ongeldige style: Waarde moet realistic of cartoon zijn.
- Ongeldige max_depth: Waarde moet tussen 3 en 6 liggen.
- Ongeldige printer_brand: Waarde moet een van de hierboven genoemde merken zijn.
- Geen kleurbron: Het invoermodel heeft geen basiskleurtextuur (realistic vereist er één, met UV's, op elk mesh-onderdeel) en geen vertexkleuren (cartoon accepteert beide). Textureer het model eerst, of gebruik cartoon voor modellen met vertexkleuren. .fbx-uploads worden gecontroleerd nadat de taak ze normaliseert en mislukken met model_missing_texture in plaats daarvan.
Name
401 - Unauthorized
Description
Authenticatie mislukt. Controleer uw API-sleutel.
Name
402 - Payment Required
Description
Onvoldoende credits om deze taak uit te voeren.
Name
429 - Too Many Requests
Description
U heeft uw rate limit overschreden.

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

Een Multi-Color 3D-afdruktaak ophalen

Dit endpoint haalt een multi-color 3D-afdruktaak op aan de hand van de ID.

Parameters

Name
id
Type
path
Description
De ID van de 3D-afdruktaak die moet worden opgehaald.

Returns

Het 3D Print Task-object.

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

Een Multi-Color 3D-printtaak verwijderen

Deze endpoint verwijdert permanent een multi-color 3D-printtaak, inclusief alle bijbehorende modellen en gegevens. Deze actie is onomkeerbaar.

Pad parameters

Name
id
Type
path
Description
De ID van de multi-color 3D-printtaak die moet worden verwijderd.

Taakstatus

Een taak die nog PENDING is, wordt verwijderd en de credits die bij het aanmaken zijn verbruikt, worden terugbetaald.

Een taak die al IN_PROGRESS is, kan niet worden verwijderd: het verzoek wordt afgewezen met 409 Conflict en de taak blijft doorlopen. Credits voor een taak die de worker al is gestart, zijn niet terugbetaalbaar, dus het verwijderen ervan tijdens de uitvoering zou je zowel de credits als het resultaat kosten. Wacht tot de status SUCCEEDED, FAILED of CANCELED bereikt is, en verwijder de taak dan.

Een taak in een eindstatus (SUCCEEDED, FAILED of CANCELED) wordt verwijderd zonder terugbetaling.

Retourneert

Retourneert 200 OK bij succes, of 409 Conflict wanneer de taak IN_PROGRESS is.

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

Meerkleurige 3D-printtaken weergeven

Met deze endpoint kun je een lijst met meerkleurige 3D-printtaken ophalen.

Parameters

Optionele attributen

Name
page_num
Type
integer
Description
Paginanummer voor paginering. Begint bij en standaard 1.
Name
page_size
Type
integer
Description
Paginagrootte limiet. Standaard 10 items. Maximaal toegestaan is 100 items.
Name
sort_by
Type
string
Description
Veld om op te sorteren. Beschikbare waarden:
- +created_at: Sorteer op aanmaaktijd in oplopende volgorde.
- -created_at: Sorteer op aanmaaktijd in aflopende volgorde.

Retourneert

Retourneert een gepagineerde lijst van The 3D Print Task Objects.

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

Stream a Multi-Color 3D Print Task

Dit endpoint streamt realtime updates voor een multi-color 3D-printtaak via Server-Sent Events (SSE).

Parameters

Name
id
Type
path
Description
Unieke identifier voor de multi-color 3D-printtaak die gestreamd moet worden.

Retourwaarden

Retourneert een stream van The 3D Print Task Objects als Server-Sent Events.

Voor taken met status PENDING of IN_PROGRESS bevat de responsestream alleen de noodzakelijke velden progress en 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
}

Het 3D-printtaakobject

Name
id
Type
string
Description
Unieke identificatie voor de taak. Hoewel we als implementatiedetail een k-sorteerbare UUID gebruiken voor taak-id's, mag je geen aannames doen over het formaat van de id.
Name
type
Type
string
Description
Type van de 3D-printtaak. De waarde is print-multi-color.
Name
model_urls
Type
object
Description
Downloadbare URL naar het 3D-modelbestand dat door Meshy is gegenereerd. De eigenschap voor een formaat wordt weggelaten als het formaat niet is gegenereerd, in plaats van een lege string te retourneren.
- Name
  3mf
  Type
  string
  Description
  Downloadbare URL naar het multikleuren-3MF-bestand.
Name
progress
Type
integer
Description
Voortgang van de taak. Als de taak nog niet gestart is, is deze eigenschap 0. Zodra de taak is geslaagd, wordt dit 100.
Name
status
Type
string
Description
Status van de taak. Mogelijke waarden zijn een van PENDING, IN_PROGRESS, SUCCEEDED, FAILED.
Name
preceding_tasks
Type
integer
Description
Het aantal voorafgaande taken.
De waarde van dit veld is alleen relevant als de taakstatus PENDING is.
Name
created_at
Type
timestamp
Description
Tijdstempel van het moment waarop de taak is aangemaakt, in milliseconden.
Name
started_at
Type
timestamp
Description
Tijdstempel van het moment waarop de taak is gestart, in milliseconden. Als de taak nog niet is gestart, is deze eigenschap 0.
Name
finished_at
Type
timestamp
Description
Tijdstempel van het moment waarop de taak is voltooid, in milliseconden. Als de taak nog niet is voltooid, is deze eigenschap 0.
Name
task_error
Type
object
Description
Foutdetails voor mislukte taken. Zie Fouten voor de volledige referentie van het task_error-object.
Name
consumed_credits
Type
integer
Description
Het aantal credits dat door deze taak is verbruikt. Aanwezig wanneer de taakstatus PENDING, IN_PROGRESS, of SUCCEEDED is. Geeft 0 terug voor FAILED-taken (credits worden terugbetaald bij een mislukking).

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
}