Resize API

Die Resize API ermöglicht es Ihnen, bestehende 3D-Modelle auf reale Abmessungen zu skalieren. Sie können eine exakte Höhe, eine Beschränkung der längsten Seite angeben oder die KI die passende Größe automatisch schätzen lassen.

POST/openapi/v1/resize

Erstellen einer Resize-Aufgabe

Dieser Endpunkt erstellt eine neue Resize-Aufgabe.

Parameter

Nur eines von input_task_id oder model_url ist erforderlich. Wenn beide angegeben werden, hat input_task_id Priorität.

Name
input_task_id
Type
string
Erforderlich
Description
Die ID einer abgeschlossenen Meshy-Aufgabe, deren Modell Sie in der Größe ändern möchten. Die Aufgabe muss den Status SUCCEEDED haben. Das Ausgabeformat ist GLB.

Name
model_url
Type
string
Erforderlich
Description
Eine öffentlich zugängliche URL oder Data URI, die auf eine 3D-Modelldatei verweist. Unterstützte Formate: .glb, .gltf, .obj, .fbx, .stl. Verwenden Sie für Data URIs den MIME-Typ: application/octet-stream. Das Ausgabeformat entspricht dem ursprünglichen Format des Eingabemodells.

Genau ein Resize-mode ist erforderlich: resize_height, resize_longest_side oder auto_size. Diese drei Parameter schließen sich gegenseitig aus.

Name
resize_height
Type
number
Description
Ändert die Größe des Modells auf eine bestimmte Höhe in Metern.

Name
resize_longest_side
Type
number
Description
Ändert die Größe des Modells so, dass seine längste Seite diesem Wert entspricht, gemessen in Metern. Das Seitenverhältnis bleibt erhalten.

Name
auto_size
Type
boolean
Description
Wenn dieser Wert auf true gesetzt ist, verwendet der Dienst KI-basierte Bilderkennung, um die reale Höhe des Objekts automatisch zu schätzen und die Größe des Modells entsprechend anzupassen. Der Ursprung wird standardmäßig auf bottom gesetzt, sofern origin_at nicht ausdrücklich festgelegt wird.

Name
origin_at
Type
string
Standard bottom
Description
Position des Ursprungs nach der Größenänderung.
Verfügbare Werte: bottom, center.

Rückgabewerte

Die Eigenschaft result der Antwort enthält die id der neu erstellten Resize-Aufgabe.

Fehlerarten

400 - Bad Request

Die Anfrage war ungültig. Häufige Ursachen:

Fehlender Parameter: Entweder model_url oder input_task_id muss angegeben werden.
Fehlender Resize-mode: Mindestens einer von resize_height, resize_longest_side oder auto_size muss angegeben werden.
Sich gegenseitig ausschließende Parameter: resize_height, resize_longest_side und auto_size können nicht kombiniert werden.
Ungültige Eingabeaufgabe: input_task_id muss sich auf eine erfolgreiche Aufgabe beziehen.
Ungültiges Modellformat: model_url verweist auf eine Datei mit einer nicht unterstützten Dateiendung.
Nicht erreichbare URL: model_url konnte nicht heruntergeladen werden.

401 - Unauthorized

Die Authentifizierung ist fehlgeschlagen. Bitte überprüfen Sie Ihren API-Schlüssel.

402 - Payment Required

Nicht genügend Credits, um diese Aufgabe auszuführen.

429 - Too Many Requests

Sie haben Ihre Ratenbegrenzung überschritten.

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

GET/openapi/v1/resize/:id

Eine Resize-Aufgabe abrufen

Dieser Endpunkt ruft eine Resize-Aufgabe anhand ihrer ID ab.

Parameter

Name
id
Type
path
Description
Die ID der abzurufenden Resize-Aufgabe.

Rückgabe

Das Resize-Task-Objekt.

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
}

DELETE/openapi/v1/resize/:id

Eine Größe-ändern-Aufgabe löschen

Dieser Endpunkt löscht eine Größe-ändern-Aufgabe endgültig, einschließlich aller zugehörigen Modelle und Daten. Diese Aktion ist unwiderruflich.

Pfadparameter

Name
id
Type
path
Description
Die ID der zu löschenden Größe-ändern-Aufgabe.

Aufgabenstatus

Eine Aufgabe, die sich noch im Status PENDING befindet, wird gelöscht, und die bei der Erstellung verbrauchten Credits werden zurückerstattet.

Eine Aufgabe, die sich bereits IN_PROGRESS befindet, kann nicht gelöscht werden: Die Anfrage wird mit 409 Conflict abgelehnt, und die Aufgabe läuft weiter. Credits für eine Aufgabe, die der Worker bereits gestartet hat, sind nicht erstattungsfähig. Ein Löschen während der Ausführung würde Sie also sowohl die Credits als auch das Ergebnis kosten. Warten Sie, bis sie den Status SUCCEEDED, FAILED oder CANCELED erreicht, und löschen Sie sie dann.

Eine Aufgabe in einem Endzustand (SUCCEEDED, FAILED oder CANCELED) wird ohne Rückerstattung gelöscht.

Rückgabewerte

Gibt bei Erfolg 200 OK zurück, oder 409 Conflict, wenn sich die Aufgabe im Status IN_PROGRESS befindet.

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

GET/openapi/v1/resize

Liste der Resize-Aufgaben abrufen

Dieser Endpunkt ermöglicht es Ihnen, eine Liste von Resize-Aufgaben abzurufen.

Parameter

Name
page_num
Type
integer
Standard 1
Description
Seitennummer für die Paginierung.

Name
page_size
Type
integer
Standard 10
Description
Begrenzung der Seitengröße. Maximal erlaubt sind 100 Elemente.

Name
sort_by
Type
string
Description
Feld, nach dem sortiert werden soll. Verfügbare Werte:
- +created_at: Sortierung nach Erstellungszeit in aufsteigender Reihenfolge.
- -created_at: Sortierung nach Erstellungszeit in absteigender Reihenfolge.

Rückgabewerte

Gibt eine paginierte Liste von The Resize Task Objects 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
  }
]

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

Streamen einer Größenänderungs-Aufgabe

Dieser Endpunkt streamt Echtzeit-Updates für eine Größenänderungs-Aufgabe mittels Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Eindeutige Kennung der zu streamenden Größenänderungs-Aufgabe.

Rückgabewerte

Gibt einen Stream von The Resize Task Objects als Server-Sent Events zurück.

Bei Aufgaben mit dem Status PENDING oder IN_PROGRESS enthält der Antwort-Stream nur die notwendigen Felder progress und status.

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
}

Das Resize-Task-Objekt

Das Resize-Task-Objekt repräsentiert einen Größenänderungs-Job.

Eigenschaften

id · string

Eindeutige Kennung für die Aufgabe.

type · string

Typ der Aufgabe. Der Wert ist resize.

model_urls · object

Herunterladbare URL für die Datei des in der Größe geänderten Modells. Bei Verwendung von input_task_id ist die Ausgabe immer GLB. Bei Verwendung von model_url bleibt das ursprüngliche Format erhalten.

progress · integer

progress der Aufgabe (0-100).

status · string

Status der Aufgabe. Mögliche Werte: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

preceding_tasks · integer

Die Anzahl der vorausgehenden Aufgaben. Nur relevant, wenn der Status PENDING ist.

created_at · timestamp

Zeitstempel, wann die Aufgabe erstellt wurde, in Millisekunden.

started_at · timestamp

Zeitstempel, wann die Aufgabe gestartet wurde, in Millisekunden. 0, wenn sie nicht gestartet wurde.

finished_at · timestamp

Zeitstempel, wann die Aufgabe abgeschlossen wurde, in Millisekunden. 0, wenn sie nicht abgeschlossen wurde.

task_error · object

Fehlerobjekt, falls die Aufgabe fehlgeschlagen ist. Weitere Details finden Sie unter Fehler.

consumed_credits · integer

Die Anzahl der von dieser Aufgabe verbrauchten Credits (1 Credit pro Resize-Aufgabe). Gibt 0 für FAILED-Aufgaben zurück.