API för flerfärgsutskrift

Konvertera en 3D-modell till en 3MF-fil för flerfärgsutskrift vid 3D-utskrift. Välj en palett med upp till 16 färger och en slicer-förinställning för ditt skrivarmärke.

POST/openapi/v1/print/multi-color

Skapa en flerfärgsutskriftsuppgift

Skapar en flerfärgsutskriftsuppgift, som konverterar en 3D-modell till en 3MF-fil med flera färger för 3D-utskrift. Uppgiften körs i bakgrunden. För information om hur lång tid en uppgift vanligtvis tar, se Processing times.

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

Parametrar

Name
input_task_id
Type
string
Obligatorisk
Description
Krävs om du inte skickar model_url. ID:t för den uppgift vars modell du vill skriva ut, till exempel en Bild till 3D-, Flera bilder till 3D-, Text till 3D-, Remesh- eller Omtexturering-uppgift. Uppgiften måste vara en som du skapade med API:et, och ha statusen SUCCEEDED.
Flerfärgsutskrift läser uppgiftens GLB-fil, som kan ha som mest 8 000 000 ytor (faces). En modell med fler ytor returnerar 400. Kör i så fall en Remesh-uppgift på den först, och skicka Remesh-uppgiftens ID istället.

Name
model_url
Type
string
Obligatorisk
Description
Krävs om du inte skickar input_task_id. Modellen som ska skrivas ut, som en offentlig URL eller en Data URI. Om du skickar båda använder Meshy input_task_id.
En http- eller https-URL måste peka på en .glb- eller .fbx-fil på högst 400 MB. En Data URI måste innehålla en base64-kodad GLB-fil på högst 100 MB. Använd data:model/gltf-binary;base64,. Skicka en .fbx-fil som en http- eller https-URL.
En fil över 100 MB måste också följa dessa regler:
- Den kan ha som mest 8 000 000 ytor. Meshy räknar ytor som trianglar, så en fyrhörning räknas som 2, och ett nät som ritas mer än en gång räknas en gång per kopia.
- En FBX-fil måste vara binär FBX 7.1 eller nyare.
- En GLB-fil får inte använda Draco-komprimering.

Name
max_colors
Type
integer
standard 4
Description
Det maximala antalet färger i utdatapaletten, från 1 till 16. För att använda standardvärdet, utelämna det istället för att skicka 0.
Name
style
Type
string
standard realistic
Description
Färgstilen för 3MF-filen.
Tillgängliga värden:
- realistic: samplar färger direkt från modellens textur för fin, fotorealistisk detalj, och skapar en större fil.
- cartoon: plattar ut färger till rena, enhetliga regioner för ett stiliserat utseende, och skapar en mindre fil.
Modellen måste ha färg. realistic behöver en enda bastexturfärg, med UV:er på varje nätdel, och cartoon accepterar även vertexfärger. Meshy avvisar en otexturerad (vit) modell. Se model_missing_texture.
Name
max_depth
Type
integer
standard 4
Description
Underindelningsdjupet som Meshy använder för att sampla texturfärger på nätet, från 3 till 6. 0 är detsamma som att utelämna det. Högre värden fångar finare färgdetaljer, och skapar en större fil. Endast stilen realistic använder det, och cartoon ignorerar det.
Name
printer_brand
Type
string
standard bambu
Description
Skrivarmärket vars slicer-förinställning Meshy skriver in i 3MF-filen. Filen öppnas då i det märkets slicer med en matchande skrivare, filament och processprofil. Förinställningen använder märkets standardskrivare, med ett munstycke på 0,4 mm.
Tillgängliga värden:
- bambu
- anycubic
- creality
- elegoo
- flashforge
- prusa
- qidi
- snapmaker
- ankermake
Alla andra värden returnerar 400.

Returvärden

Fältet result i svaret innehåller ID:t för den nya flerfärgsutskriftsuppgiften.

Felscenarier

Name
400 - Bad Request
Description
Begäran kan inte köras. Felmeddelandet anger vilket problem det hittade. Till exempel:
- Saknad parameter: Varken model_url eller input_task_id skickades.
- Ogiltigt modellformat: model_url-filen är inte en .glb- eller .fbx-fil.
- Onåbar URL: Meshy kan inte ladda ner model_url-filen.
- Modellfilen för stor: model_url-filen är över 400 MB från en http- eller https-URL, eller över 100 MB som en Data URI.
- För många ytor: model_url-filen är över 100 MB och har fler än 8 000 000 ytor. Minska antalet ytor, och skicka sedan filen igen.
- ASCII FBX över 100 MB: model_url-filen är en ASCII FBX-fil över 100 MB. Skicka den som binär FBX eller GLB.
- Oläsbar modellfil: model_url-filen är över 100 MB, och Meshy kan inte läsa dess header. Till exempel är det en Draco-komprimerad GLB-fil, eller en binär FBX äldre än 7.1.
- Modellens header för komplex: model_url-filen är över 100 MB, och dess header har för många nät, noder eller poster att kontrollera. Minska antalet objekt i filen, och skicka den sedan igen.
- Ogiltig input-uppgift: input_task_id är inte en lyckad uppgift.
- För många ytor i input-uppgiften: input_task_id-modellen har fler än 8 000 000 ytor. Kör en Remesh-uppgift på den, och skicka sedan Remesh-uppgiftens ID istället.
- Ogiltig max_colors: max_colors är negativt eller över 16.
- Ogiltig style: style är varken realistic eller cartoon.
- Ogiltig max_depth: max_depth ligger utanför 3 till 6, och är inte 0.
- Ogiltig printer_brand: printer_brand är inte ett av de tillgängliga värdena.
- Ingen färgkälla: Modellen saknar den färg som style behöver. realistic behöver en enda bastexturfärg, med UV:er, på varje nätdel. cartoon accepterar en bastexturfärg eller vertexfärger. Texturera modellen först, eller använd cartoon för en modell med vertexfärger. Meshy kontrollerar en .fbx-uppladdning endast efter att uppgiften har normaliserat den, så uppgiften misslyckas istället med model_missing_texture.
Åtgärda begäran, och skicka den sedan igen. Se Fel.
Name
401 - Unauthorized
Description
API-nyckeln saknas eller är ogiltig. Kontrollera Authorization-headern.
Name
402 - Payment Required
Description
Till exempel:
- Otillräckliga credits: Kontot har inte tillräckligt med credits för denna uppgift, eller kontot har nått en creditgräns. Kontrollera ditt creditsaldo, och försök sedan igen.
- Gratisplan: Att skapa en uppgift kräver en betald plan. Uppgradera din plan i dina prenumerationsinställningar, och försök sedan igen.
Name
403 - Forbidden
Description
input_task_id är en basrelief-modell, som denna endpoint inte kan skriva ut. Meddelandet är This model type does not support this operation. Skicka en annan modell.
Name
404 - Not Found
Description
input_task_id matchar ingen av dina uppgifter. Kontrollera uppgifts-ID:t, och skicka sedan begäran igen.
Name
429 - Too Many Requests
Description
Du överskred din hastighetsgräns. Vänta, och försök sedan igen. Se Rate limits.

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

Hämta en flerfärgsutskriftsuppgift

Returnerar en flerfärgsutskriftsuppgift baserat på dess 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
}

Parametrar

Name
id
Type
path
Description
Uppgifts-ID:t från skapandesvaret.

Returnerar

Objektet för flerfärgsutskriftsuppgift.

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

Ta bort en flerfärgsutskriftsuppgift

Tar permanent bort en flerfärgsutskriftsuppgift, inklusive dess modeller och data. Du kan inte ångra en borttagning.

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

Sökvägsparametrar

Name
id
Type
path
Description
ID:t för uppgiften som ska tas bort.

Uppgiftsstatus

Om du tar bort en uppgift med status PENDING återbetalas de credits som användes när du skapade den.

En uppgift med status IN_PROGRESS kan inte tas bort. Förfrågan returnerar 409 Conflict, och uppgiften fortsätter att köras. Meshy återbetalar inte en uppgift som har startat, så att ta bort den skulle kosta dig både credits och resultatet. Vänta tills den når SUCCEEDED, FAILED eller CANCELED, och ta sedan bort den.

Att ta bort en uppgift med en slutgiltig status (SUCCEEDED, FAILED eller CANCELED) återbetalar inte dess credits.

Returvärden

200 OK när uppgiften har tagits bort, eller 409 Conflict när uppgiften är IN_PROGRESS.

GET/openapi/v1/print/multi-color

Lista flerfärgsutskriftsuppgifter

Returnerar en lista över dina flerfärgsutskriftsuppgifter.

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

Parametrar

Name
page_num
Type
integer
standard 1
Description
Sidnumret som ska returneras. Sidnummer börjar på 1.
Name
page_size
Type
integer
standard 10
Description
Antalet uppgifter per sida, upp till 100.
Name
sort_by
Type
string
Description
Sorteringsordningen.
Tillgängliga värden:
- +created_at: äldsta först
- -created_at: nyaste först

Returnerar

En paginerad lista med flerfärgsutskriftsuppgiftsobjekt.

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

Strömma en flerfärgsutskriftsuppgift

Strömmar uppdateringar för en flerfärgsutskriftsuppgift som 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
}

Parametrar

Name
id
Type
path
Description
Uppgifts-ID:t från skaparsvaret.

Returnerar

En ström av flerfärgsutskriftsuppgiftsobjekt som Server-Sent Events.

Varje händelse innehåller hela uppgiftsobjektet, i samma format som Get-endpointen returnerar. Medan uppgiften är PENDING eller IN_PROGRESS har dess resultatfält ännu inga värden.

Multi-Color Print-uppgiftsobjektet

Ett Multi-Color Print-uppgiftsobjekt beskriver en konvertering av en 3D-modell till en flerfärgad 3MF-fil. Det innehåller status, progress och 3MF-filen när uppgiften lyckas.

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
Uppgifts-ID:t. Behandla det som en ogenomskinlig sträng och förlita dig inte på dess format.
Name
type
Type
string
Description
Uppgiftstypen, alltid print-multi-color.
Name
model_urls
Type
object
Description
Nedladdningslänkar för den utskrivna modellen, en per filformat. Ett format som uppgiften inte genererade saknar nyckel, i stället för att ha en tom sträng.
- Name
  3mf
  Type
  string
  Description
  Den flerfärgade 3MF-filen.
Name
progress
Type
integer
Description
Hur stor del av uppgiften som är klar, i procent. Den är 0 tills uppgiften startar och 100 när den lyckas.
Name
status
Type
string
Description
Uppgiftens status, en av PENDING, IN_PROGRESS, SUCCEEDED, FAILED eller CANCELED.
Name
preceding_tasks
Type
integer
Description
Antalet uppgifter som ligger före denna i kön. Värdet är endast meningsfullt medan uppgiften är PENDING.
Name
created_at
Type
timestamp
Description
Tidpunkten då uppgiften skapades, i Unix-millisekunder.
Name
started_at
Type
timestamp
Description
Tidpunkten då uppgiften startade, i Unix-millisekunder. Den är 0 tills uppgiften startar.
Name
finished_at
Type
timestamp
Description
Tidpunkten då uppgiften avslutades, i Unix-millisekunder. Den är 0 tills uppgiften avslutas.
Name
expires_at
Type
timestamp
Description
Tidpunkten då uppgiftens resultat upphör att gälla, i Unix-millisekunder. Den är 0 tills uppgiften avslutas.
Name
task_error
Type
object
Description
Feldetaljerna när uppgiften misslyckas. Se Fel.
Name
consumed_credits
Type
integer
Description
Antalet credits som uppgiften använde. Finns med när statusen är PENDING, IN_PROGRESS eller SUCCEEDED. Den är 0 för en FAILED-uppgift, eftersom Meshy återbetalar credits när en uppgift misslyckas.