Konvertera API

Konvertera en 3D-modell till andra filformat, från en Meshy-uppgift eller från en modellfil.

POST/openapi/v1/convert

Skapa en Convert-uppgift

Skapar en Convert-uppgift. Uppgiften körs i bakgrunden. För information om hur lång tid en uppgift vanligtvis tar, se Bearbetningstider.

Request

POST

/openapi/v1/convert

curl https://api.meshy.ai/openapi/v1/convert \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["fbx", "stl"]
  }'

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 en uppgift som producerade en 3D-modell, till exempel en Text till 3D-, Bild till 3D-, Remesh-, Ändra storlek- eller Omtexturering-uppgift. Uppgiften måste komma från API:et och ha statusen SUCCEEDED.

Name
model_url
Type
string
Obligatorisk
Description
Krävs om du inte skickar input_task_id. Modellen som ska konverteras, antingen som en offentlig URL eller en Data URI. Om du skickar båda använder Meshy input_task_id.
Modellen måste vara en GLB-, glTF-, OBJ-, FBX- eller STL-fil på högst 400 MB från en http- eller https-URL, eller 100 MB som en Data URI. För en Data URI, använd MIME type application/octet-stream.
En fil över 100 MB måste även följa dessa regler:
- En GLB-, glTF-, FBX- eller OBJ-fil kan ha som mest 10 000 000 ytor. Meshy räknar ytor som trianglar, så en fyrhörning räknas som 2, och ett nät som ritas flera gånger räknas en gång per kopia.
- En FBX-fil måste vara binär FBX 7.1 eller nyare.
- En GLB- eller glTF-fil får inte använda Draco-komprimering.

Name
target_formats
Type
string[]
Obligatorisk
Description
Filformaten som ska genereras. Ange minst ett. En saknad eller tom lista returnerar 400.
Tillgängliga värden:
- glb
- fbx
- obj
- usdz
- blend
- stl
- 3mf

Returnerar

Fältet result i svaret innehåller ID:t för den nya Convert-uppgiften.

Felscenarier

Name
400 - Bad Request
Description
Begäran kan inte köras. Felmeddelandet anger vilket problem som hittades. Till exempel:
- Saknad parameter: Varken model_url eller input_task_id skickades.
- Saknad target_formats: target_formats saknas eller listar inget format.
- Ogiltig indatauppgift: input_task_id är inte en lyckad API-uppgift med en modellfil.
- Ogiltigt modellformat: Filen i model_url har ett filtillägg som inte stöds.
- Oåtkomlig URL: Meshy kan inte hämta filen i model_url.
- Modellfilen är för stor: Filen i model_url är över 400 MB från en http- eller https-URL, eller över 100 MB som en Data URI.
- För många ytor: Filen i model_url är över 100 MB och har fler än 10 000 000 ytor. Minska antalet ytor och skicka sedan filen igen.
- ASCII FBX över 100 MB: Filen i model_url är en ASCII FBX över 100 MB. Skicka den som binär FBX eller GLB.
- Oläsbar modellfil: Filen i model_url är över 100 MB, och Meshy kan inte läsa dess header. Det kan till exempel vara en Draco-komprimerad GLB eller glTF, eller en binär FBX äldre än 7.1.
- Modellens header för komplex: Filen i model_url ä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.
Åtgärda begäran och skicka den 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 den här uppgiften, eller kontot har nått en creditgräns. Kontrollera ditt credit-saldo och försök igen.
- Gratisplan: Att skapa en uppgift kräver en betalplan. Uppgradera din plan i dina prenumerationsinställningar och försök igen.
Name
403 - Forbidden
Description
input_task_id är en basreliefmodell, vilket den här endpointen inte kan konvertera. 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 begäran igen.
Name
429 - Too Many Requests
Description
Du överskred din hastighetsgräns. Vänta och försök igen. Se Hastighetsgränser.

GET/openapi/v1/convert/:id

Hämta en Convert-uppgift

Returnerar en Convert-uppgift baserat på dess ID.

Request

GET

/openapi/v1/convert/:id

curl https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

Parametrar

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

Returnerar

Convert-uppgiftsobjektet.

DELETE/openapi/v1/convert/:id

Ta bort en Convert-uppgift

Tar bort en Convert-uppgift permanent, inklusive dess modeller och data. Du kan inte ångra en borttagning.

Request

DELETE

/openapi/v1/convert/:id

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/convert/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 PENDING-uppgift återbetalas de credits som användes när du skapade den.

En IN_PROGRESS-uppgift kan inte tas bort. Begäran returnerar 409 Conflict, och uppgiften fortsätter att köras. Meshy återbetalar inte en uppgift som har påbörjats, 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 slutlig status (SUCCEEDED, FAILED eller CANCELED) återbetalar inte dess credits.

Returnerar

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

GET/openapi/v1/convert

Lista Konvertera-uppgifter

Returnerar en lista över dina Konvertera-uppgifter.

Request

GET

/openapi/v1/convert

curl https://api.meshy.ai/openapi/v1/convert?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "convert",
    "model_urls": {
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
    "consumed_credits": 1
  }
]

Parametrar

Name
page_num
Type
integer
standard 1
Description
Sidnumret som ska returneras, upp till 255. Ett större värde returnerar 400.

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 över Convert task-objekt.

GET/openapi/v1/convert/:id/stream

Streama en Convert-uppgift

Streamar uppdateringar för en Convert-uppgift som Server-Sent Events (SSE).

Request

GET

/openapi/v1/convert/:id/stream

curl -N https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Message event examples illustrate task progress.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
    "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
    "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

Parametrar

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

Returnerar

En ström av Convert task-objekt som Server-Sent Events.

Varje event 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.

Convert-objektet för uppgiften

Ett Convert-uppgiftsobjekt beskriver en formatkonvertering av en 3D-modell. Det innehåller status, progress och modellfilerna när uppgiften lyckas.

Egenskaper

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 convert.
Name
model_urls
Type
object
Description
Nedladdningslänkar för den konverterade modellen, en per filformat. Endast formaten i target_formats har länkar. Ett format du inte begärde saknar nyckel, istället för att ha en tom sträng.
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 före den här 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 nedladdningslänkar upphör att gälla, i Unix-millisekunder. Den är 0 tills uppgiften avslutas.
Name
texture_urls
Type
array
Description
Nedladdningslänkar för modellens texturkartor, när uppgiften lyckas: en array av objekt, ett per texturuppsättning. Varje objekt har en base_color-länk, och kan även ha länkar för metallic, roughness, normal, emission och metallic_roughness. Den är null tills uppgiften lyckas, och en tom array när modellen saknar texturkartor.
Name
task_error
Type
object
Description
Feldetaljerna när uppgiften misslyckas. Se Fel.
Name
consumed_credits
Type
integer
Description
Antalet credits uppgiften använde, vilket är 1 för en Convert-uppgift. Den är 0 för en FAILED-uppgift.