Convert API

Konvertieren Sie ein 3D-Modell in andere Dateiformate, aus einer Meshy-Aufgabe oder aus einer Modelldatei.

POST/openapi/v1/convert

Erstellen einer Convert-Aufgabe

Erstellt eine Convert-Aufgabe. Die Aufgabe läuft im Hintergrund. Wie lange eine Aufgabe normalerweise dauert, erfahren Sie unter Processing times.

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

Parameter

Name
input_task_id
Type
string
Erforderlich
Description
Erforderlich, sofern Sie nicht model_url senden. Die ID der Meshy-Aufgabe, deren Modell Sie konvertieren möchten. Die Aufgabe muss den Status SUCCEEDED haben.

Name
model_url
Type
string
Erforderlich
Description
Erforderlich, sofern Sie nicht input_task_id senden. Das zu konvertierende Modell, als öffentliche URL oder als Data URI. Wenn Sie beides senden, verwendet Meshy input_task_id.
Das Modell muss eine GLB-, glTF-, OBJ-, FBX- oder STL-Datei mit höchstens 400 MB sein, wenn sie von einer http- oder https-URL stammt, oder höchstens 100 MB als Data URI. Verwenden Sie für eine Data URI den MIME-Typ application/octet-stream.
Für eine Datei über 100 MB gelten zusätzlich folgende Regeln:
- Eine GLB-, glTF-, FBX- oder OBJ-Datei darf höchstens 10.000.000 Flächen haben. Meshy zählt Flächen als Dreiecke, sodass ein Viereck als 2 zählt und ein mehrfach gezeichnetes Netz pro Kopie einmal zählt.
- Eine FBX-Datei muss binäres FBX 7.1 oder neuer sein.
- Eine GLB- oder glTF-Datei darf keine Draco-Komprimierung verwenden.

Name
target_formats
Type
string[]
Erforderlich
Description
Die zu erzeugenden Dateiformate. Geben Sie mindestens eines an. Eine fehlende oder leere Liste führt zu 400.
Verfügbare Werte:
- glb
- fbx
- obj
- usdz
- blend
- stl
- 3mf

Rückgabewerte

Das Feld result der Antwort enthält die ID der neuen Convert-Aufgabe.

Fehlermodi

Name
400 - Bad Request
Description
Die Anfrage kann nicht ausgeführt werden. Die Fehlermeldung gibt an, welches Problem gefunden wurde. Zum Beispiel:
- Fehlender Parameter: Weder model_url noch input_task_id wurde gesendet.
- Fehlendes target_formats: target_formats fehlt oder enthält kein Format.
- Ungültige input-Aufgabe: input_task_id ist keine erfolgreiche Aufgabe.
- Ungültiges Modellformat: Die Datei unter model_url hat eine nicht unterstützte Erweiterung.
- Nicht erreichbare URL: Meshy kann die Datei unter model_url nicht herunterladen.
- Modelldatei zu groß: Die Datei unter model_url ist größer als 400 MB bei einer http- oder https-URL, oder größer als 100 MB als Data URI.
- Zu viele Flächen: Die Datei unter model_url ist größer als 100 MB und hat mehr als 10.000.000 Flächen. Reduzieren Sie die Flächenanzahl und senden Sie die Datei erneut.
- ASCII-FBX über 100 MB: Die Datei unter model_url ist eine ASCII-FBX-Datei über 100 MB. Senden Sie sie als binäres FBX oder als GLB.
- Nicht lesbare Modelldatei: Die Datei unter model_url ist größer als 100 MB, und Meshy kann den Header nicht lesen. Zum Beispiel handelt es sich um eine Draco-komprimierte GLB- oder glTF-Datei oder um ein binäres FBX älter als 7.1.
- Modell-Header zu komplex: Die Datei unter model_url ist größer als 100 MB, und ihr Header enthält zu viele Netze, Knoten oder Einträge zum Prüfen. Reduzieren Sie die Anzahl der Objekte in der Datei und senden Sie sie erneut.
Beheben Sie das Problem in der Anfrage und senden Sie sie erneut. Siehe Errors.
Name
401 - Unauthorized
Description
Der API-Schlüssel fehlt oder ist ungültig. Überprüfen Sie den Authorization-Header.
Name
402 - Payment Required
Description
Zum Beispiel:
- Unzureichende Credits: Das Konto hat nicht genügend Credits für diese Aufgabe, oder das Konto hat ein Credit-Limit erreicht. Überprüfen Sie Ihr Credit-Guthaben und versuchen Sie es erneut.
- Kostenloser Plan: Das Erstellen einer Aufgabe erfordert einen kostenpflichtigen Plan. Upgraden Sie Ihren Plan in Ihren Abonnement-Einstellungen und versuchen Sie es erneut.
Name
403 - Forbidden
Description
input_task_id ist ein Flachrelief-Modell, das dieser Endpunkt nicht konvertieren kann. Die Meldung lautet This model type does not support this operation. Senden Sie ein anderes Modell.
Name
404 - Not Found
Description
input_task_id entspricht keiner Ihrer Aufgaben. Überprüfen Sie die Aufgaben-ID und senden Sie die Anfrage erneut.
Name
429 - Too Many Requests
Description
Sie haben Ihre Ratenbegrenzung überschritten. Warten Sie und versuchen Sie es dann erneut. Siehe Rate limits.

GET/openapi/v1/convert/:id

Convert-Task abrufen

Gibt einen Convert-Task anhand seiner ID zurück.

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
}

Parameter

Name
id
Type
path
Description
Die Task-ID aus der Antwort der Erstellung.

Rückgabe

Das Convert-Task-Objekt.

DELETE/openapi/v1/convert/:id

Eine Convert-Aufgabe löschen

Löscht eine Convert-Aufgabe dauerhaft, einschließlich ihrer Modelle und Daten. Das Löschen kann nicht rückgängig gemacht werden.

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

Pfadparameter

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

Aufgabenstatus

Das Löschen einer Aufgabe mit dem Status PENDING erstattet die Credits zurück, die bei ihrer Erstellung verwendet wurden.

Eine Aufgabe mit dem Status IN_PROGRESS kann nicht gelöscht werden. Die Anfrage gibt 409 Conflict zurück, und die Aufgabe läuft weiter. Meshy erstattet keine Aufgabe, die bereits gestartet wurde, daher würde das Löschen Sie sowohl die Credits als auch das Ergebnis kosten. Warten Sie, bis sie SUCCEEDED, FAILED oder CANCELED erreicht, und löschen Sie sie dann.

Das Löschen einer Aufgabe in einem Endstatus (SUCCEEDED, FAILED oder CANCELED) erstattet ihre Credits nicht zurück.

Rückgabewerte

200 OK, wenn die Aufgabe gelöscht wurde, oder 409 Conflict, wenn die Aufgabe den Status IN_PROGRESS hat.

GET/openapi/v1/convert

Convert-Aufgaben auflisten

Gibt eine Liste Ihrer Convert-Aufgaben 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
  }
]

Parameter

Name
page_num
Type
integer
Standard 1
Description
Die zurückzugebende Seitenzahl.

Name
page_size
Type
integer
Standard 10
Description
Die Anzahl der Aufgaben pro Seite, bis zu 100.

Name
sort_by
Type
string
Description
Die Sortierreihenfolge.
Verfügbare Werte:
- +created_at: älteste zuerst
- -created_at: neueste zuerst

Rückgabewerte

Eine paginierte Liste von Convert-Aufgabenobjekten.

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

Stream a Convert task

Streamt die Aktualisierungen eines Convert-Tasks 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
}

Parameter

Name
id
Type
path
Description
Die Task-ID aus der Erstellungsantwort.

Rückgabewerte

Ein Stream von Convert-Task-Objekten als Server-Sent Events.

Jedes Event enthält das vollständige Task-Objekt, in derselben Form, die der Get-Endpunkt zurückgibt. Solange der Task PENDING oder IN_PROGRESS ist, haben seine Ergebnisfelder noch keine Werte.

Das Convert-Task-Objekt

Ein Convert-Task-Objekt beschreibt eine Formatkonvertierung eines 3D-Modells. Es enthält den Status, den progress und die Modelldateien, wenn der Task erfolgreich war.

Eigenschaften

Name
id
Type
string
Description
Die Task-ID. Behandeln Sie sie als undurchsichtige Zeichenkette und verlassen Sie sich nicht auf ihr Format.
Name
type
Type
string
Description
Der Task-Typ, immer convert.
Name
model_urls
Type
object
Description
Download-URLs für das konvertierte Modell, eine pro Dateiformat. Nur die in target_formats angegebenen Formate besitzen URLs. Ein nicht angefordertes Format hat keinen Schlüssel, statt einer leeren Zeichenkette.
Name
progress
Type
integer
Description
Wie viel des Tasks erledigt ist, als Prozentsatz. Der Wert ist 0, bis der Task beginnt, und 100, wenn er erfolgreich ist.
Name
status
Type
string
Description
Der Task-Status, einer von PENDING, IN_PROGRESS, SUCCEEDED, FAILED oder CANCELED.
Name
preceding_tasks
Type
integer
Description
Die Anzahl der Tasks, die in der Warteschlange vor diesem liegen. Der Wert ist nur aussagekräftig, solange der Task PENDING ist.
Name
created_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task erstellt wurde, in Unix-Millisekunden.
Name
started_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task begonnen hat, in Unix-Millisekunden. Der Wert ist 0, bis der Task beginnt.
Name
finished_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task beendet wurde, in Unix-Millisekunden. Der Wert ist 0, bis der Task beendet ist.
Name
task_error
Type
object
Description
Die Fehlerdetails, wenn der Task fehlschlägt. Siehe Fehler.
Name
consumed_credits
Type
integer
Description
Die Anzahl der vom Task verbrauchten Credits, die bei einem Convert-Task 1 beträgt. Bei einem FAILED-Task ist der Wert 0.