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

Resize-Task erstellen

Erstellt einen Resize-Task. Der Task läuft im Hintergrund. Wie lange ein Task normalerweise dauert, erfahren 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, außer Sie senden model_url. Die ID des Meshy-Tasks, dessen Modell Sie in der Größe ändern möchten. Der Task muss den Status SUCCEEDED haben. Meshy gibt das größenveränderte Modell als GLB-Datei zurück.

Name
model_url
Type
string
Erforderlich
Description
Erforderlich, außer Sie senden input_task_id. 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-Kompression verwenden.
Eine GLB-, OBJ-, FBX- oder STL-Datei behält ihr Format im Ergebnis bei. Eine .gltf-Datei oder eine Data URI wird als GLB zurückgegeben.

Senden Sie genau einen der Parameter resize_height, resize_longest_side oder auto_size. Wenn Sie keinen oder mehr als einen senden, wird 400 zurückgegeben.

Name
resize_height
Type
number
Description
Die neue Höhe des Modells in Metern, größer als 0. Ein negativer Wert gibt 400 zurück.

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 gibt 400 zurück. Meshy behält das Seitenverhältnis des Modells bei.

Name
auto_size
Type
boolean
Description
Ob die reale Höhe des Objekts mit KI-Bildverarbeitung geschätzt und das Modell entsprechend in der Größe angepasst 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 des neuen Resize-Tasks.

Fehlerfälle

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-Modus: Keiner der Parameter resize_height, resize_longest_side und auto_size wurde gesendet.
- Sich gegenseitig ausschließende Parameter: Die Anfrage enthält mehr als einen der Parameter resize_height, resize_longest_side und auto_size. Senden Sie nur einen.
- Negative Größe: resize_height oder resize_longest_side ist negativ.
- Ungültiger Input-Task: input_task_id ist kein erfolgreicher Task.
- Ungültiges Modellformat: Die Datei unter model_url hat eine nicht unterstützte Dateiendung.
- URL nicht erreichbar: 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 Anzahl der Flächen 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äre FBX- oder GLB-Datei.
- Modelldatei nicht lesbar: 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 eine binäre FBX-Datei ä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 Überprü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. Überprü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 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 keinem Ihrer Tasks überein. Ü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 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 Größenänderungs-Tasks

Gibt eine Liste deiner Größenänderungs-Tasks 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 Seitenzahl.

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 Resize-Task-Objekten.

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.

Das Resize-Task-Objekt

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

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 resize.
Name
model_urls
Type
object
Description
Download-URL für die in der Größe geänderte Modelldatei. Bei input_task_id ist die Datei immer GLB. Bei model_url behalten GLB-, OBJ-, FBX- oder STL-Dateien ihr Format, während eine .gltf-Datei oder eine Data URI als GLB zurückgegeben wird.
Name
progress
Type
integer
Description
Wie viel von dem Task erledigt ist, in Prozent. Der Wert ist 0, bis der Task startet, 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 vor diesem in der Warteschlange stehen. Der Wert ist nur relevant, solange der Task PENDING ist.
Name
created_at
Type
timestamp
Description
Zeitpunkt der Erstellung des Tasks, 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 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, was bei einem Resize-Task 1 ist. Bei einem FAILED-Task ist der Wert 0.