Convert API

Die Convert API ermöglicht es Ihnen, bestehende 3D-Modelle in andere Dateiformate zu konvertieren.

POST/openapi/v1/convert

Erstellen einer Konvertierungsaufgabe

Dieser Endpunkt erstellt eine neue Aufgabe zur Formatkonvertierung.

Parameter

Nur eines von input_task_id oder model_url ist erforderlich. Wenn beide angegeben werden, hat input_task_id Priorität.

Name
input_task_id
Type
string
Erforderlich
Description
Die ID einer abgeschlossenen Meshy-Aufgabe, deren Modell konvertiert werden soll. Die Aufgabe muss den Status SUCCEEDED haben.

Name
model_url
Type
string
Erforderlich
Description
Eine öffentlich zugängliche URL oder Data URI, die auf eine 3D-Modelldatei verweist. Unterstützte Formate: .glb, .gltf, .obj, .fbx, .stl. Für Data URIs verwenden Sie den MIME-Typ: application/octet-stream.

Name
target_formats
Type
string[]
Erforderlich
Description
Eine Liste der Ausgabeformate für das konvertierte Modell. Verfügbare Werte: glb, fbx, obj, usdz, blend, stl, 3mf.

Rückgabewerte

Die result-Eigenschaft der Antwort enthält die id der neu erstellten Konvertierungsaufgabe.

Fehlermodi

400 - Bad Request

Die Anfrage war unzulässig. Häufige Ursachen:

Fehlender Parameter: Entweder model_url oder input_task_id muss angegeben werden.
Fehlende target_formats: Es muss mindestens ein Zielformat angegeben werden.
Ungültige Eingabeaufgabe: input_task_id muss sich auf eine erfolgreiche Aufgabe beziehen.
Ungültiges Modellformat: model_url verweist auf eine Datei mit einer nicht unterstützten Dateierweiterung.
Nicht erreichbare URL: model_url konnte nicht herunterladen werden.

401 - Unauthorized

Die Authentifizierung ist fehlgeschlagen. Bitte überprüfen Sie Ihren API-Schlüssel.

402 - Payment Required

Nicht genügend Credits, um diese Aufgabe auszuführen.

429 - Too Many Requests

Sie haben Ihre Ratenbegrenzung überschritten.

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

Einen Konvertierungs-Task abrufen

Dieser Endpunkt ruft einen Konvertierungs-Task anhand seiner ID ab.

Parameter

Name
id
Type
path
Description
Die ID des abzurufenden Konvertierungs-Tasks.

Rückgabewerte

Das Convert-Task-Objekt.

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

Einen Convert-Task löschen

Dieser Endpunkt löscht einen Convert-Task dauerhaft, einschließlich aller zugehörigen Modelle und Daten. Diese Aktion ist unwiderruflich.

Pfadparameter

Name
id
Type
path
Description
Die ID des zu löschenden Convert-Tasks.

Taskstatus

Ein Task, der sich noch im Status PENDING befindet, wird gelöscht, und die bei der Erstellung verbrauchten Credits werden erstattet.

Ein Task, der sich bereits IN_PROGRESS befindet, kann nicht gelöscht werden: Die Anfrage wird mit 409 Conflict abgelehnt, und der Task läuft weiter. Credits für einen Task, den der Worker bereits gestartet hat, sind nicht erstattungsfähig. Ein Löschen während der Ausführung würde Sie sowohl die Credits als auch das Ergebnis kosten. Warten Sie, bis der Status SUCCEEDED, FAILED oder CANCELED erreicht ist, und löschen Sie ihn dann.

Ein Task in einem Endzustand (SUCCEEDED, FAILED oder CANCELED) wird ohne Rückerstattung gelöscht.

Rückgabewerte

Gibt bei Erfolg 200 OK zurück, oder 409 Conflict, wenn sich der Task im Status IN_PROGRESS befindet.

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

Konvertierungsaufgaben auflisten

Dieser Endpunkt ermöglicht es Ihnen, eine Liste von Konvertierungsaufgaben abzurufen.

Parameter

Name
page_num
Type
integer
Standard 1
Description
Seitennummer für die Paginierung.

Name
page_size
Type
integer
Standard 10
Description
Begrenzung der Seitengröße. Maximal erlaubt sind 100 Einträge.

Name
sort_by
Type
string
Description
Feld, nach dem sortiert werden soll. Verfügbare Werte:
- +created_at: Sortierung nach Erstellungszeit in aufsteigender Reihenfolge.
- -created_at: Sortierung nach Erstellungszeit in absteigender Reihenfolge.

Rückgabewerte

Gibt eine paginierte Liste von Convert-Task-Objekten zurück.

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

Convert-Task streamen

Dieser Endpunkt streamt Echtzeit-Updates für einen Konvertierungs-Task mittels Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Eindeutige Kennung des zu streamenden Konvertierungs-Tasks.

Rückgabewerte

Gibt einen Stream von Convert Task Objects als Server-Sent Events zurück.

Bei Tasks mit dem Status PENDING oder IN_PROGRESS enthält der Antwort-Stream nur die notwendigen Felder progress und 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
}

Das Convert-Task-Objekt

Das Convert-Task-Objekt stellt einen Formatkonvertierungs-Auftrag dar.

Eigenschaften

id · string

Eindeutige Kennung für den Task.

type · string

Typ des Tasks. Der Wert ist convert.

model_urls · object

Herunterladbare URLs für die konvertierten Modelldateien. Nur die in target_formats angegebenen Formate erhalten URLs. Andere Formateigenschaften sind leere Zeichenketten.

progress · integer

progress des Tasks (0-100).

status · string

Status des Tasks. Mögliche Werte: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

preceding_tasks · integer

Die Anzahl der vorangehenden Tasks. Nur relevant, wenn der Status PENDING ist.

created_at · Zeitstempel

Zeitstempel der Erstellung des Tasks, in Millisekunden.

started_at · Zeitstempel

Zeitstempel des Starts des Tasks, in Millisekunden. 0, wenn noch nicht gestartet.

finished_at · Zeitstempel

Zeitstempel des Abschlusses des Tasks, in Millisekunden. 0, wenn noch nicht abgeschlossen.

task_error · object

Fehlerobjekt, falls der Task fehlgeschlagen ist. Weitere Details finden Sie unter Fehler.

consumed_credits · integer

Die Anzahl der von diesem Task verbrauchten Credits (1 Credit pro Convert-Task). Gibt 0 für FAILED-Tasks zurück.