lowpoly wird am 30.10.2026 abgeschaltet. meshy-7 wird als 3D-Generierungsmodell am 31.12.2026 abgeschaltet; als Texturmodell bleibt es verfügbar. Wechseln Sie vor diesen Terminen das Modell, um Fehler bei Anfragen zu vermeiden. Alle Abkündigungen ansehen

Convert API

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


POST/openapi/v1/convert

Convert-Task erstellen

Erstellt einen Convert-Task. Der Task läuft im Hintergrund. Wie lange ein Task normalerweise dauert, erfahren Sie unter Verarbeitungszeiten.

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, 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 Status SUCCEEDED haben.

  • 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 Meshy input_task_id.

    Das Modell muss eine GLB-, glTF-, OBJ-, FBX- oder STL-Datei von höchstens 400 MB über eine http- oder https-URL sein, oder 100 MB als Data URI. Verwenden Sie für eine Data URI den MIME-Typ application/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:

    • glb
    • fbx
    • obj
    • usdz
    • blend
    • stl
    • 3mf

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_url noch input_task_id wurde gesendet.
    • Fehlendes target_formats: target_formats fehlt oder enthält kein Format.
    • Ungültiger Input-Task: input_task_id ist kein erfolgreicher API-Task mit einer Modelldatei.
    • Ungültiges Modellformat: Die Datei unter model_url hat eine nicht unterstützte Dateiendung.
    • Nicht erreichbare URL: Meshy kann die Datei unter model_url nicht herunterladen.
    • Modelldatei zu groß: Die Datei unter model_url ist über 400 MB groß bei einer http- oder https-URL, oder über 100 MB als Data URI.
    • Zu viele Flächen: Die Datei unter model_url ist ü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_url ist ein ASCII-FBX über 100 MB. Senden Sie sie als binäres FBX oder GLB.
    • Nicht lesbare Modelldatei: Die Datei unter model_url ist ü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_url ist ü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.

  • 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_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 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.


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-Tasks auflisten

Gibt eine Liste Ihrer Convert-Tasks 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, bis zu 255. Ein größerer Wert führt zu 400.

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


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 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_formats haben 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, 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 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ßerdem metallic-, roughness-, normal-, emission- und metallic_roughness-URLs haben. Der Wert ist null, 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 1 für einen Convert-Task ist. Der Wert ist 0 für einen FAILED-Task.