API för flerfärgsutskrift

Konvertera 3D-modeller till flerfärgat 3MF-format för 3D-utskrift, med en konfigurerbar färgpalett med upp till 16 färger.

POST/openapi/v1/print/multi-color

Create a Multi-Color 3D Print Task

Denna endpoint skapar en ny flerfärgad 3D-utskriftsuppgift. Uppgiften konverterar en 3D-modell till en flerfärgad 3MF-fil som är lämplig för 3D-utskrift.

Parametrar

Endast en av input_task_id eller model_url är obligatorisk. Om båda anges har input_task_id prioritet.

  • Name
    model_url
    Type
    string
    Obligatorisk
    Description

    Offentligt tillgänglig URL eller Data URI för en 3D-modell. Vi stöder för närvarande formaten .glb och .fbx.

  • Name
    max_colors
    Type
    integer
    standard 4
    Description

    Maximalt antal färger i den genererade paletten.

    Giltigt intervall: 1 till 16.

  • Name
    style
    Type
    string
    standard realistic
    Description

    Visuell färgstil för den genererade 3MF-filen.

    Tillgängliga värden:

    • realistic: Samplar färger direkt från modellens textur för fina, fotorealistiska detaljer. Ger en större fil.
    • cartoon: Plattar till färger i rena, enhetliga områden för ett stiliserat utseende. Ger en mindre fil.

    Indatan måste innehålla färg: realistic kräver en enda bastexturkarta med UV-koordinater på varje nätdel; cartoon accepterar även färger per vertex. Modeller utan textur (vita) avvisas — se model_missing_texture.

Returvärden

Svarets result-egenskap innehåller id för den nyskapade 3D-utskriftsuppgiften.

Felscenarier

  • Name
    400 - Bad Request
    Description

    Begäran kunde inte godtas. Vanliga orsaker:

    • Saknad parameter: Antingen model_url eller input_task_id måste anges.
    • Ogiltigt modellformat: model_url pekar på en fil med en filändelse som inte stöds (endast .glb och .fbx stöds).
    • Onåbar URL: model_url kunde inte laddas ner.
    • Ogiltig inmatningsuppgift: input_task_id måste referera till en lyckad uppgift.
    • Ogiltigt max_colors: Värdet måste vara mellan 1 och 16.
    • Ogiltig style: Värdet måste vara realistic eller cartoon.
    • Ingen färgkälla: Indatamodellen saknar bastexturkarta (realistic behöver en enda, med UV, på varje nätdel) och saknar vertexfärger (cartoon accepterar antingen). Texturera modellen först, eller använd cartoon för modeller med vertexfärger. Uppladdningar av .fbx kontrolleras efter att uppgiften normaliserat dem och misslyckas med model_missing_texture istället.
  • Name
    401 - Unauthorized
    Description

    Autentiseringen misslyckades. Kontrollera din API-nyckel.

  • Name
    402 - Payment Required
    Description

    Otillräckliga credits för att utföra denna uppgift.

  • Name
    429 - Too Many Requests
    Description

    Du har överskridit din hastighetsgräns.

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

Hämta en flerfärgad 3D-utskriftsuppgift

Denna endpoint hämtar en flerfärgad 3D-utskriftsuppgift baserat på dess ID.

Parametrar

  • Name
    id
    Type
    path
    Description

    ID:t för 3D-utskriftsuppgiften som ska hämtas.

Returnerar

3D Print Task-objektet.

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

Ta bort en flerfärgad 3D-utskriftsuppgift

Denna endpoint tar permanent bort en flerfärgad 3D-utskriftsuppgift, inklusive alla tillhörande modeller och data. Denna åtgärd kan inte ångras.

Sökvägsparametrar

  • Name
    id
    Type
    path
    Description

    ID:t för den flerfärgade 3D-utskriftsuppgift som ska tas bort.

Uppgiftsstatus

En uppgift som fortfarande är PENDING tas bort och de credits som förbrukades vid skapandet återbetalas.

En uppgift som redan är IN_PROGRESS kan inte tas bort: begäran avvisas med 409 Conflict och uppgiften fortsätter att köras. Credits för en uppgift som arbetaren redan har påbörjat kan inte återbetalas, så att ta bort den mitt i körningen skulle kosta dig både credits och resultatet. Vänta tills den når SUCCEEDED, FAILED eller CANCELED, och ta sedan bort den.

En uppgift i ett slutgiltigt tillstånd (SUCCEEDED, FAILED eller CANCELED) tas bort utan återbetalning.

Returer

Returnerar 200 OK vid framgång, eller 409 Conflict när uppgiften är IN_PROGRESS.

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

Lista flerfärgade 3D-utskriftsuppgifter

Denna endpoint gör det möjligt att hämta en lista över flerfärgade 3D-utskriftsuppgifter.

Parametrar

Valfria attribut

  • Name
    page_num
    Type
    integer
    Description

    Sidnummer för paginering. Börjar på och har som standardvärde 1.

  • Name
    page_size
    Type
    integer
    Description

    Gräns för sidstorlek. Standardvärdet är 10 objekt. Max tillåtet är 100 objekt.

  • Name
    sort_by
    Type
    string
    Description

    Fält att sortera efter. Tillgängliga värden:

    • +created_at: Sortera efter skapandetid i stigande ordning.
    • -created_at: Sortera efter skapandetid i fallande ordning.

Returnerar

Returnerar en paginerad lista med 3D-utskriftsuppgiftsobjekt.

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

Strömma en flerfärgad 3D-utskriftsuppgift

Denna endpoint strömmar realtidsuppdateringar för en flerfärgad 3D-utskriftsuppgift med hjälp av Server-Sent Events (SSE).

Parametrar

  • Name
    id
    Type
    path
    Description

    Unik identifierare för den flerfärgade 3D-utskriftsuppgift som ska strömmas.

Returnerar

Returnerar en ström av 3D-utskriftsuppgiftsobjekt som Server-Sent Events.

För uppgifter med status PENDING eller IN_PROGRESS kommer svarsströmmen endast att innehålla nödvändiga fält för progress och 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
}

3D-utskriftsobjektet (Task)

  • Name
    id
    Type
    string
    Description

    Unik identifierare för uppgiften (task). Även om vi använder en k-sorterbar UUID som implementationsdetalj för uppgifts-id:n, bör du inte göra några antaganden om id:ts format.

  • Name
    type
    Type
    string
    Description

    Typ av 3D-utskriftsuppgift. Värdet är print-multi-color.

  • Name
    model_urls
    Type
    object
    Description

    Nedladdningsbar URL till 3D-modellfilen som genererats av Meshy. Egenskapen för ett format utelämnas om formatet inte har genererats, istället för att returnera en tom sträng.

    • Name
      3mf
      Type
      string
      Description

      Nedladdningsbar URL till 3MF-filen med flera färger.

  • Name
    progress
    Type
    integer
    Description

    Progress för uppgiften. Om uppgiften ännu inte har startat är denna egenskap 0. När uppgiften har lyckats blir den 100.

  • Name
    status
    Type
    string
    Description

    Status för uppgiften. Möjliga värden är ett av PENDING, IN_PROGRESS, SUCCEEDED, FAILED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Antalet föregående uppgifter i kön.

    Värdet i detta fält är endast meningsfullt om uppgiftens status är PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Tidsstämpel för när uppgiften skapades, i millisekunder.

  • Name
    started_at
    Type
    timestamp
    Description

    Tidsstämpel för när uppgiften startades, i millisekunder. Om uppgiften ännu inte har startat är denna egenskap 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Tidsstämpel för när uppgiften avslutades, i millisekunder. Om uppgiften ännu inte är avslutad är denna egenskap 0.

  • Name
    task_error
    Type
    object
    Description

    Feldetaljer för misslyckade uppgifter. Se Fel för den fullständiga referensen till objektet task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Antalet credits som förbrukats av denna uppgift. Finns med när uppgiftens status är PENDING, IN_PROGRESS eller SUCCEEDED. Returnerar 0 för FAILED-uppgifter (credits återbetalas vid misslyckande).

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
}