Multi-Color Print API

Converteer een 3D-model naar een meerkleuren-3MF-bestand voor 3D-printen. Kies een palet van maximaal 16 kleuren en een slicer-preset voor uw printermerk.

POST/openapi/v1/print/multi-color

Multi-Color Print-taak aanmaken

Maakt een Multi-Color Print-taak aan, die een 3D-model omzet in een 3MF-bestand met meerdere kleuren voor 3D-printen. De taak draait op de achtergrond. Voor hoe lang een taak gewoonlijk duurt, zie Verwerkingstijden.

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

Parameters

Name
input_task_id
Type
string
Verplicht
Description
Verplicht, tenzij je model_url meestuurt. De ID van de taak waarvan je het model wilt printen, bijvoorbeeld een Afbeelding naar 3D-, Multi-afbeelding naar 3D-, Tekst naar 3D-, Remesh- of Hertextureren-taak. De taak moet er een zijn die je met de API hebt aangemaakt en de status SUCCEEDED hebben.
Multi-Color Print leest het GLB-bestand van de taak, dat maximaal 8.000.000 vlakken mag bevatten. Een model met meer vlakken geeft 400 terug. Voer in dat geval eerst een Remesh-taak erop uit en stuur in plaats daarvan de ID van de Remesh-taak mee.

Name
model_url
Type
string
Verplicht
Description
Verplicht, tenzij je input_task_id meestuurt. Het te printen model, als openbare URL of als data-URI. Als je beide meestuurt, gebruikt Meshy input_task_id.
Een http- of https-URL moet verwijzen naar een .glb- of .fbx-bestand van maximaal 400 MB. Een data-URI moet een base64-GLB-bestand van maximaal 100 MB bevatten. Gebruik data:model/gltf-binary;base64,. Stuur een .fbx-bestand als een http- of https-URL.
Een bestand groter dan 100 MB moet ook aan deze regels voldoen:
- Het mag maximaal 8.000.000 vlakken bevatten. Meshy telt vlakken als driehoeken, dus een vierhoek telt als 2, en een mesh die meer dan eens wordt getekend, telt eenmaal per kopie.
- Een FBX-bestand moet binaire FBX 7.1 of nieuwer zijn.
- Een GLB-bestand mag geen Draco-compressie gebruiken.

Name
max_colors
Type
integer
standaard 4
Description
Het maximale aantal kleuren in het uitvoerpalet, van 1 tot 16. Laat de parameter weg om de standaardwaarde te gebruiken, in plaats van 0 te sturen.
Name
style
Type
string
standaard realistic
Description
De kleurstijl van het 3MF-bestand.
Beschikbare waarden:
- realistic: bemonstert kleuren rechtstreeks van de textuur van het model voor fijne, fotorealistische details, en maakt een groter bestand.
- cartoon: vereenvoudigt kleuren tot nette, uniforme gebieden voor een gestileerde look, en maakt een kleiner bestand.
Het model moet kleur hebben. realistic vereist één basiskleurtextuur, met UV's op elk meshdeel, en cartoon accepteert ook vertexkleuren. Meshy weigert een model zonder textuur (wit). Zie model_missing_texture.
Name
max_depth
Type
integer
standaard 4
Description
De onderverdelingsdiepte die Meshy gebruikt om textuurkleuren op de mesh te bemonsteren, van 3 tot 6. 0 is hetzelfde als de parameter weglaten. Hogere waarden leggen fijnere kleurdetails vast en maken een groter bestand. Alleen de stijl realistic gebruikt dit, cartoon negeert het.
Name
printer_brand
Type
string
standaard bambu
Description
Het printermerk waarvan Meshy de slicer-preset in het 3MF-bestand schrijft. Het bestand opent dan in de slicer van dat merk met een bijpassend printer-, filament- en processprofiel. De preset gebruikt de standaardprinter van het merk, met een nozzle van 0,4 mm.
Beschikbare waarden:
- bambu
- anycubic
- creality
- elegoo
- flashforge
- prusa
- qidi
- snapmaker
- ankermake
Elke andere waarde geeft 400 terug.

Resultaten

Het veld result van de response bevat de ID van de nieuwe Multi-Color Print-taak.

Faalscenario's

Name
400 - Bad Request
Description
Het verzoek kan niet worden uitgevoerd. Het foutbericht geeft aan welk probleem er is gevonden. Bijvoorbeeld:
- Ontbrekende parameter: Noch model_url, noch input_task_id is meegestuurd.
- Ongeldig modelformaat: Het bestand van model_url is geen .glb- of .fbx-bestand.
- Onbereikbare URL: Meshy kan het bestand van model_url niet downloaden.
- Modelbestand te groot: Het bestand van model_url is groter dan 400 MB vanaf een http- of https-URL, of groter dan 100 MB als data-URI.
- Te veel vlakken: Het bestand van model_url is groter dan 100 MB en heeft meer dan 8.000.000 vlakken. Verminder het aantal vlakken en stuur het bestand opnieuw.
- ASCII-FBX groter dan 100 MB: Het bestand van model_url is een ASCII-FBX groter dan 100 MB. Stuur het als binaire FBX of GLB.
- Onleesbaar modelbestand: Het bestand van model_url is groter dan 100 MB en Meshy kan de header niet lezen. Bijvoorbeeld een Draco-gecomprimeerd GLB-bestand, of een binair FBX-bestand ouder dan 7.1.
- Modelheader te complex: Het bestand van model_url is groter dan 100 MB en de header bevat te veel meshes, nodes of records om te controleren. Verminder het aantal objecten in het bestand en stuur het opnieuw.
- Ongeldige invoertaak: input_task_id is geen geslaagde taak.
- Te veel vlakken in de invoertaak: Het model van input_task_id heeft meer dan 8.000.000 vlakken. Voer er een Remesh-taak op uit en stuur in plaats daarvan de ID van de Remesh-taak mee.
- Ongeldige max_colors: max_colors is negatief of groter dan 16.
- Ongeldige style: style is niet realistic of cartoon.
- Ongeldige max_depth: max_depth ligt buiten 3 tot 6 en is niet 0.
- Ongeldige printer_brand: printer_brand is geen van de beschikbare waarden.
- Geen kleurbron: Het model mist de kleur die style vereist. realistic vereist één basiskleurtextuur, met UV's, op elk meshdeel. cartoon accepteert een basiskleurtextuur of vertexkleuren. Geef het model eerst een textuur, of gebruik cartoon voor een model met vertexkleuren. Meshy controleert een .fbx-upload pas nadat de taak deze heeft genormaliseerd, dus de taak mislukt in plaats daarvan met model_missing_texture.
Herstel het verzoek en stuur het opnieuw. Zie Fouten.
Name
401 - Unauthorized
Description
De API-sleutel ontbreekt of is ongeldig. Controleer de header Authorization.
Name
402 - Payment Required
Description
Bijvoorbeeld:
- Onvoldoende credits: Het account heeft niet genoeg credits voor deze taak, of het account heeft een creditlimiet bereikt. Controleer je creditsaldo en probeer het opnieuw.
- Gratis abonnement: Het aanmaken van een taak vereist een betaald abonnement. Upgrade je abonnement in je abonnementsinstellingen en probeer het opnieuw.
Name
403 - Forbidden
Description
input_task_id is een bas-reliëfmodel, dat deze endpoint niet kan printen. Het bericht is This model type does not support this operation. Stuur een ander model.
Name
404 - Not Found
Description
input_task_id komt niet overeen met een van je taken. Controleer de taak-ID en stuur het verzoek opnieuw.
Name
429 - Too Many Requests
Description
Je hebt je rate limit overschreden. Wacht en probeer het opnieuw. Zie Rate limits.

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

Haal een meerkleurenprint-taak op

Retourneert een meerkleurenprint-taak op basis van de 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
}

Parameters

Name
id
Type
path
Description
De taak-ID uit de respons van het aanmaken.

Retourwaarden

Het meerkleurenprint-taakobject.

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

Een meerkleurenprint-taak verwijderen

Verwijdert een meerkleurenprint-taak permanent, inclusief de modellen en gegevens ervan. U kunt een verwijdering niet ongedaan maken.

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

Padparameters

Name
id
Type
path
Description
De ID van de te verwijderen taak.

Taakstatus

Het verwijderen van een PENDING-taak vergoedt de credits die zijn gebruikt bij het aanmaken ervan.

Een IN_PROGRESS-taak kan niet worden verwijderd. Het verzoek geeft 409 Conflict terug, en de taak blijft actief. Meshy vergoedt geen taak die is gestart, dus het verwijderen ervan zou u zowel de credits als het resultaat kosten. Wacht tot deze SUCCEEDED, FAILED of CANCELED bereikt, en verwijder deze dan.

Het verwijderen van een taak met een definitieve status (SUCCEEDED, FAILED of CANCELED) vergoedt de credits ervan niet.

Resultaten

200 OK wanneer de taak is verwijderd, of 409 Conflict wanneer de taak IN_PROGRESS is.

GET/openapi/v1/print/multi-color

Lijst van meerkleurenprint-taken

Retourneert een lijst van uw meerkleurenprint-taken.

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

Parameters

Name
page_num
Type
integer
standaard 1
Description
Het paginanummer dat moet worden geretourneerd. Paginanummers beginnen bij 1.
Name
page_size
Type
integer
standaard 10
Description
Het aantal taken per pagina, tot 100.
Name
sort_by
Type
string
Description
De sorteervolgorde.
Beschikbare waarden:
- +created_at: oudste eerst
- -created_at: nieuwste eerst

Retourwaarden

Een gepagineerde lijst van meerkleurenprint-taakobjecten.

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

Stream een meerkleurenprint-taak

Streamt de updates van een meerkleurenprint-taak als 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
}

Parameters

Name
id
Type
path
Description
De taak-ID uit het aanmaakantwoord.

Retourwaarden

Een stream van meerkleurenprint-taakobjecten als Server-Sent Events.

Elk event bevat het volledige taakobject, in dezelfde vorm als de Get-endpoint retourneert. Zolang de taak PENDING of IN_PROGRESS is, hebben de resultaatvelden nog geen waarden.

Het multi-color print-taakobject

Een multi-color print-taakobject beschrijft één conversie van een 3D-model naar een meerkleuren-3MF-bestand. Het bevat de status, de progress en het 3MF-bestand wanneer de taak slaagt.

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
De taak-ID. Behandel dit als een ondoorzichtige tekenreeks en vertrouw niet op de indeling ervan.
Name
type
Type
string
Description
Het taaktype, altijd print-multi-color.
Name
model_urls
Type
object
Description
Downloadlinks voor het geprinte model, één per bestandsformaat. Een formaat dat de taak niet heeft gegenereerd, heeft geen sleutel, in plaats van een lege tekenreeks.
- Name
  3mf
  Type
  string
  Description
  Het meerkleuren-3MF-bestand.
Name
progress
Type
integer
Description
Hoeveel van de taak is voltooid, als percentage. Dit is 0 totdat de taak start en 100 wanneer deze slaagt.
Name
status
Type
string
Description
De taakstatus, één van PENDING, IN_PROGRESS, SUCCEEDED, FAILED of CANCELED.
Name
preceding_tasks
Type
integer
Description
Het aantal taken dat vóór deze taak in de wachtrij staat. Deze waarde is alleen betekenisvol zolang de taak PENDING is.
Name
created_at
Type
timestamp
Description
Tijdstip waarop de taak is aangemaakt, in Unix-milliseconden.
Name
started_at
Type
timestamp
Description
Tijdstip waarop de taak is gestart, in Unix-milliseconden. Dit is 0 totdat de taak start.
Name
finished_at
Type
timestamp
Description
Tijdstip waarop de taak is voltooid, in Unix-milliseconden. Dit is 0 totdat de taak voltooid is.
Name
expires_at
Type
timestamp
Description
Tijdstip waarop het resultaat van de taak verloopt, in Unix-milliseconden. Dit is 0 totdat de taak voltooid is.
Name
task_error
Type
object
Description
De foutdetails wanneer de taak mislukt. Zie Fouten.
Name
consumed_credits
Type
integer
Description
Het aantal credits dat de taak heeft gebruikt. Aanwezig wanneer de status PENDING, IN_PROGRESS of SUCCEEDED is. Dit is 0 voor een FAILED-taak, omdat Meshy de credits terugbetaalt wanneer een taak mislukt.