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

Een Multi-kleur 3D-printtaak aanmaken

Dit endpoint maakt een nieuwe multi-kleur 3D-printtaak aan. De taak converteert een 3D-model naar een multi-kleur 3MF-bestand geschikt voor 3D-printen.

Parameters

Slechts één van input_task_id of model_url is vereist. Als beide worden meegegeven, heeft input_task_id prioriteit.

  • 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

    Maximum 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 uit de textuur van het model voor fijn, fotorealistisch detail. Produceert een groter bestand.
    • cartoon: Vereenvoudigt kleuren tot nette, uniforme gebieden voor een gestileerde look. Produceert een kleiner bestand.

    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.

Retourwaarden

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

Faalmodi

  • Name
    400 - Bad Request
    Description

    Het verzoek was onaanvaardbaar. Veelvoorkomende oorzaken:

    • Ontbrekende parameter: Ofwel model_url ofwel input_task_id moet worden meegegeven.
    • 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.
    • Geen kleurbron: Het inputmodel heeft geen basiskleurtextuur (realistic heeft er één nodig, met UV's, op elk mesh-onderdeel) en geen vertexkleuren (cartoon accepteert beide). Voorzie het model eerst van een textuur, of gebruik cartoon voor modellen met vertexkleuren. .fbx-uploads worden gecontroleerd nadat de taak ze heeft genormaliseerd en falen dan met model_missing_texture in plaats daarvan.
  • Name
    401 - Unauthorized
    Description

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

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
}