Convert-API

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

POST/openapi/v1/convert

Eine Konvertierungsaufgabe erstellen

Dieser endpoint 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 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-Modelldatei verweist. Unterstützte Formate: .glb, .gltf, .obj, .fbx, .stl. Verwenden Sie für Data-URIs 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ückgabe

Die Eigenschaft result 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 auf eine erfolgreiche Aufgabe verweisen.
Ungültiges Modellformat: model_url verweist auf eine Datei mit einer nicht unterstützten Erweiterung.
Nicht erreichbare URL: model_url konnte nicht heruntergeladen werden.

401 - Unauthorized

Authentifizierung fehlgeschlagen. Bitte überprüfen Sie Ihre API key.

402 - Payment Required

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

429 - Too Many Requests

Sie haben Ihr Ratenlimit ü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

Eine Konvertierungsaufgabe abrufen

Dieser endpoint ruft eine Konvertierungsaufgabe anhand ihrer ID ab.

Parameter

Name
id
Type
path
Description
Die ID der abzurufenden Konvertierungsaufgabe.

Rückgabe

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

Konvertierungsaufgabe löschen

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

Pfadparameter

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

Rückgabe

Gibt bei Erfolg 200 OK zurück.

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

// Returns 200 Ok on success.

GET/openapi/v1/convert

Konvertierungsaufgaben auflisten

Dieser endpoint 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 zulässig sind 50 Elemente.

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

Rückgaben

Gibt eine paginierte Liste der Konvertierungsaufgaben-Objekte 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

Einen Convert-Task streamen

Dieser endpoint streamt Echtzeit-Updates für einen Convert-Task mithilfe von Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Eindeutige Kennung für den zu streamenden Convert-Task.

Rückgabe

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

Für Aufgaben mit PENDING oder IN_PROGRESS enthält der Antwortstream 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 Auftrag zur Formatkonvertierung dar.

Eigenschaften

id · string

Eindeutige Kennung für die Aufgabe.

type · string

Typ der Aufgabe. Der Wert ist convert.

model_urls · object

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

progress · integer

Fortschritt der Aufgabe (0–100).

status · string

Status der Aufgabe. Mögliche Werte: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

preceding_tasks · integer

Die Anzahl der vorhergehenden Aufgaben. Nur aussagekräftig, wenn der Status PENDING ist.

created_at · timestamp

Zeitstempel, zu dem die Aufgabe erstellt wurde, in Millisekunden.

started_at · timestamp

Zeitstempel, zu dem die Aufgabe gestartet wurde, in Millisekunden. 0, wenn sie nicht gestartet wurde.

finished_at · timestamp

Zeitstempel, zu dem die Aufgabe abgeschlossen wurde, in Millisekunden. 0, wenn sie nicht abgeschlossen wurde.

task_error · object

Fehlerobjekt, wenn die Aufgabe fehlgeschlagen ist. Weitere Details finden Sie unter Fehler.

consumed_credits · integer

Die Anzahl der von dieser Aufgabe verbrauchten Credits (1 Credit pro Konvertierungsaufgabe). Gibt bei FAILED-Aufgaben 0 zurück.