Convert API

Met de Convert API kunt u bestaande 3D-modellen naar andere bestandsformaten converteren.

POST/openapi/v1/convert

Create a Convert Task

Deze endpoint maakt een nieuwe formaatconversietaak aan.

Parameters

Slechts één van input_task_id of model_url is verplicht. Als beide worden opgegeven, heeft input_task_id prioriteit.

  • Name
    input_task_id
    Type
    string
    Verplicht
    Description

    De ID van een voltooide Meshy-taak waarvan u het model wilt converteren. De taak moet de status SUCCEEDED hebben.

  • Name
    model_url
    Type
    string
    Verplicht
    Description

    Een openbaar toegankelijke URL of data-URI die verwijst naar een 3D-modelbestand. Ondersteunde formaten: .glb, .gltf, .obj, .fbx, .stl. Gebruik voor Data URI's het MIME type: application/octet-stream.

  • Name
    target_formats
    Type
    string[]
    Verplicht
    Description

    Een lijst met uitvoerformaten voor het geconverteerde model. Beschikbare waarden: glb, fbx, obj, usdz, blend, stl, 3mf.

Retourwaarden

De eigenschap result van de respons bevat de id van de nieuw aangemaakte conversietaak.

Faalscenario's

  • 400 - Bad Request

Het verzoek was onaanvaardbaar. Veelvoorkomende oorzaken:

  • Ontbrekende parameter: Er moet ofwel model_url ofwel input_task_id worden opgegeven.
  • Ontbrekende target_formats: Er moet ten minste één doelformaat worden opgegeven.
  • Ongeldige invoertaak: input_task_id moet verwijzen naar een succesvolle taak.
  • Ongeldig modelformaat: model_url verwijst naar een bestand met een niet-ondersteunde extensie.
  • Onbereikbare URL: model_url kon niet worden gedownload.
  • 401 - Unauthorized

Authenticatie is mislukt. Controleer uw API-sleutel.

  • 402 - Payment Required

Onvoldoende credits om deze taak uit te voeren.

  • 429 - Too Many Requests

U heeft uw rate limit overschreden.

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"
}
GET/openapi/v1/convert/:id

Een Convert-taak ophalen

Deze endpoint haalt een convert-taak op aan de hand van de ID ervan.

Parameters

  • Name
    id
    Type
    path
    Description

    De ID van de convert-taak die u wilt ophalen.

Retourneert

Het Convert Task-object.

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": {
      "glb": "",
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "obj": "",
      "usdz": "",
      "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
}
DELETE/openapi/v1/convert/:id

Een Convert-taak verwijderen

Dit endpoint verwijdert een convert-taak permanent, inclusief alle bijbehorende modellen en gegevens. Deze actie is onomkeerbaar.

Padparameters

  • Name
    id
    Type
    path
    Description

    De ID van de convert-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 doorlopen. Credits voor een taak waarmee de worker al is begonnen, worden niet terugbetaald, dus het verwijderen ervan tijdens de uitvoering zou je zowel de credits als het resultaat kosten. Wacht tot de taak SUCCEEDED, FAILED of CANCELED bereikt, en verwijder hem 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/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 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/convert

Lijst met Converteren-taken opvragen

Deze endpoint stelt u in staat om een lijst met converteertaken op te vragen.

Parameters

  • Name
    page_num
    Type
    integer
    standaard 1
    Description

    Paginanummer voor paginering.

  • Name
    page_size
    Type
    integer
    standaard 10
    Description

    Maximale paginagrootte. Het maximaal toegestane aantal 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.

Retourwaarden

Retourneert een gepagineerde lijst van The Convert Task Objects.

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
  }
]
GET/openapi/v1/convert/:id/stream

Stream een Convert-taak

Deze endpoint streamt realtime updates voor een convert-taak met behulp van Server-Sent Events (SSE).

Parameters

  • Name
    id
    Type
    path
    Description

    Unieke identifier voor de te streamen convert-taak.

Retourwaarden

Retourneert een stream van The Convert 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/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
}

Het Convert Task-object

Het Convert Task-object vertegenwoordigt een taak voor formaatconversie.

Eigenschappen

  • id · string

Unieke identificator voor de taak.

  • type · string

Type van de taak. De waarde is convert.

  • model_urls · object

Downloadbare URL's voor de geconverteerde modelbestanden. Alleen de formaten die in target_formats zijn opgegeven, hebben URL's. Andere formaateigenschappen zijn lege strings.

  • progress · integer

progress van de taak (0-100).

  • status · string

Status van de taak. Mogelijke waarden: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • preceding_tasks · integer

Het aantal voorafgaande taken. Alleen relevant wanneer de status PENDING is.

  • created_at · tijdstempel

tijdstempel van wanneer de taak is aangemaakt, in milliseconden.

  • started_at · tijdstempel

tijdstempel van wanneer de taak is gestart, in milliseconden. 0 als niet gestart.

  • finished_at · tijdstempel

tijdstempel van wanneer de taak is voltooid, in milliseconden. 0 als niet voltooid.

  • task_error · object

Foutobject als de taak is mislukt. Zie Fouten voor meer details.

  • consumed_credits · integer

Het aantal credits dat door deze taak is verbruikt (1 credit per convert-taak). Geeft 0 terug voor FAILED-taken.