Meerkleurenprint API

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

POST/openapi/v1/print/multi-color

Create a Multi-Color 3D Print Task

Deze endpoint creëert een nieuwe multi-color 3D-printtaak. De taak converteert een 3D-model naar een multi-color 3MF-bestand geschikt voor 3D-printen.

Parameters

Slechts een van input_task_id of model_url is vereist. Als beide worden opgegeven, heeft input_task_id prioriteit.

Name
input_task_id
Type
string
Verplicht
Description
De ID van een geslaagde taak om als input 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 of Data URI van een 3D-model. We ondersteunen momenteel de formaten .glb en .fbx.

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. Levert een groter bestand op.
- cartoon: Vereenvoudigt kleuren tot nette, uniforme gebieden voor een gestileerde look. Levert een kleiner bestand op.
De input moet kleur bevatten: realistic vereist een enkele basiskleurtextuur met UV-coördinaten op elk mesh-onderdeel; cartoon accepteert ook kleuren per vertex. Modellen zonder textuur (wit) worden geweigerd — 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 vangen fijner kleurdetail op 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 het 3MF-bestand wordt geschreven, zodat het bestand in de slicer van dat merk wordt geopend met een passend 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.

Returns

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

Faalmodi

Name
400 - Bad Request
Description
Het verzoek was onaanvaardbaar. Veelvoorkomende oorzaken:
- Ontbrekende parameter: Er moet ofwel model_url ofwel input_task_id 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.
- Ongeldige input-taak: 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 vermelde merken zijn.
- Geen kleurbron: Het inputmodel heeft geen basiskleurtextuur (realistic heeft er precies één nodig, 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 heeft genormaliseerd en falen dan met model_missing_texture.
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-printtaak ophalen

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

Parameters

Name
id
Type
path
Description
De ID van de op te halen 3D-printtaak.

Retourneert

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

Verwijder een Multi-Color 3D Print Taak

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

Padparameters

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

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 draaien. Credits voor een taak waarmee de worker al is begonnen, kunnen niet worden terugbetaald, dus het verwijderen ervan halverwege zou u zowel de credits als het resultaat kosten. Wacht tot de taak SUCCEEDED, FAILED of CANCELED bereikt, en verwijder deze 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

Deze endpoint stelt u in staat om een lijst met meerkleurige 3D-printtaken op te halen.

Parameters

Optionele attributen

Name
page_num
Type
integer
Description
Paginanummer voor paginering. Begint en heeft standaard de waarde 1.
Name
page_size
Type
integer
Description
Limiet voor de paginagrootte. 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 een multikleuren-3D-printtaak

Deze endpoint streamt realtime updates voor een multikleuren-3D-printtaak met behulp van Server-Sent Events (SSE).

Parameters

Name
id
Type
path
Description
Unieke identifier voor de multikleuren-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 responsstream 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-print-taakobject

Name
id
Type
string
Description
Unieke identificatie voor de taak. Hoewel we een k-sortable UUID gebruiken voor taak-id's als implementatiedetail, 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 terug te geven.
- Name
  3mf
  Type
  string
  Description
  Downloadbare URL naar het multicolor 3MF-bestand.
Name
progress
Type
integer
Description
Voortgang van de taak. Als de taak nog niet is gestart, 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 wanneer de taak is aangemaakt, in milliseconden.
Name
started_at
Type
timestamp
Description
Tijdstempel van wanneer 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 wanneer 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 taken met status FAILED (credits worden terugbetaald bij 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
}