Convert API
Konvertieren Sie ein 3D-Modell in andere Dateiformate, aus einer Meshy-Aufgabe oder aus einer Modelldatei.
Convert-Task erstellen
Erstellt einen Convert-Task. Der Task läuft im Hintergrund. Wie lange ein Task normalerweise dauert, erfahren Sie unter Verarbeitungszeiten.
Request
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, außer Sie senden
model_url. Die ID eines Tasks, der ein 3D-Modell erzeugt hat, zum Beispiel ein Text-zu-3D-, Bild-zu-3D-, Neuvernetzungs-, Größe-ändern- oder Neutexturierungs-Task. Der Task muss von der API stammen und den StatusSUCCEEDEDhaben.
- Name
- model_url
- Type
- string
- Erforderlich
- Description
Erforderlich, außer Sie senden
input_task_id. Das zu konvertierende Modell, als öffentliche URL oder als Data URI. Wenn Sie beides senden, verwendet Meshyinput_task_id.Das Modell muss eine GLB-, glTF-, OBJ-, FBX- oder STL-Datei von höchstens 400 MB über eine
http- oderhttps-URL sein, oder 100 MB als Data URI. Verwenden Sie für eine Data URI den MIME-Typapplication/octet-stream.Eine Datei über 100 MB muss zusätzlich diese Regeln erfüllen:
- Eine GLB-, glTF-, FBX- oder OBJ-Datei darf höchstens 10.000.000 Flächen haben. Meshy zählt Flächen als Dreiecke, ein Viereck zählt also als 2, und ein mehrfach gezeichnetes Netz zählt einmal pro Kopie.
- Eine FBX-Datei muss binäres FBX 7.1 oder neuer sein.
- Eine GLB- oder glTF-Datei darf keine Draco-Kompression verwenden.
- Name
- target_formats
- Type
- string[]
- Erforderlich
- Description
Die zu generierenden Dateiformate. Geben Sie mindestens eines an. Eine fehlende oder leere Liste liefert
400.Verfügbare Werte:
glbfbxobjusdzblendstl3mf
Rückgabewerte
Das Feld result der Antwort enthält die ID des neuen Convert-Tasks.
Fehlermodi
- Name
400 - Bad Request- Description
Die Anfrage kann nicht ausgeführt werden. Die Fehlermeldung nennt das gefundene Problem. Zum Beispiel:
- Fehlender Parameter: Weder
model_urlnochinput_task_idwurde gesendet. - Fehlendes
target_formats:target_formatsfehlt oder enthält kein Format. - Ungültiger Input-Task:
input_task_idist kein erfolgreicher API-Task mit einer Modelldatei. - Ungültiges Modellformat: Die Datei unter
model_urlhat eine nicht unterstützte Dateiendung. - Nicht erreichbare URL: Meshy kann die Datei unter
model_urlnicht herunterladen. - Modelldatei zu groß: Die Datei unter
model_urlist über 400 MB groß bei einerhttp- oderhttps-URL, oder über 100 MB als Data URI. - Zu viele Flächen: Die Datei unter
model_urlist über 100 MB groß 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_urlist ein ASCII-FBX über 100 MB. Senden Sie sie als binäres FBX oder GLB. - Nicht lesbare Modelldatei: Die Datei unter
model_urlist über 100 MB groß, und Meshy kann den Header nicht lesen. Zum Beispiel ist es ein Draco-komprimiertes GLB oder glTF, oder ein binäres FBX älter als 7.1. - Modell-Header zu komplex: Die Datei unter
model_urlist über 100 MB groß, 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.
Korrigieren Sie die Anfrage und senden Sie sie erneut. Siehe Fehler.
- Fehlender Parameter: Weder
- 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 diesen Task, oder das Konto hat ein Credit-Limit erreicht. Prüfen Sie Ihr Credit-Guthaben und versuchen Sie es erneut.
- Kostenloser Plan: Das Erstellen eines Tasks erfordert einen kostenpflichtigen Plan. Aktualisieren Sie Ihren Plan in den Abonnement-Einstellungen und versuchen Sie es erneut.
- Name
403 - Forbidden- Description
input_task_idist ein Flachrelief-Modell, das dieser Endpunkt nicht konvertieren kann. Die Meldung lautetThis model type does not support this operation. Senden Sie ein anderes Modell.
- Name
404 - Not Found- Description
input_task_identspricht keinem Ihrer Tasks. Überprüfen Sie die Task-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 Ratenbegrenzungen.
Convert-Task abrufen
Gibt einen Convert-Task anhand seiner ID zurück.
Request
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.
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
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.
Convert-Tasks auflisten
Gibt eine Liste Ihrer Convert-Tasks zurück.
Request
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, bis zu
255. Ein größerer Wert führt zu400.
- Name
- page_size
- Type
- integer
- Standard 10
- Description
Die Anzahl der Tasks 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-Task-Objekten.
Stream a Convert task
Streamt die Aktualisierungen eines Convert-Tasks als Server-Sent Events (SSE).
Request
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 ist.
Eigenschaften
- Name
- id
- Type
- string
- Description
Die Task-ID. Behandeln Sie sie als undurchsichtige Zeichenfolge 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 Formate in
target_formatshaben URLs. Ein Format, das Sie nicht angefordert haben, hat keinen Schlüssel, statt einer leeren Zeichenfolge.
- Name
- progress
- Type
- integer
- Description
Wie viel von der Aufgabe erledigt ist, in Prozent. Der Wert ist
0, bis der Task beginnt, und100, wenn er erfolgreich ist.
- Name
- status
- Type
- string
- Description
Der Task-Status, einer von
PENDING,IN_PROGRESS,SUCCEEDED,FAILEDoderCANCELED.
- 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
PENDINGist.
- 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 gestartet wurde, in Unix-Millisekunden. Der Wert ist
0, bis der Task startet.
- Name
- finished_at
- Type
- timestamp
- Description
Zeitpunkt, zu dem der Task abgeschlossen wurde, in Unix-Millisekunden. Der Wert ist
0, bis der Task abgeschlossen ist.
- Name
- expires_at
- Type
- timestamp
- Description
Zeitpunkt, zu dem die Download-URLs des Tasks ablaufen, in Unix-Millisekunden. Der Wert ist
0, bis der Task abgeschlossen ist.
- Name
- texture_urls
- Type
- array
- Description
Download-URLs für die Texturkarten des Modells, wenn der Task erfolgreich ist: ein Array von Objekten, eines pro Textur-Set. Jedes Objekt hat eine
base_color-URL und kann außerdemmetallic-,roughness-,normal-,emission- undmetallic_roughness-URLs haben. Der Wert istnull, bis der Task erfolgreich ist, und ein leeres Array, wenn das Modell keine Texturkarten hat.
- Name
- task_error
- Type
- object
- Description
Die Fehlerdetails, wenn der Task fehlschlägt. Siehe Fehler.
- Name
- consumed_credits
- Type
- integer
- Description
Die Anzahl der Credits, die der Task verbraucht hat, was
1für einen Convert-Task ist. Der Wert ist0für einenFAILED-Task.