Konvertieren API

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

POST/openapi/v1/convert

Erstellen einer Konvertierungsaufgabe

Dieser Endpunkt erstellt eine neue Formatkonvertierungsaufgabe.

Parameter

Nur einer von input_task_id oder model_url ist erforderlich. Wenn beide angegeben sind, hat input_task_id Vorrang.

Name
input_task_id
Type
string
Erforderlich
Description
Die ID einer abgeschlossenen Meshy-Aufgabe, deren Modell Sie konvertieren möchten. 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-Modell-Datei zeigt. 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 von Ausgabeformaten für das konvertierte Modell. Verfügbare Werte: glb, fbx, obj, usdz, blend, stl, 3mf.

Rückgaben

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

Fehlermodi

400 - Bad Request

Die Anfrage war nicht akzeptabel. Häufige Ursachen:

Fehlender Parameter: Entweder model_url oder input_task_id muss angegeben werden.
Fehlendes target_formats: Mindestens ein Zielformat muss angegeben werden.
Ungültige Eingabeaufgabe: Die input_task_id muss auf eine erfolgreiche Aufgabe verweisen.
Ungültiges Modellformat: Die model_url verweist auf eine Datei mit einer nicht unterstützten Erweiterung.
Nicht erreichbare URL: Die model_url konnte nicht heruntergeladen werden.

401 - Unauthorized

Authentifizierung 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.

Anfrage

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

Antwort

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/convert/:id

Abrufen einer Konvertierungsaufgabe

Dieser Endpunkt ruft eine Konvertierungsaufgabe anhand ihrer ID ab.

Parameter

Name
id
Type
path
Description
Die ID der abzurufenden Konvertierungsaufgabe.

Rückgaben

Das Convert Task-Objekt.

Anfrage

GET

/openapi/v1/convert/:id

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

Antwort

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

Löschen einer Konvertierungsaufgabe

Dieser Endpunkt löscht dauerhaft eine Konvertierungsaufgabe, einschließlich aller zugehörigen Modelle und Daten. Diese Aktion ist unwiderruflich.

Pfadparameter

Name
id
Type
path
Description
Die ID der zu löschenden Konvertierungsaufgabe.

Rückgaben

Gibt 200 OK bei Erfolg zurück.

Anfrage

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

Antwort

// Returns 200 Ok on success.

GET/openapi/v1/convert

Liste der Konvertierungsaufgaben

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
Seitengrößenlimit. Maximal erlaubt sind 50 Elemente.

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ückgaben

Gibt eine paginierte Liste von The Convert Task Objects zurück.

Anfrage

GET

/openapi/v1/convert

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

Antwort

[
  {
    "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

Streamen einer Konvertierungsaufgabe

Dieser Endpunkt streamt Echtzeit-Updates für eine Konvertierungsaufgabe unter Verwendung von Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Eindeutiger Bezeichner für die zu streamende Konvertierungsaufgabe.

Rückgaben

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

Für PENDING oder IN_PROGRESS Aufgaben enthält der Antwortstream nur die notwendigen progress und status Felder.

Anfrage

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

Antwortstream

// 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 repräsentiert einen Formatkonvertierungsauftrag.

Eigenschaften

id · string

Eindeutiger Bezeichner für den Auftrag.

type · string

Typ des Auftrags. Der Wert ist convert.

model_urls · object

Herunterladbare URLs für die konvertierten Modell-Dateien. Nur die in target_formats angegebenen Formate werden URLs haben. Andere Format-Eigenschaften werden leere Zeichenfolgen sein.

progress · integer

Fortschritt des Auftrags (0-100).

status · string

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

preceding_tasks · integer

Die Anzahl der vorhergehenden Aufträge. Nur sinnvoll, wenn der Status PENDING ist.

created_at · timestamp

Zeitstempel, wann der Auftrag erstellt wurde, in Millisekunden.

started_at · timestamp

Zeitstempel, wann der Auftrag gestartet wurde, in Millisekunden. 0, wenn nicht gestartet.

finished_at · timestamp

Zeitstempel, wann der Auftrag abgeschlossen wurde, in Millisekunden. 0, wenn nicht abgeschlossen.

task_error · object

Fehlerobjekt, falls der Auftrag fehlgeschlagen ist. Siehe Fehler für weitere Details.

consumed_credits · integer

Die Anzahl der von diesem Auftrag verbrauchten Credits (1 Credit pro Konvertierungsauftrag). Gibt 0 für FAILED Aufträge zurück.