Bild zu 3D API

Verwandle ein Bild in ein 3D-Modell, texturiert oder untexturiert, in den Formaten deiner Wahl. Sende das Bild oder verwende die Ausgabe eines Text zu Bild- oder Bild zu Bild-Tasks.

POST/openapi/v1/image-to-3d

Eine Bild-zu-3D-Aufgabe erstellen

Erstellt eine Bild-zu-3D-Aufgabe. Die Aufgabe läuft im Hintergrund. Wie lange eine Aufgabe üblicherweise dauert, erfahren Sie unter Verarbeitungszeiten.

Request

POST

/openapi/v1/image-to-3d

# Simple request with required params
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

# With Ultra 4K geometry, remesh, PBR, and A-pose
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "ai_model": "meshy-7.1",
    "geometry_resolution": "4k",
    "enable_pbr": true,
    "should_remesh": true,
    "target_polycount": 100000,
    "should_texture": true,
    "pose_mode": "a-pose",
    "target_formats": ["glb"]
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Parameter

Name
input_task_id
Type
string
Erforderlich
Description
Erforderlich, sofern Sie nicht image_url senden. Die ID einer Text-zu-Bild- oder Bild-zu-Bild-Aufgabe, deren Bild Sie als Eingabe verwenden möchten. Die Aufgabe muss eine sein, die Sie über die API erstellt haben, den Status SUCCEEDED haben und genau ein Bild erzeugt haben.

Name
image_url
Type
string
Erforderlich
Description
Erforderlich, sofern Sie nicht input_task_id senden. Das Bild, das in ein 3D-Modell umgewandelt werden soll, als öffentliche URL oder base64-codierte Data URI, z. B. data:image/jpeg;base64,<your base64-encoded image data>. Wenn Sie beides senden, verwendet Meshy input_task_id.
Das Bild muss eine JPG-, JPEG-, PNG- oder WebP-Datei von höchstens 20 MB sein.

Name
model_type
Type
string
Standard standard
Description
Die Art des zu erzeugenden 3D-Netzes.
Verfügbare Werte:
- standard: ein Netz mit hoher Detailtiefe
- smart-topology: ein Netz aus einem Smart-Topology-Modell, das Sie mit ai_model auswählen (meshy-t2 oder meshy-t2.5)
Bei smart-topology ignoriert Meshy should_remesh, save_pre_remeshed_model und decimation_mode und akzeptiert nur topology: triangle.
Name
ai_model
Type
string
Standard latest
Description
Das KI-Modell, das das 3D-Modell erzeugt. Die verfügbaren Werte hängen von model_type ab.
Standardmodelle (model_type: standard):
- latest: Meshy 7.1
- meshy-7.1
- meshy-6
- meshy-6-lite
- meshy-7 (veraltet): verwenden Sie stattdessen meshy-7.1
Smart-Topology-Modelle (model_type: smart-topology) erzeugen Dreiecke, mit einer Flächenanzahl, die Sie über target_polycount festlegen können:
- meshy-t2: sauberere topology und von Natur aus getrennte Teile
- meshy-t2.5 (Standard): schärfere Details für Game-Assets
Name
geometry_resolution
Type
string
Standard standard
Description
Der Geometrie-Generierungsdurchlauf.
Verfügbare Werte:
- standard
- 2k: führt den Ultra-Durchlauf mit 2048³ aus
- 4k: führt den Ultra-Durchlauf mit 4096³ aus, für die meisten Oberflächendetails
2k erfordert meshy-7.1, latest oder das veraltete meshy-7. 4k erfordert meshy-7.1 oder latest.
Name
ultra_mode
Type
boolean
⚠ veraltet
Standard false
Description
Verwenden Sie stattdessen geometry_resolution. ultra_mode: true entspricht geometry_resolution: "2k".
Name
should_texture
Type
boolean
Standard true
Description
Ob Texturen generiert werden sollen. true liefert ein texturiertes Modell, und false überspringt die Texturierung und liefert ein untexturiertes Netz.

Gilt nur wenn should_texture = true

Name
enable_pbr
Type
boolean
Standard false
Description
Ob zusätzlich zur Grundfarbe auch PBR-Texturen (Metallic, Roughness und Normal) erzeugt werden sollen. true erfordert should_texture: true und liefert bei should_texture: false einen 400-Fehler.
Bei meshy-6 erzeugt Meshy außerdem eine Emission Map, außer bei texture_resolution: 8k. Diese Modelle erzeugen keine Emission Map:
- meshy-6-lite
- meshy-7
- meshy-7.1
- meshy-t2
- meshy-t2.5
- latest
Name
texture_resolution
Type
string
Standard 2k
Description
Die Größe der Grundfarbtextur. Eine größere Textur erfasst mehr Oberflächendetails.
Verfügbare Werte:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
4k und 8k sind bei meshy-6-lite nicht verfügbar und liefern damit 400. Bei 8k erzeugt Meshy keine Emission Map.
Name
hd_texture
Type
boolean
⚠ veraltet
Standard false
Description
Verwenden Sie stattdessen texture_resolution. hd_texture: true entspricht texture_resolution: "4k". Wenn Sie beides senden, verwendet Meshy texture_resolution.
Name
texture_prompt
Type
string
Description
Text, der die Textur steuert, bis zu 800 Zeichen. Längerer Text liefert 400.
Name
texture_image_url
Type
string
Description
Ein Bild, das die Textur steuert, als öffentliche URL oder base64-codierte Data URI, z. B. data:image/jpeg;base64,<your base64-encoded image data>. Das Bild muss eine JPG-, JPEG-, PNG- oder WebP-Datei von höchstens 20 MB sein.
Meshy steuert die Textur nur mit einem von texture_prompt und texture_image_url. Wenn Sie beides senden, verwendet Meshy texture_prompt. Die Credit-Kosten der Texturierung finden Sie unter Preise.
Das Texturieren anhand eines Bildes funktioniert möglicherweise nicht gut, wenn die Form des Bildes stark von der Geometrie des 3D-Modells abweicht.

Name
should_remesh
Type
boolean
Standard true (meshy-6-lite), false (other models)
Description
Ob die Neuvernetzungsphase ausgeführt werden soll. Für das qualitativ hochwertigste 3D-Modell setzen Sie diesen Wert auf false.

Gilt nur wenn should_remesh = true

Name
topology
Type
string
Standard triangle
Description
Der Flächentyp des neu vernetzten Modells.
Verfügbare Werte:
- quad: ein überwiegend aus Vierecken bestehendes Netz
- triangle: ein reduziertes Dreiecksnetz
Die Ausgabe von Smart Topology besteht nur aus Dreiecken, daher liefert quad mit meshy-t2 oder meshy-t2.5 400.
Name
decimation_mode
Type
integer
Description
Adaptive Flächenanzahl, nach Stufe. Wenn Sie diesen Wert setzen, ignoriert Meshy target_polycount.
Verfügbare Werte:
- 1: ultra
- 2: hoch
- 3: mittel
- 4: niedrig
Name
save_pre_remeshed_model
Type
boolean
Standard false
Description
Ob zusätzlich eine GLB-Datei des Modells vor der Neuvernetzungsphase gespeichert werden soll. Meshy liefert sie in model_urls.pre_remeshed_glb zurück.

Name
target_polycount
Type
integer
Description
Die angestrebte Anzahl an Flächen. Das Ergebnis kann je nach Geometrie des Modells vom Zielwert abweichen.
Es gilt in zwei unterschiedlichen Fällen:
- Neuvernetzung: Wenn should_remesh bei einem standard-Modell auf true gesetzt ist, reduziert Meshy das Netz auf etwa diese Anzahl. Wenn Sie decimation_mode setzen, verwendet Meshy diesen Wert und ignoriert target_polycount.
- Smart Topology: Wenn model_type auf smart-topology gesetzt ist und ai_model meshy-t2 oder meshy-t2.5 ist, erzeugt Meshy das Modell mit dieser Flächenanzahl. Es läuft keine Neuvernetzung, und Sie benötigen should_remesh nicht.
Der Bereich und der Standardwert hängen vom Fall ab:
Fall Bereich Standard
Neuvernetzung 100 bis 300000 30000
meshy-t2 100 bis 15000 4000
meshy-t2.5 100 bis 30000 15000
Ein Wert außerhalb dieses Bereichs liefert 400.

Fall	Bereich	Standard
Neuvernetzung	`100` bis `300000`	`30000`
`meshy-t2`	`100` bis `15000`	`4000`
`meshy-t2.5`	`100` bis `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ veraltet
Standard auto
Description
Lassen Sie diesen Parameter weg, da er die Ausgabe nicht beeinflusst. Seine Werte steuerten die Symmetrie während der Generierung:
- off: keine Symmetrie
- auto: aus der Eingabegeometrie gewählte Symmetrie
- on: erzwungene Symmetrie
Name
pose_mode
Type
string
Standard ""
Description
Die Pose für das generierte Modell.
Verfügbare Werte:
- a-pose: eine A-Pose
- t-pose: eine T-Pose
- "" (leere Zeichenfolge): keine bestimmte Pose
Name
is_a_t_pose
Type
boolean
⚠ veraltet
Standard false
Description
Verwenden Sie stattdessen pose_mode. Ob das Modell in einer A- oder T-Pose erzeugt werden soll.
Name
surface_mode
Type
string
⚠ veraltet
Description
Verwenden Sie stattdessen ai_model. Dieser Parameter beeinflusst die Ausgabe nicht, da die von ihm ausgewählte Modellgenerierung eingestellt wurde.
Akzeptierte Werte sind organic und hard. Jeder andere Wert liefert 400.
Name
image_enhancement
Type
boolean
Standard true
Description
Ob das Eingabebild vor der Generierung optimiert werden soll. false behält das exakte Aussehen des Eingabebilds bei, ohne Stilverarbeitung.
Dies funktioniert nur mit meshy-6, meshy-7.1 oder latest. Mit meshy-6-lite oder model_type: smart-topology liefert es 400.
Name
remove_lighting
Type
boolean
Standard true
Description
Ob Glanzlichter und Schatten aus der Grundfarbtextur entfernt werden sollen. Das Ergebnis ist sauberer und funktioniert besser unter eigener Beleuchtung.
Dies wirkt sich nur bei meshy-6 aus. meshy-7.1 und latest akzeptieren den Parameter, ignorieren ihn jedoch. Mit meshy-6-lite oder model_type: smart-topology liefert er 400.
Name
moderation
Type
boolean
Standard false
Description
Ob diese Eingaben vor der Generierung auf schädliche Inhalte geprüft werden sollen:
- image_url
- texture_image_url
- texture_prompt
Erkennt Meshy schädliche Inhalte, liefert die Anfrage 400, und Meshy erstellt keine Aufgabe.
Name
target_formats
Type
string[]
Description
Die zu generierenden Dateiformate. Meshy generiert und liefert nur die von Ihnen aufgeführten Formate zurück, wodurch sich die Aufgabe verkürzen kann. Wenn Sie diesen Parameter weglassen, generiert Meshy jedes Format außer 3mf, das Sie nur erhalten, wenn Sie es aufführen.
Verfügbare Werte:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
auto_size
Type
boolean
Standard false
Description
Ob die reale Höhe des Objekts per KI-Bildanalyse geschätzt und das Modell entsprechend skaliert werden soll. Meshy setzt den Ursprung unten, sofern Sie nicht origin_at festlegen.
Name
alpha_thumbnail
Type
boolean
Standard false
Description
Ob zusätzlich eine Vorschau mit transparentem Hintergrund (RGBA) gerendert werden soll, die beim Abrufen der Aufgabe in alpha_thumbnail_url zurückgegeben wird. thumbnail_url ändert sich dadurch nicht.
Name
multi_view_thumbnails
Type
boolean
Standard false
Description
Ob zusätzlich Vorschauen von vorne, rechts, hinten und links gerendert werden sollen, die beim Abrufen der Aufgabe in thumbnail_urls zurückgegeben werden. thumbnail_url ändert sich dadurch nicht und zeigt weiterhin die Vorderansicht. Dies verlängert die Aufgabe um etwa 5 Sekunden.

Gilt nur wenn auto_size = true

Name
origin_at
Type
string
Standard bottom
Description
Wo der Ursprung des Modells platziert werden soll, bottom oder center.

Rückgabewerte

Das Feld result der Antwort enthält die ID der neuen Bild-zu-3D-Aufgabe.

Fehlerfälle

Name
400 - Bad Request
Description
Die Anfrage kann nicht ausgeführt werden. Die Fehlermeldung gibt an, welches Problem gefunden wurde. Beispiele:
- Fehlender Parameter: Weder image_url noch input_task_id wurde gesendet.
- Ungültige Eingabeaufgabe: input_task_id ist keine Text-zu-Bild- oder Bild-zu-Bild-Aufgabe mit dem Status SUCCEEDED, die genau ein Bild erzeugt hat.
- Ungültiges Bildformat: Das Bild unter image_url ist keine JPG-, JPEG-, PNG- oder WebP-Datei.
- Nicht erreichbare URL: Meshy kann das Bild unter image_url nicht herunterladen, weil die URL 404 liefert oder ein Timeout auftritt.
- Bild zu groß: Das Bild unter image_url oder texture_image_url ist größer als 20 MB.
- Ungültige Data URI: Die base64-Zeichenfolge ist fehlerhaft.
- Ungültige Parameterkombination: enable_pbr ist true, und should_texture ist false.
- Nicht unterstütztes Modell für Ultra: geometry_resolution ist 2k oder 4k, mit einem ai_model, das dies nicht ausführen kann.
- Nicht unterstütztes Modell für Bildoptionen: image_enhancement oder remove_lighting wurde mit ai_model: "meshy-6-lite" oder model_type: "smart-topology" gesendet.
Korrigieren Sie die Anfrage, und senden Sie sie dann erneut. Siehe Fehler.
Name
401 - Unauthorized
Description
Der API-Schlüssel fehlt oder ist ungültig. Prüfen Sie den Header Authorization.
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. Prü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 den Abonnement-Einstellungen, und versuchen Sie es erneut.
Name
404 - Not Found
Description
input_task_id stimmt mit keiner Ihrer Aufgaben überein. Prüfen Sie die Aufgaben-ID, und senden Sie die Anfrage dann 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/image-to-3d/:id

Ein Bild-zu-3D-Task abrufen

Gibt einen Bild-zu-3D-Task anhand seiner ID zurück.

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}

Parameter

Name
id
Type
path
Description
Die Task-ID aus der Erstellungsantwort.

Rückgabe

Das Bild-zu-3D-Task-Objekt.

DELETE/openapi/v1/image-to-3d/:id

Image to 3D-Task löschen

Löscht einen Image to 3D-Task dauerhaft, einschließlich seiner Modelle und Daten. Ein Löschvorgang kann nicht rückgängig gemacht werden.

Request

DELETE

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -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.

Taskstatus

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

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

Das Löschen eines Tasks mit einem endgültigen Status (SUCCEEDED, FAILED oder CANCELED) erstattet keine Credits.

Rückgabewerte

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

GET/openapi/v1/image-to-3d

Image to 3D-Aufgaben auflisten

Gibt eine Liste Ihrer Image to 3D-Aufgaben zurück.

Request

GET

/openapi/v1/image-to-3d

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-3d",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
      "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "thumbnail_urls": {
      "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
      "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
      "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
      "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
    },
    "texture_prompt": "",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "expires_at": 1692771679037,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
        "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
        "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
        "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
        "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
      }
    ],
    "preceding_tasks": 0,
    "task_error": {
      "message": ""
    },
    "consumed_credits": 30
  }
]

Parameter

Name
page_num
Type
integer
Standard 1
Description
Die zurückzugebende Seitenzahl. Die Zählung beginnt bei 1.
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ückgabe

Eine paginierte Liste von Image to 3D-Aufgabenobjekten.

GET/openapi/v1/image-to-3d/:id/stream

Einen Bild-zu-3D-Task streamen

Streamt die Updates eines Bild-zu-3D-Tasks als Server-Sent Events (SSE).

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// These examples are shortened. Each event holds the full task object.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
  "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
  "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
  "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
  "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
  "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}

Parameter

Name
id
Type
path
Description
Die Task-ID aus der Antwort der Erstellung.

Rückgabe

Ein Stream von Bild-zu-3D-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, besitzen seine Ergebnisfelder noch keine Werte.

Das Image-to-3D-Task-Objekt

Ein Image-to-3D-Task-Objekt beschreibt eine Generierung eines 3D-Modells aus einem Bild. Es enthält den Status, den Fortschritt und die Modelldateien, wenn der Task erfolgreich ist.

Eigenschaften

Example Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "texture_image_url": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}

Name
id
Type
string
Description
Die Task-ID. Behandeln Sie sie als eine opake Zeichenkette und verlassen Sie sich nicht auf ihr Format.
Name
type
Type
string
Description
Der Task-Typ, immer image-to-3d.
Name
model_urls
Type
object
Description
Download-URLs für das generierte 3D-Modell, eine pro Dateiformat. Ein Format, das der Task nicht generiert hat, besitzt keinen Schlüssel, statt einer leeren Zeichenkette.
- Name
  glb
  Type
  string
  Description
  Die GLB-Datei.
- Name
  fbx
  Type
  string
  Description
  Die FBX-Datei.
- Name
  obj
  Type
  string
  Description
  Die OBJ-Datei.
- Name
  usdz
  Type
  string
  Description
  Die USDZ-Datei.
- Name
  mtl
  Type
  string
  Description
  Die MTL-Datei, die zusammen mit einer OBJ-Datei zurückgegeben wird, wenn das Modell Texturen hat.
- Name
  stl
  Type
  string
  Description
  Die STL-Datei.
- Name
  3mf
  Type
  string
  Description
  Die 3MF-Datei. Nur vorhanden, wenn target_formats 3mf enthält.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  Die GLB-Datei von vor der Neuvernetzung. Nur vorhanden, wenn Sie den Task mit sowohl should_remesh: true als auch save_pre_remeshed_model: true erstellt haben.
Name
thumbnail_url
Type
string
Description
Download-URL für ein Vorschaubild des 3D-Modells. Wenn thumbnail_urls vorhanden ist, handelt es sich um dasselbe Bild wie thumbnail_urls.front. Meshy behält es aus Gründen der Abwärtskompatibilität bei.
Name
alpha_thumbnail_url
Type
string
Description
Download-URL für eine Version von thumbnail_url mit transparentem Hintergrund (RGBA). Nur vorhanden, wenn Sie den Task mit alpha_thumbnail: true erstellt haben und Meshy die transparente Vorschau gerendert hat.
Name
thumbnail_urls
Type
object
Description
Download-URLs für Vorschauen des 3D-Modells aus vier Richtungen. Jeder Wert ist eine signierte URL zu einem 512×512-PNG, das mit denselben Materialien und derselben Beleuchtung wie thumbnail_url gerendert wurde. Verwenden Sie sie, um das Modell aus mehreren Blickwinkeln zu betrachten, zum Beispiel in einer Batch-Pipeline, ohne die GLB-Datei herunterzuladen.
Nur vorhanden, wenn Sie den Task mit multi_view_thumbnails: true erstellt haben und der Task den Status SUCCEEDED erreicht hat. Tasks, die ohne multi_view_thumbnails: true erstellt wurden, enthalten dieses Feld nicht.
- Name
  front
  Type
  string
  Description
  Die Vorderansicht, bei 0° um die vertikale Achse. Sie entspricht thumbnail_url.
- Name
  right
  Type
  string
  Description
  Die rechte Ansicht, bei 90°.
- Name
  back
  Type
  string
  Description
  Die Rückansicht, bei 180°.
- Name
  left
  Type
  string
  Description
  Die linke Ansicht, bei 270°.
Name
texture_prompt
Type
string
Description
Der Textprompt, der die Textur geleitet hat.
Name
texture_image_url
Type
string
Description
Download-URL für das Bild, das die Textur geleitet hat.
Name
ultra_mode
Type
boolean
⚠ veraltet
Description
Verwenden Sie stattdessen geometry_resolution.
Name
geometry_resolution
Type
string
Description
Die Ultra-Stufe, mit der der Task ausgeführt wurde, 2k oder 4k. Ein standard-Task enthält dieses Feld nicht.
Name
progress
Type
integer
Description
Wie viel des Tasks abgeschlossen ist, als Prozentsatz. Es ist 0, bis der Task startet, und 100, wenn er erfolgreich ist.
Name
started_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task gestartet wurde, in Unix-Millisekunden. Es ist 0, bis der Task startet.
Name
created_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task erstellt wurde, in Unix-Millisekunden.
Name
expires_at
Type
timestamp
Description
Zeitpunkt, zu dem das Ergebnis des Tasks abläuft, in Unix-Millisekunden.
Name
finished_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task abgeschlossen wurde, in Unix-Millisekunden. Es ist 0, bis der Task abgeschlossen ist.
Name
status
Type
string
Description
Der Task-Status, einer von PENDING, IN_PROGRESS, SUCCEEDED, FAILED oder CANCELED.
Name
texture_urls
Type
array
Description
Die vom Task generierten Texturkarten, als Array von Objekten. Es enthält in der Regel ein Objekt mit diesen Feldern:
- Name
  base_color
  Type
  string
  Description
  Download-URL für die Basisfarbkarte.
- Name
  metallic
  Type
  string
  Description
  Download-URL für die Metallic-Karte. Das Feld fehlt, wenn Sie den Task mit enable_pbr: false erstellt haben.
- Name
  normal
  Type
  string
  Description
  Download-URL für die Normal Map. Das Feld fehlt, wenn Sie den Task mit enable_pbr: false erstellt haben.
- Name
  roughness
  Type
  string
  Description
  Download-URL für die Rauheitskarte. Das Feld fehlt, wenn Sie den Task mit enable_pbr: false erstellt haben.
- Name
  emission
  Type
  string
  Description
  Download-URL für die Emissionskarte. Das Feld fehlt, wenn Sie den Task mit enable_pbr: false oder texture_resolution: 8k erstellt haben, oder wenn ai_model eines dieser Modelle ist:
  
  meshy-6-lite
  
  meshy-7
  
  meshy-7.1
  
  meshy-t2
  
  meshy-t2.5
  
  latest
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
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. Vorhanden, wenn der Status PENDING, IN_PROGRESS oder SUCCEEDED ist. Bei einem FAILED-Task ist der Wert 0, da Meshy die Credits erstattet, wenn ein Task fehlschlägt.