Bild-zu-3D-API

Die Bild-zu-3D-API ist eine Funktion, mit der Sie die Bild-zu-3D-Fähigkeiten von Meshy in Ihre eigene Anwendung integrieren können. In diesem Abschnitt finden Sie alle Informationen, die Sie benötigen, um mit dieser API zu beginnen.

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

Erstellen einer Bild-zu-3D-Aufgabe

Dieser Endpunkt ermöglicht es Ihnen, eine neue Bild-zu-3D-Aufgabe zu erstellen. Weitere Informationen dazu, welche Eigenschaften im Bild-zu-3D-Aufgabenobjekt enthalten sind, finden Sie unter Das Bild-zu-3D-Aufgabenobjekt.

Parameter

Nur eines von input_task_id oder image_url ist erforderlich. Werden beide angegeben, hat input_task_id Priorität.

Name
input_task_id
Type
string
Erforderlich
Description
Die ID einer abgeschlossenen Bildgenerierungsaufgabe, deren Ausgabe als Eingabebild verwendet werden soll. Diese Aufgabe muss eine der folgenden Aufgaben sein: Text zu Bild oder Bild zu Bild. Außerdem muss sie über die API ausgeführt worden sein, den Status SUCCEEDED haben und genau ein Bild erzeugen.

Name
image_url
Type
string
Erforderlich
Description
Stellen Sie Meshy ein Bild zur Modellerstellung bereit. Derzeit werden die Formate .jpg, .jpeg und .png unterstützt.
Es gibt zwei Möglichkeiten, das Bild bereitzustellen:
- Öffentlich zugängliche URL: Eine URL, die aus dem öffentlichen Internet erreichbar ist.
- Data URI: Ein base64-codierter Data URI des Bildes. Beispiel für einen Data URI: data:image/jpeg;base64,<Ihre base64-codierten Bilddaten>.

Name
model_type
Type
string
Standard standard
Description
Geben Sie die Art der 3D-Netzerzeugung an.
Verfügbare Werte:
- standard: Reguläre hochdetaillierte Netzerzeugung.
- smart-topology: Wählen Sie ein Smart-Topology-Modell mit ai_model (meshy-t2).
- lowpoly (veraltet): Erzeugt ein Low-Poly-Netz, das für saubere Polygone optimiert ist. Wir empfehlen, stattdessen smart-topology zu verwenden.
Wenn smart-topology ausgewählt ist, werden topology, should_remesh und save_pre_remeshed_model ignoriert.
Wenn lowpoly ausgewählt ist, werden ai_model, topology, target_polycount, should_remesh und save_pre_remeshed_model ignoriert.
Name
ai_model
Type
string
Standard latest
Description
ID des zu verwendenden Modells. Die verfügbaren Werte hängen von model_type ab.
Standardgenerierung (model_type: standard):
- meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
- meshy-7 (veraltet): Verwenden Sie stattdessen meshy-7.1.
Smart-Topology-Generierung (model_type: smart-topology):
- meshy-t2 (Standard): das Smart-Topology-Modell — saubere topology, nativ getrennte Teile, Dreiecks-Ausgabe und eine Flächenanzahl, die Sie mit target_polycount festlegen können.
Name
geometry_resolution
Type
string
Standard standard
Description
Durchgang zur Geometrieerzeugung. 2k führt den Ultra-Durchgang bei 2048³ aus; 4k führt ihn bei 4096³ für die feinsten Oberflächendetails aus.
Verfügbare Werte: standard, 2k, 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
Bestimmt, ob Texturen erzeugt werden. Wird dieser Wert auf false gesetzt, wird die Texturphase übersprungen und ein Netz ohne Texturen bereitgestellt.

Gilt nur wenn should_texture = true

Name
enable_pbr
Type
boolean
Standard false
Description
Erzeugt zusätzlich zur Basisfarbe PBR-Texturen (Metallic, Roughness, Normal). Eine Emission-Map wird ebenfalls einbezogen, wenn ai_model meshy-6 ist, außer bei texture_resolution: 8k. meshy-6-lite, meshy-7.1 und latest erzeugen keine Emission-Map.
Name
texture_resolution
Type
string
Standard 2k
Description
Auflösung der Basisfarbtextur. Einer von 2k (2048×2048), 4k (4096×4096) oder 8k (8192×8192). Höhere Auflösungen erfassen mehr Oberflächendetails.
4k und 8k sind bei ai_model meshy-6-lite nicht verfügbar. Bei 8k wird keine Emission-Map erzeugt.
Name
hd_texture
Type
boolean
⚠ veraltet
Standard false
Description
Verwenden Sie stattdessen texture_resolution — entspricht texture_resolution: "4k". Wenn beide gesetzt sind, hat texture_resolution Vorrang.
Name
texture_prompt
Type
string
Description
Geben Sie einen Text-prompt an, um den Texturierungsprozess zu steuern. Maximal 800 Zeichen.
Name
texture_image_url
Type
string
Description
Geben Sie ein 2D-Bild an, um den Texturierungsprozess zu steuern. Derzeit werden die Formate .jpg, .jpeg und .png unterstützt.
Es gibt zwei Möglichkeiten, das Bild bereitzustellen:
- Öffentlich zugängliche URL: Eine URL, die aus dem öffentlichen Internet erreichbar ist
- Data URI: Ein base64-codierter Data URI des Bildes. Beispiel für einen Data URI: data:image/jpeg;base64,<Ihre base64-codierten Bilddaten>
Die Bildtexturierung funktioniert möglicherweise nicht optimal, wenn erhebliche geometrische Unterschiede zwischen dem ursprünglichen Asset und dem hochgeladenen Bild bestehen. Nur eines von texture_image_url oder texture_prompt kann verwendet werden, um den Texturierungsprozess zu steuern. Werden beide Parameter angegeben, wird standardmäßig texture_prompt zur Texturierung des Modells verwendet. Die Texturierung per Text oder Bild kostet 10 Credits pro Aufgabe.

Name
should_remesh
Type
boolean
Standard false (Meshy 6 and Meshy 7 models), true (others)
Description
Steuert, ob die Neuvernetzungsphase aktiviert wird. Für das qualitativ hochwertigste Modell empfehlen wir, should_remesh auf false zu setzen.

Gilt nur wenn should_remesh = true

Name
topology
Type
string
Standard triangle
Description
Geben Sie die topology des erzeugten Modells an.
Verfügbare Werte:
- quad: Erzeugt ein überwiegend aus Vierecken bestehendes Netz.
- triangle: Erzeugt ein reduziertes Dreiecksnetz.
Name
decimation_mode
Type
integer
Description
Aktivieren Sie die adaptive Reduzierung, indem Sie eine Polygonanzahl-Stufe festlegen. Wenn dies gesetzt ist, wird target_polycount ignoriert.
Verfügbare Werte:
- 1: Adaptiv — ultra hohe Polygonanzahl.
- 2: Adaptiv — hohe Polygonanzahl.
- 3: Adaptiv — mittlere Polygonanzahl.
- 4: Adaptiv — niedrige Polygonanzahl.
Name
save_pre_remeshed_model
Type
boolean
Standard false
Description
Wird dieser Wert auf true gesetzt, speichert Meshy zusätzlich eine weitere GLB-Datei, bevor die Neuvernetzungsphase abgeschlossen ist.

Name
target_polycount
Type
integer
Description
Zielanzahl der Polygone (Flächen) in der Ausgabe. Die tatsächliche Anzahl kann je nach Geometrie vom Zielwert abweichen.
target_polycount wirkt sich in zwei unabhängigen Fällen aus:
- Neuvernetzung — mit should_remesh: true bei einem standard-Modell. Das Netz wird auf ungefähr diese Anzahl neu vernetzt (reduziert). Bereich 100 bis 300.000, Standardwert 30.000. Wenn decimation_mode gesetzt ist, hat es Vorrang und target_polycount wird ignoriert.
- Smart Topology — mit model_type: smart-topology und ai_model: meshy-t2. Das Modell wird direkt mit dieser Flächenanzahl erzeugt; es findet keine Neuvernetzung statt und should_remesh ist nicht erforderlich. Bereich 100 bis 15.000, Standardwert 4.000.

Name
symmetry_mode
Type
string
⚠ veraltet
Standard auto
Description
Veraltet. Dieser Parameter beeinflusst die Ausgabe nicht mehr.
Das Feld symmetry_mode steuert das Symmetrieverhalten während des Modellgenerierungsprozesses.
Die gültigen Werte sind:
- off: Deaktiviert die Symmetrie.
- auto: Bestimmt und wendet die Symmetrie automatisch basierend auf der Eingabegeometrie an.
- on: Erzwingt Symmetrie während der Generierung.
Name
pose_mode
Type
string
Standard ""
Description
Geben Sie den pose_mode für das erzeugte Modell an.
Verfügbare Werte:
- a-pose: Erzeugt das Modell in einer A-Pose.
- t-pose: Erzeugt das Modell in einer T-Pose.
- "" (leere Zeichenkette): Keine bestimmte Pose angewendet.
Name
is_a_t_pose
Type
boolean
⚠ veraltet
Standard false
Description
Verwenden Sie stattdessen pose_mode. Ob das Modell in einer A/T-Pose erzeugt werden soll.
Name
image_enhancement
Type
boolean
Standard true
Description
Optimiert das Eingabebild für bessere Ergebnisse. Setzen Sie den Wert auf false, um das exakte Erscheinungsbild des Eingabebildes ohne jegliche Stilverarbeitung zu erhalten.
Wird nur unterstützt, wenn ai_model meshy-6, meshy-7.1 oder latest ist.
Name
remove_lighting
Type
boolean
Standard true
Description
Entfernt Glanzlichter und Schatten aus der Basisfarbtextur und erzeugt so ein sauberes Ergebnis, das unter individuellen Beleuchtungseinstellungen besser funktioniert.
Wird nur unterstützt, wenn ai_model meshy-6 ist.
Name
moderation
Type
boolean
Standard false
Description
Wird dieser Wert auf true gesetzt, wird der Eingabeinhalt automatisch auf potenziell schädliche Inhalte überprüft. Wird schädlicher Inhalt erkannt, geht die Aufgabe nicht in die Generierung über.
Der Inhalt der Eingaben image_url, texture_image_url und texture_prompt wird überprüft.
Name
target_formats
Type
string[]
Description
Legt fest, welche 3D-Dateiformate in die Ausgabe einbezogen werden. Nur die angeforderten Formate werden erzeugt und zurückgegeben, was die Aufgabenlaufzeit verkürzen kann. Wenn dieser Parameter nicht angegeben wird, werden alle unterstützten Formate einbezogen.
Verfügbare Werte: glb, obj, fbx, stl, usdz, 3mf
Wenn nicht angegeben, werden alle Formate außer 3mf erzeugt. 3mf wird nur einbezogen, wenn es explizit angegeben wird.
Name
auto_size
Type
boolean
Standard false
Description
Wird dieser Wert auf true gesetzt, verwendet der Dienst KI-Bilderkennung, um automatisch die reale Höhe des Objekts zu schätzen und das Modell entsprechend zu skalieren. Der Ursprung wird standardmäßig auf bottom gesetzt, sofern origin_at nicht explizit angegeben ist.
Name
alpha_thumbnail
Type
boolean
Standard false
Description
Wird dieser Wert auf true gesetzt, rendert die Aufgabe zusätzlich eine Version der Vorschau mit transparentem Hintergrund (RGBA) und gibt diese als alpha_thumbnail_url in der GET-Antwort zurück. Das vorhandene Feld thumbnail_url bleibt unverändert.
Name
multi_view_thumbnails
Type
boolean
Standard false
Description
Wird dieser Wert auf true gesetzt, rendert die Aufgabe zusätzlich vier Ansichten aus den Hauptrichtungen (vorne, rechts, hinten, links) und gibt diese unter thumbnail_urls in der GET-Antwort zurück. Das vorhandene Feld thumbnail_url bleibt unverändert und verweist weiterhin auf die Vorderansicht, sodass bestehende Clients nicht beeinträchtigt werden.
Erhöht die Aufgabenlaufzeit um etwa 3 Sekunden.

Gilt nur wenn auto_size = true

Name
origin_at
Type
string
Standard bottom
Description
Position des Ursprungs, wenn auto_size aktiviert ist.
Verfügbare Werte: bottom, center.

Rückgabewerte

Die Eigenschaft result der Antwort enthält die Aufgaben-id der neu erstellten Bild-zu-3D-Aufgabe.

Fehlermodi

Name
400 - Bad Request
Description
Die Anfrage war nicht akzeptabel. Häufige Ursachen:
- Fehlender Parameter: Entweder image_url oder input_task_id muss angegeben werden.
- Ungültige Eingabeaufgabe: input_task_id muss sich auf eine SUCCEEDED-Aufgabe des Typs Text zu Bild oder Bild zu Bild beziehen, die genau ein Bild erzeugt.
- Ungültiges Bildformat: Das angegebene image_url hat kein unterstütztes Format (.jpg, .jpeg, .png).
- Nicht erreichbare URL: Das image_url konnte nicht herunterladen werden (404 oder timeout).
- Ungültiger Data URI: Die base64-Zeichenkette ist fehlerhaft.
- Ungültige Parameterkombination: enable_pbr wird nur unterstützt, wenn should_texture true ist.
- Nicht unterstütztes Modell für Low-Poly: ai_model: "meshy-6-lite" unterstützt model_type: "lowpoly" nicht.
- Nicht unterstütztes Modell für Ultra: geometry_resolution erfordert meshy-7.1 oder latest.
Name
401 - Unauthorized
Description
Authentifizierung fehlgeschlagen. Bitte überprüfen Sie Ihren API-Schlüssel.
Name
402 - Payment Required
Description
Unzureichende Credits, um diese Aufgabe durchzuführen.
Name
429 - Too Many Requests
Description
Sie haben Ihre Ratenbegrenzung überschritten.

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

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

Ruft eine Bild-zu-3D-Aufgabe ab

Dieser Endpunkt ermöglicht es Ihnen, eine Bild-zu-3D-Aufgabe anhand einer gültigen Aufgaben-id abzurufen. Weitere Informationen dazu, welche Eigenschaften im Bild-zu-3D-Aufgabenobjekt enthalten sind, finden Sie unter Das Bild-zu-3D-Aufgabenobjekt.

Parameter

Name
id
Type
path
Description
Eindeutige Kennung der abzurufenden Bild-zu-3D-Aufgabe.

Rückgabewerte

Die Antwort enthält das Bild-zu-3D-Aufgabenobjekt. Weitere Details finden Sie im Abschnitt Das Bild-zu-3D-Aufgabenobjekt.

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
}

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

Delete an Image to 3D Task

Dieser Endpunkt löscht eine Bild-zu-3D-Aufgabe dauerhaft, einschließlich aller zugehörigen Modelle und Daten. Diese Aktion ist unwiderruflich.

Pfadparameter

Name
id
Type
path
Description
Die ID der zu löschenden Bild-zu-3D-Aufgabe.

Aufgabenstatus

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

Eine Aufgabe, die bereits IN_PROGRESS ist, 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 mitten im Ablauf würde Sie daher sowohl die Credits als auch das Ergebnis kosten. Warten Sie, bis der Status SUCCEEDED, FAILED oder CANCELED erreicht ist, und löschen Sie die Aufgabe dann.

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

Rückgabewerte

Gibt bei Erfolg 200 OK zurück, oder 409 Conflict, wenn die Aufgabe IN_PROGRESS ist.

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 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/image-to-3d

Bild zu 3D Aufgaben auflisten

Dieser Endpunkt ermöglicht es Ihnen, eine Liste von Bild-zu-3D-Aufgaben abzurufen.

Parameter

Optionale Attribute

Name
page_num
Type
integer
Description
Seitennummer für die Paginierung. Beginnt bei und ist standardmäßig 1.
Name
page_size
Type
integer
Description
Begrenzung der Seitengröße. Standardmäßig 10 Einträge. Maximal erlaubt sind 100 Einträge.
Name
sort_by
Type
string
Description
Feld, nach dem sortiert werden soll. Verfügbare Werte:
- +created_at: Sortierung nach Erstellungszeitpunkt in aufsteigender Reihenfolge.
- -created_at: Sortierung nach Erstellungszeitpunkt in absteigender Reihenfolge.

Rückgabewerte

Gibt eine paginierte Liste der Bild-zu-3D-Aufgabenobjekte 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
  }
]

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

Streamen einer Bild-zu-3D-Aufgabe

Dieser Endpunkt streamt Echtzeit-Updates für eine Bild-zu-3D-Aufgabe mittels Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Eindeutige Kennung der zu streamenden Bild-zu-3D-Aufgabe.

Rückgabewerte

Gibt einen Stream von Das Bild-zu-3D-Aufgabenobjekt 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/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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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
}

Das Bild-zu-3D-Task-Objekt

Das Bild-zu-3D-Task-Objekt ist eine Arbeitseinheit, die Meshy verfolgt, um aus einer Bild-Eingabe ein 3D-Modell zu generieren. Das Objekt verfügt über die folgenden Eigenschaften:

Eigenschaften

Name
id
Type
string
Description
Eindeutiger Bezeichner für den Task. Obwohl wir als Implementierungsdetail eine k-sortierbare UUID für Task-IDs verwenden, solltest du keine Annahmen über das Format der ID treffen.
Name
type
Type
string
Description
Typ des Bild-zu-3D-Tasks. Der Wert ist image-to-3d.
Name
model_urls
Type
object
Description
Herunterladbare URL zur texturierten 3D-Modelldatei, die von Meshy generiert wurde. Die Eigenschaft für ein Format wird weggelassen, wenn das Format nicht generiert wurde, anstatt eine leere Zeichenfolge zurückzugeben.
- Name
  glb
  Type
  string
  Description
  Herunterladbare URL zur GLB-Datei.
- Name
  fbx
  Type
  string
  Description
  Herunterladbare URL zur FBX-Datei.
- Name
  obj
  Type
  string
  Description
  Herunterladbare URL zur OBJ-Datei.
- Name
  usdz
  Type
  string
  Description
  Herunterladbare URL zur USDZ-Datei.
- Name
  mtl
  Type
  string
  Description
  Herunterladbare URL zur MTL-Datei, die zusammen mit OBJ-Exporten zurückgegeben wird, wenn Texturen vorhanden sind.
- Name
  stl
  Type
  string
  Description
  Herunterladbare URL zur STL-Datei.
- Name
  3mf
  Type
  string
  Description
  Herunterladbare URL zur 3MF-Datei. Nur vorhanden, wenn 3mf über target_formats angefordert wurde.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  Herunterladbare URL zum ursprünglichen GLB-Output vor dem Remeshing.
  Nur verfügbar, wenn der Task sowohl mit should_remesh: true als auch mit save_pre_remeshed_model: true erstellt wurde.
Name
thumbnail_url
Type
string
Description
Herunterladbare URL zum Vorschaubild der Modelldatei. Entspricht thumbnail_urls.front, sofern vorhanden, und wird aus Gründen der Abwärtskompatibilität beibehalten.
Name
alpha_thumbnail_url
Type
string
Description
Herunterladbare URL zu einer Version von thumbnail_url mit transparentem Hintergrund (RGBA). Nur vorhanden, wenn der Task mit alpha_thumbnail: true erstellt wurde und die transparente Vorschau erfolgreich gerendert wurde; andernfalls wird dieses Feld weggelassen.
Name
thumbnail_urls
Type
object
Description
Herunterladbare URLs für vier Miniaturansichten des generierten 3D-Modells aus den Hauptrichtungen. Jeder Wert ist eine signierte URL zu einem 512×512-PNG, das mit denselben Materialien und derselben Beleuchtung wie thumbnail_url gerendert wurde. Nützlich, um das Modell in Batch-Pipelines aus mehreren Blickwinkeln in der Vorschau zu betrachten, ohne die GLB-Datei herunterzuladen.
Nur vorhanden, wenn der Task mit multi_view_thumbnails: true erstellt wurde und den Status SUCCEEDED erreicht hat. Ältere Tasks und Tasks, die ohne diese Opt-in-Option erstellt wurden, enthalten dieses Feld nicht.
- Name
  front
  Type
  string
  Description
  Vorderansicht, 0° Rotation um die vertikale Achse (entspricht thumbnail_url).
- Name
  right
  Type
  string
  Description
  Rechte Ansicht, 90° Rotation.
- Name
  back
  Type
  string
  Description
  Rückansicht, 180° Rotation.
- Name
  left
  Type
  string
  Description
  Linke Ansicht, 270° Rotation.
Name
texture_prompt
Type
string
Description
Der Text-Prompt, der zur Steuerung des Texturierungsprozesses verwendet wurde.
Name
texture_image_url
Type
string
Description
Herunterladbare URL zum Texturbild, das zur Steuerung des Texturierungsprozesses verwendet wurde.
Name
ultra_mode
Type
boolean
⚠ veraltet
Description
Veraltet; lies stattdessen geometry_resolution.
Name
geometry_resolution
Type
string
Description
Die Ultra-Stufe, mit der der Task ausgeführt wurde (2k oder 4k); wird für standard weggelassen.
Name
progress
Type
integer
Description
Fortschritt des Tasks. Wenn der Task noch nicht gestartet wurde, ist diese Eigenschaft 0. Sobald der Task erfolgreich abgeschlossen wurde, wird dieser Wert 100.
Name
started_at
Type
timestamp
Description
Zeitstempel, wann der Task gestartet wurde, in Millisekunden. Wenn der Task noch nicht gestartet wurde, ist diese Eigenschaft 0.
Ein Zeitstempel repräsentiert die Anzahl der Millisekunden, die seit dem 1. Januar 1970 UTC vergangen sind, gemäß dem Standard RFC 3339. Zum Beispiel wird Freitag, der 1. September 2023, 12:00:00 Uhr GMT als 1693569600000 dargestellt. Dies gilt für alle Zeitstempel in der Meshy API.
Name
created_at
Type
timestamp
Description
Zeitstempel, wann der Task erstellt wurde, in Millisekunden.
Name
expires_at
Type
timestamp
Description
Zeitstempel, wann das Taskergebnis abläuft, in Millisekunden.
Name
finished_at
Type
timestamp
Description
Zeitstempel, wann der Task abgeschlossen wurde, in Millisekunden. Wenn der Task noch nicht abgeschlossen ist, ist diese Eigenschaft 0.
Name
status
Type
string
Description
Status des Tasks. Mögliche Werte sind einer von PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Ein Array von Textur-URL-Objekten, die aus dem Task generiert werden. Normalerweise enthält dies nur ein Textur-URL-Objekt. Jede Textur-URL hat die folgenden Eigenschaften:
- Name
  base_color
  Type
  string
  Description
  Herunterladbare URL zum Base-Color-Map-Bild.
- Name
  metallic
  Type
  string
  Description
  Herunterladbare URL zum Metallic-Map-Bild.
  Wenn der Task mit enable_pbr: false erstellt wurde, wird diese Eigenschaft weggelassen.
- Name
  normal
  Type
  string
  Description
  Herunterladbare URL zum Normal-Map-Bild.
  Wenn der Task mit enable_pbr: false erstellt wurde, wird diese Eigenschaft weggelassen.
- Name
  roughness
  Type
  string
  Description
  Herunterladbare URL zum Roughness-Map-Bild.
  Wenn der Task mit enable_pbr: false erstellt wurde, wird diese Eigenschaft weggelassen.
- Name
  emission
  Type
  string
  Description
  Herunterladbare URL zum Emission-Map-Bild.
  Wenn der Task mit enable_pbr: false erstellt wurde oder ai_model meshy-6-lite, meshy-7.1 oder latest ist, wird diese Eigenschaft weggelassen.
Name
preceding_tasks
Type
integer
Description
Die Anzahl der vorangehenden Tasks.
Der Wert dieses Felds ist nur dann aussagekräftig, wenn der Task-Status PENDING ist.
Name
task_error
Type
object
Description
Fehlerdetails für fehlgeschlagene Tasks. Siehe Fehler für die vollständige Referenz des task_error-Objekts.
Name
consumed_credits
Type
integer
Description
Die Anzahl der von diesem Task verbrauchten Credits. Vorhanden, wenn der Task-Status PENDING, IN_PROGRESS oder SUCCEEDED ist. Gibt 0 für Tasks mit Status FAILED zurück (Credits werden bei Fehlschlag zurückerstattet).

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
}