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

Größe-ändern-API

Ändern Sie die Größe eines 3D-Modells auf eine reale Größe, in Metern. Legen Sie die Höhe oder die Länge der längsten Seite fest, oder lassen Sie Meshy die reale Höhe des Objekts schätzen.


POST/openapi/v1/resize

Erstellen einer Resize-Aufgabe

Erstellt eine Resize-Aufgabe. Die Aufgabe läuft im Hintergrund. Informationen dazu, wie lange eine Aufgabe in der Regel dauert, finden Sie unter Verarbeitungszeiten.

Request

POST
/openapi/v1/resize
# Simple: resize to a specific height
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "resize_height": 1.8
  }'

# Advanced: resize longest side with custom origin
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.glb",
    "resize_longest_side": 2.0,
    "origin_at": "center"
  }'

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 einer Aufgabe, die ein 3D-Modell erzeugt hat, zum Beispiel eine Text-zu-3D-, Bild-zu-3D-, Neuvernetzungs- oder Neutexturierungs-Aufgabe. Die Aufgabe muss von der API stammen und den Status SUCCEEDED haben. Meshy gibt das in der Größe geänderte Modell als GLB-Datei zurück.

  • Name
    model_url
    Type
    string
    Erforderlich
    Description

    Erforderlich, sofern Sie nicht input_task_id senden. Das Modell, dessen Größe geändert werden soll, als öffentliche URL oder als Data URI. Wenn Sie beide senden, verwendet Meshy input_task_id.

    Das Modell muss eine GLB-, glTF-, OBJ-, FBX- oder STL-Datei mit höchstens 400 MB von einer 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, 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.

    Eine GLB-, OBJ-, FBX- oder STL-Datei behält ihr Format im Ergebnis bei. Eine .gltf-Datei oder eine Data URI kommt als GLB zurück.

Senden Sie genau eines von resize_height, resize_longest_side oder auto_size. Wenn Sie keines oder mehr als eines senden, erhalten Sie 400.

  • Name
    resize_height
    Type
    number
    Description

    Die neue Höhe des Modells in Metern, größer als 0. Ein negativer Wert führt zu 400.

  • Name
    resize_longest_side
    Type
    number
    Description

    Die neue Länge der längsten Seite des Modells in Metern, größer als 0. Ein negativer Wert führt zu 400. Meshy behält das Seitenverhältnis des Modells bei.

  • Name
    auto_size
    Type
    boolean
    Description

    Ob die reale Höhe des Objekts mit KI-Bildanalyse geschätzt und das Modell darauf skaliert werden soll. Sofern Sie origin_at nicht setzen, platziert Meshy den Ursprung unten.

  • Name
    origin_at
    Type
    string
    Standard bottom
    Description

    Wo der Ursprung des Modells nach der Größenänderung platziert werden soll, bottom oder center.

Rückgabewerte

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

Fehlerarten

  • 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.
    • Fehlender Resize-mode: Keines von resize_height, resize_longest_side und auto_size wurde gesendet.
    • Sich gegenseitig ausschließende Parameter: Die Anfrage enthält mehr als eines von resize_height, resize_longest_side und auto_size. Senden Sie nur eines davon.
    • Negative Größe: resize_height oder resize_longest_side ist negativ.
    • Ungültige Eingabeaufgabe: input_task_id ist keine erfolgreiche API-Aufgabe mit einer Modelldatei.
    • Ungültiges Modellformat: Die Datei model_url hat eine nicht unterstützte Dateierweiterung.
    • Unerreichbare URL: Meshy kann die Datei model_url nicht herunterladen.
    • Modelldatei zu groß: Die Datei model_url ist größer als 400 MB von einer http- oder https-URL, oder größer als 100 MB als Data URI.
    • Zu viele Flächen: Die Datei 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 model_url ist eine ASCII-FBX-Datei über 100 MB. Senden Sie sie als binäre FBX- oder GLB-Datei.
    • Nicht lesbare Modelldatei: Die Datei model_url ist größer als 100 MB, und Meshy kann ihren Header nicht lesen. Zum Beispiel handelt es sich um eine Draco-komprimierte GLB- oder glTF-Datei, oder um eine binäre FBX-Datei älter als 7.1.
    • Modell-Header zu komplex: Die Datei model_url ist größer als 100 MB, und ihr Header hat zu viele Netze, Knoten oder Datensätze zum Überprüfen. Reduzieren Sie die Anzahl der Objekte in der Datei und senden Sie sie erneut.

    Beheben Sie die Anfrage und senden Sie sie dann 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 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. Aktualisieren Sie Ihren Plan in Ihren Abonnement-Einstellungen und versuchen Sie es erneut.
  • Name
    403 - Forbidden
    Description

    input_task_id ist ein Flachrelief-Modell, dessen Größe dieser Endpunkt nicht ändern 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 stimmt mit keiner Ihrer Aufgaben überein. Ü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 erneut. Siehe Ratenbegrenzungen.


GET/openapi/v1/resize/:id

Resize-Task abrufen

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

Request

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "resize",
  "model_urls": {
      "glb": "https://assets.meshy.ai/.../model.glb?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 Resize-Task-Objekt.


DELETE/openapi/v1/resize/:id

Einen Resize-Task löschen

Löscht einen Resize-Task endgültig, einschließlich seiner Modelle und Daten. Ein Löschvorgang kann nicht rückgängig gemacht werden.

Request

DELETE
/openapi/v1/resize/:id
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/resize/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 des zu löschenden Tasks.

Task-Status

Das Löschen eines Tasks mit Status PENDING erstattet die Credits, die bei seiner Erstellung verwendet wurden.

Ein Task mit Status IN_PROGRESS kann nicht gelöscht werden. Die Anfrage liefert 409 Conflict, und der Task läuft weiter. Meshy erstattet keine Credits für einen bereits gestarteten Task, daher würde das Löschen Sie sowohl die Credits als auch das Ergebnis kosten. Warten Sie, bis er SUCCEEDED, FAILED oder CANCELED erreicht, und löschen Sie ihn dann.

Das Löschen eines Tasks mit einem finalen Status (SUCCEEDED, FAILED oder CANCELED) erstattet dessen Credits nicht.

Rückgabewerte

200 OK, wenn der Task gelöscht wurde, oder 409 Conflict, wenn der Task IN_PROGRESS ist.


GET/openapi/v1/resize

Liste der Resize-Aufgaben abrufen

Gibt eine Liste deiner Resize-Aufgaben zurück.

Request

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "resize",
    "model_urls": {
      "glb": "https://assets.meshy.ai/.../model.glb?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 Seitennummer, bis zu 255. Ein größerer Wert gibt 400 zurück.

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


GET/openapi/v1/resize/:id/stream

Eine Resize-Aufgabe streamen

Streamt die Updates einer Resize-Aufgabe als Server-Sent Events (SSE).

Request

GET
/openapi/v1/resize/:id/stream
curl -N https://api.meshy.ai/openapi/v1/resize/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": "resize",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb?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

Ein Stream von Resize-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 die Aufgabe PENDING oder IN_PROGRESS ist, haben ihre Ergebnisfelder noch keine Werte.


The Resize task object

Ein Resize-Task-Objekt beschreibt eine Größenänderung eines 3D-Modells. Es enthält den Status, den Fortschritt und die Modelldatei, wenn der Task erfolgreich abgeschlossen wird.

Properties

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

  • Name
    model_urls
    Type
    object
    Description

    Download-URL für die Datei des in der Größe geänderten Modells. Bei input_task_id ist die Datei immer GLB. Bei model_url behält eine GLB-, OBJ-, FBX- oder STL-Datei ihr Format bei, während eine .gltf-Datei oder eine Data URI als GLB zurückgegeben wird.

  • Name
    progress
    Type
    integer
    Description

    Wie viel des Tasks erledigt ist, als Prozentsatz. Der Wert ist 0, bis der Task startet, und 100, wenn er erfolgreich abgeschlossen wird.

  • 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 den Status PENDING hat.

  • 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 abgeschlossen wird: 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 abgeschlossen wird, 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 für einen Resize-Task 1 beträgt. Bei einem Task mit Status FAILED ist der Wert 0.