Convert API

Converteer een 3D-model naar andere bestandsformaten, vanuit een Meshy-taak of vanuit een modelbestand.

POST/openapi/v1/convert

Een Convert-taak aanmaken

Maakt een Convert-taak aan. De taak wordt op de achtergrond uitgevoerd. Voor een indicatie van de duur van een taak, zie Verwerkingstijden.

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

Parameters

Name
input_task_id
Type
string
Verplicht
Description
Vereist, tenzij je model_url meestuurt. De ID van een taak die een 3D-model heeft opgeleverd, bijvoorbeeld een Tekst naar 3D-, Afbeelding naar 3D-, Remesh-, Formaat wijzigen- of Hertextureren-taak. De taak moet afkomstig zijn van de API en de status SUCCEEDED hebben.

Name
model_url
Type
string
Verplicht
Description
Vereist, tenzij je input_task_id meestuurt. Het te converteren model, als openbare URL of als data-URI. Als je beide meestuurt, gebruikt Meshy input_task_id.
Het model moet een GLB-, glTF-, OBJ-, FBX- of STL-bestand zijn van maximaal 400 MB vanaf een http- of https-URL, of 100 MB als data-URI. Gebruik voor een data-URI het MIME type application/octet-stream.
Een bestand groter dan 100 MB moet bovendien aan deze regels voldoen:
- Een GLB-, glTF-, FBX- of OBJ-bestand mag maximaal 10.000.000 vlakken hebben. Meshy telt vlakken als driehoeken, dus een vierhoek telt als 2, en een mesh die meerdere keren getekend wordt, telt per kopie.
- Een FBX-bestand moet binaire FBX 7.1 of nieuwer zijn.
- Een GLB- of glTF-bestand mag geen Draco-compressie gebruiken.

Name
target_formats
Type
string[]
Verplicht
Description
De te genereren bestandsindelingen. Vermeld er minstens één. Een ontbrekende of lege lijst resulteert in 400.
Beschikbare waarden:
- glb
- fbx
- obj
- usdz
- blend
- stl
- 3mf

Resultaten

Het veld result in de respons bevat de ID van de nieuwe Convert-taak.

Foutmodi

Name
400 - Bad Request
Description
Het verzoek kan niet worden uitgevoerd. Het foutbericht geeft aan welk probleem er is gevonden. Bijvoorbeeld:
- Ontbrekende parameter: Er is geen model_url of input_task_id meegestuurd.
- Ontbrekende target_formats: target_formats ontbreekt of bevat geen enkele indeling.
- Ongeldige invoertaak: input_task_id is geen geslaagde API-taak met een modelbestand.
- Ongeldige modelindeling: Het bestand bij model_url heeft een niet-ondersteunde extensie.
- Onbereikbare URL: Meshy kan het bestand bij model_url niet downloaden.
- Modelbestand te groot: Het bestand bij model_url is groter dan 400 MB vanaf een http- of https-URL, of groter dan 100 MB als data-URI.
- Te veel vlakken: Het bestand bij model_url is groter dan 100 MB en heeft meer dan 10.000.000 vlakken. Verminder het aantal vlakken en stuur het bestand opnieuw.
- ASCII-FBX groter dan 100 MB: Het bestand bij model_url is een ASCII-FBX groter dan 100 MB. Stuur het als binaire FBX of GLB.
- Onleesbaar modelbestand: Het bestand bij model_url is groter dan 100 MB en Meshy kan de header niet lezen. Bijvoorbeeld een Draco-gecomprimeerde GLB of glTF, of een binaire FBX ouder dan 7.1.
- Modelheader te complex: Het bestand bij model_url is groter dan 100 MB, en de header bevat te veel meshes, nodes of records om te controleren. Verminder het aantal objecten in het bestand en stuur het opnieuw.
Corrigeer het verzoek en stuur het opnieuw. Zie Fouten.
Name
401 - Unauthorized
Description
De API-sleutel ontbreekt of is ongeldig. Controleer de Authorization-header.
Name
402 - Payment Required
Description
Bijvoorbeeld:
- Onvoldoende credits: Het account heeft niet genoeg credits voor deze taak, of het account heeft een creditlimiet bereikt. Controleer je creditsaldo en probeer het opnieuw.
- Gratis abonnement: Voor het aanmaken van een taak is een betaald abonnement vereist. Upgrade je abonnement in je abonnementsinstellingen en probeer het opnieuw.
Name
403 - Forbidden
Description
input_task_id is een bas-reliëfmodel, dat deze endpoint niet kan converteren. Het bericht luidt This model type does not support this operation. Stuur een ander model.
Name
404 - Not Found
Description
input_task_id komt niet overeen met een van je taken. Controleer de taak-ID en stuur het verzoek opnieuw.
Name
429 - Too Many Requests
Description
Je hebt je rate limit overschreden. Wacht en probeer het opnieuw. Zie Rate limits.

GET/openapi/v1/convert/:id

Haal een Converteren-taak op

Retourneert een Converteren-taak op basis van de 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
}

Parameters

Name
id
Type
path
Description
De taak-ID uit het aanmaakantwoord.

Retourwaarden

Het Convert task object.

DELETE/openapi/v1/convert/:id

Delete a Convert task

Verwijdert een Convert-taak permanent, inclusief de bijbehorende modellen en gegevens. U kunt een verwijdering niet ongedaan maken.

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

Padparameters

Name
id
Type
path
Description
De ID van de taak die moet worden verwijderd.

Taakstatus

Het verwijderen van een PENDING-taak betaalt de credits terug die werden gebruikt bij het aanmaken ervan.

Een IN_PROGRESS-taak kan niet worden verwijderd. Het verzoek geeft 409 Conflict terug, en de taak blijft draaien. Meshy betaalt geen credits terug voor een taak die al is gestart, dus het verwijderen ervan zou u zowel de credits als het resultaat kosten. Wacht tot de taak SUCCEEDED, FAILED of CANCELED bereikt, en verwijder deze dan.

Het verwijderen van een taak met een eindstatus (SUCCEEDED, FAILED of CANCELED) betaalt de credits niet terug.

Retourwaarden

200 OK wanneer de taak is verwijderd, of 409 Conflict wanneer de taak IN_PROGRESS is.

GET/openapi/v1/convert

Lijst van Converteren-taken

Geeft een lijst van uw Converteren-taken terug.

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

Parameters

Name
page_num
Type
integer
standaard 1
Description
Het paginanummer dat moet worden teruggegeven, tot 255. Een hogere waarde geeft 400 terug.

Name
page_size
Type
integer
standaard 10
Description
Het aantal taken per pagina, tot 100.

Name
sort_by
Type
string
Description
De sorteervolgorde.
Beschikbare waarden:
- +created_at: oudste eerst
- -created_at: nieuwste eerst

Returns

Een gepagineerde lijst van Convert-taakobjecten.

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

Stream een Convert-taak

Streamt de updates van een Convert-taak als 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
}

Parameters

Name
id
Type
path
Description
De taak-ID uit de create-respons.

Retourwaarden

Een stream van Convert-taakobjecten als Server-Sent Events.

Elk event bevat het volledige taakobject, in dezelfde vorm als het Get-endpoint retourneert. Zolang de taak PENDING of IN_PROGRESS is, hebben de resultaatvelden nog geen waarden.

Het Convert-taakobject

Een Convert-taakobject beschrijft één formaatconversie van een 3D-model. Het bevat de status, de progress en de modelbestanden wanneer de taak slaagt.

Eigenschappen

Name
id
Type
string
Description
De taak-ID. Behandel dit als een ondoorzichtige string en vertrouw niet op het formaat ervan.
Name
type
Type
string
Description
Het taaktype, altijd convert.
Name
model_urls
Type
object
Description
Download-URL's voor het geconverteerde model, één per bestandsformaat. Alleen de formaten in target_formats hebben URL's. Een formaat dat je niet hebt aangevraagd heeft geen sleutel, in plaats van een lege string.
Name
progress
Type
integer
Description
Hoeveel van de taak voltooid is, als percentage. Dit is 0 totdat de taak start en 100 wanneer deze slaagt.
Name
status
Type
string
Description
De taakstatus, één van PENDING, IN_PROGRESS, SUCCEEDED, FAILED of CANCELED.
Name
preceding_tasks
Type
integer
Description
Het aantal taken dat vóór deze taak in de wachtrij staat. De waarde is alleen relevant zolang de taak PENDING is.
Name
created_at
Type
timestamp
Description
Tijdstip waarop de taak is aangemaakt, in Unix-milliseconden.
Name
started_at
Type
timestamp
Description
Tijdstip waarop de taak is gestart, in Unix-milliseconden. Dit is 0 totdat de taak start.
Name
finished_at
Type
timestamp
Description
Tijdstip waarop de taak is beëindigd, in Unix-milliseconden. Dit is 0 totdat de taak eindigt.
Name
expires_at
Type
timestamp
Description
Tijdstip waarop de download-URL's van de taak verlopen, in Unix-milliseconden. Dit is 0 totdat de taak eindigt.
Name
texture_urls
Type
array
Description
Download-URL's voor de textuurkaarten van het model, wanneer de taak slaagt: een array van objecten, één per textuurset. Elk object heeft een base_color-URL en kan ook metallic-, roughness-, normal-, emission- en metallic_roughness-URL's hebben. Dit is null totdat de taak slaagt, en een lege array wanneer het model geen textuurkaarten heeft.
Name
task_error
Type
object
Description
De foutdetails wanneer de taak mislukt. Zie Fouten.
Name
consumed_credits
Type
integer
Description
Het aantal credits dat de taak heeft gebruikt, wat 1 is voor een Convert-taak. Dit is 0 voor een FAILED-taak.