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

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

Erstellen einer Bild-zu-3D-Aufgabe

Erstellt eine Bild-zu-3D-Aufgabe. Die Aufgabe läuft im Hintergrund. Wie lange eine Aufgabe normalerweise 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"]
  }'

# Textured with Meshy N1 from the input image
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",
    "texture_model": "meshy-n1"
  }'

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 mit der API erstellt worden sein, 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 als 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, mindestens 32 Pixel auf jeder Seite haben und höchstens 178.956.970 Pixel (Breite × Höhe) umfassen.

  • Name
    model_type
    Type
    string
    Standard standard
    Description

    Die Art des zu generierenden 3D-Netzes.

    Verfügbare Werte:

    • standard: ein Netz mit hohem Detailgrad
    • 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 generiert. 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. Es wird am 31. Dezember 2026 eingestellt.

    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 nativ getrennte Teile
    • meshy-t2.5 (Standard): schärfere Details für Game-Assets

    Unter Modelle finden Sie, welches Modell zu Ihrem Projekt passt, etwa einem Spielcharakter oder einem 3D-Druck.

  • Name
    geometry_resolution
    Type
    string
    Standard standard
    Description

    Der Durchgang zur Geometriegenerierung.

    Verfügbare Werte:

    • standard
    • 2k: führt den Ultra-Durchgang bei 2048³ aus
    • 4k: führt den Ultra-Durchgang bei 4096³ aus, für das meiste Oberflächendetail

    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 das Texturieren und liefert ein untexturiertes Netz.

Gilt nur wenn should_texture = true
  • Name
    texture_model
    Type
    string
    Standard depends on ai_model
    Description

    Das KI-Modell, das das 3D-Modell in derselben Aufgabe texturiert. Lassen Sie es weg, um das Standard-Texturmodell für Ihr ai_model zu verwenden. Es ändert nicht die Credit-Kosten.

    Verfügbare Werte:

    • meshy-7: Meshy 7, mit PBR-Texturen und Texturen bis zu 8K
    • meshy-n1: Meshy N1, eine 2K-Basisfarbtextur nur aus Referenzbildern
    • meshy-6-lite: Meshy 6 Lite, eine 2K-Textur zu den geringsten Kosten
    • meshy-6: Meshy 6, nur als Standard für ai_model: meshy-6

    Jedes ai_model akzeptiert meshy-7, meshy-n1 und meshy-6-lite. Eine Option, die das gewählte Texturmodell nicht unterstützt, liefert 400. Bei meshy-n1 schlägt die Aufgabe bei einem generierten Modell mit über 7.999.999 Dreiecken fehl, und Meshy erstattet dessen Credits. Bei should_texture: false ignoriert Meshy texture_model, aber ein unbekannter Wert liefert trotzdem 400.

    Unter Modelle erfahren Sie, was jedes Texturmodell leistet und welches Sie wählen sollten.

  • Name
    enable_pbr
    Type
    boolean
    Standard false
    Description

    Ob zusätzlich zur Basisfarbe auch PBR-Texturen (Metallic, Roughness und Normal) generiert werden sollen. true erfordert should_texture: true und liefert 400 bei should_texture: false. Bei texture_model: meshy-n1 liefert true den Fehler 400.

    Das Texturmodell Meshy 6 generiert außerdem eine Emission Map, außer bei texture_resolution: 8k.

  • Name
    texture_resolution
    Type
    string
    Standard 2k
    Description

    Die Größe der Basisfarbtextur. Eine größere Textur erfasst mehr Oberflächendetails.

    Verfügbare Werte:

    • 2k: 2048×2048
    • 4k: 4096×4096
    • 8k: 8192×8192

    4k und 8k erfordern das Texturmodell Meshy 7 oder Meshy 6 und liefern bei den anderen 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 leitet, bis zu 800 Zeichen. Längerer Text liefert 400. Bei texture_model: meshy-n1 liefert das Senden 400.

  • Name
    texture_image_url
    Type
    string
    Description

    Ein Bild, das die Textur leitet, als öffentliche URL oder als 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, mindestens 32 Pixel auf jeder Seite haben und höchstens 178.956.970 Pixel (Breite × Höhe) umfassen.

    Meshy leitet die Textur nur mit einem von texture_prompt und texture_image_url. Wenn Sie beides senden, verwendet Meshy texture_prompt. Zu den Credit-Kosten des Texturierens siehe Preise.

    Bei texture_model: meshy-n1 texturiert Meshy anhand dieses Bildes als Vorderansicht, oder anhand des Eingabebildes, wenn Sie es weglassen.

  • 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 dezimiertes Dreiecksnetz

    Die Ausgabe von Smart Topology besteht ausschließlich aus Dreiecken, daher liefert quad bei meshy-t2 oder meshy-t2.5 den Fehler 400. Bei texture_model: meshy-n1 liefert quad 400, wenn das Modell neu vernetzt wird, was meshy-6-lite standardmäßig tut.

  • Name
    decimation_mode
    Type
    integer
    Description

    Adaptive Flächenanzahl, nach Stufe. Wenn Sie diese festlegen, 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 diese in model_urls.pre_remeshed_glb.

  • Name
    target_polycount
    Type
    integer
    Description

    Die anzustrebende Flächenanzahl. Das Ergebnis kann je nach Geometrie des Modells vom Zielwert abweichen.

    Dies gilt in zwei getrennten Fällen:

    • Neuvernetzung: Wenn should_remesh bei einem standard-Modell true ist, dezimiert Meshy das Netz auf etwa diese Anzahl. Wenn Sie decimation_mode festlegen, verwendet Meshy diesen und ignoriert target_polycount.
    • Smart Topology: Wenn model_type smart-topology ist und ai_model meshy-t2 oder meshy-t2.5 ist, generiert Meshy das Modell mit dieser Flächenanzahl. Es läuft keine Neuvernetzung, und Sie benötigen should_remesh nicht.

    Bereich und Standardwert hängen vom Fall ab:

    FallBereichStandard
    Neuvernetzung100 bis 30000030000
    meshy-t2100 bis 150004000
    meshy-t2.5100 bis 3000015000

    Ein Wert außerhalb des Bereichs liefert 400.

    Für ein Low-Poly-Game-Asset verwenden Sie ein Smart-Topology-Modell statt ein Standardmodell neu zu vernetzen. Siehe Modelle.

  • 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: Symmetrie, gewählt anhand der Eingabegeometrie
    • on: erzwungene Symmetrie
  • Name
    pose_mode
    Type
    string
    Description

    Die Pose für ein Charaktermodell, a-pose oder t-pose. Um keine Pose zu erhalten, lassen Sie pose_mode und is_a_t_pose weg.

  • 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 generiert 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 Eingabebildes bei, ohne Stilverarbeitung.

    Dies funktioniert nur mit meshy-6, meshy-7.1 oder latest. Bei 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 Basisfarbtextur entfernt werden sollen. Das Ergebnis ist sauberer und funktioniert besser unter Ihrer eigenen Beleuchtung.

    Dies wirkt sich nur beim Texturmodell Meshy 6 aus, und ein Texturmodell, das dies nicht unterstützt, liefert bei true den Fehler 400. Bei model_type: smart-topology, oder bei ai_model: meshy-6-lite und dessen Standard-Texturmodell, liefert das Senden 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

    Wenn Meshy schädliche Inhalte erkennt, 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, was die Aufgabe verkürzen kann. Wenn Sie diesen Parameter weglassen, generiert Meshy jedes Format außer 3mf, das Sie nur erhalten, wenn Sie es auflisten.

    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-Bildverarbeitung geschätzt und das Modell darauf skaliert werden soll. Meshy setzt den Ursprung unten, es sei denn, Sie legen origin_at fest.

  • 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 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 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ückgabe

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

Fehlermodi

  • 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 image_url noch input_task_id wurde gesendet.
    • Ungültige Eingabeaufgabe: input_task_id ist keine SUCCEEDED-Text-zu-Bild- oder Bild-zu-Bild-Aufgabe, die genau ein Bild erzeugt hat.
    • Ungültiges Bildformat: Das Bild unter image_url ist keine JPG-, JPEG-, PNG- oder WebP-Datei.
    • Unerreichbare URL: Meshy kann das Bild unter image_url nicht herunterladen, weil die URL 404 liefert oder eine Zeitüberschreitung auftritt.
    • Bild zu groß: Das Bild unter image_url oder texture_image_url ist größer als 20 MB.
    • Ungültige Bildgröße: Das Bild unter image_url oder texture_image_url hat eine Seite, die kürzer als 32 Pixel ist, oder mehr als 178.956.970 Pixel (Breite × Höhe).
    • 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: einer der folgenden Fälle:
      • image_enhancement wurde mit ai_model: "meshy-6-lite" oder model_type: "smart-topology" gesendet.
      • remove_lighting wurde mit model_type: "smart-topology" gesendet, oder mit ai_model: "meshy-6-lite" und dessen Standard-Texturmodell.
    • Ungültiges Texturmodell: texture_model ist keiner der verfügbaren Werte.
    • Texturmodell nicht verfügbar: texture_model ist meshy-6 mit einem ai_model ungleich meshy-6. Senden Sie meshy-7, meshy-n1 oder meshy-6-lite, oder lassen Sie den Parameter weg.
    • Nicht unterstützte Option für das Texturmodell: Die Anfrage verlangt vom Texturmodell eine Option, die es nicht unterstützt, z. B. enable_pbr: true mit meshy-n1 oder eine 4k-Textur mit meshy-6-lite. Siehe Modelle.

    Korrigieren Sie die Anfrage und senden Sie sie erneut. Siehe Fehler.

  • Name
    401 - Unauthorized
    Description

    Der API-Schlüssel fehlt oder ist ungültig. Prüfen Sie den Authorization-Header.

  • Name
    402 - Payment Required
    Description

    Zum Beispiel:

    • Unzureichende Credits: Das Konto verfügt nicht über 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 Ihren Abonnementeinstellungen und versuchen Sie es erneut.
  • Name
    403 - Forbidden
    Description

    Die Inhaltsmoderation hat den Prompt oder ein Eingabebild blockiert. Ändern Sie die Eingabe 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 erneut.

  • Name
    429 - Too Many Requests
    Description

    Sie haben Ihre Ratenbegrenzung überschritten. Warten Sie und versuchen Sie es 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": null,
  "consumed_credits": 30
}

Parameter

  • Name
    id
    Type
    path
    Description

    Die Task-ID aus der Antwort der Erstellung.

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 Bild zu 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": null,
    "consumed_credits": 30
  }
]

Parameter

  • Name
    page_num
    Type
    integer
    Standard 1
    Description

    Die zurückzugebende Seitenzahl, 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 Bild zu 3D-Aufgabenobjekten.


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

Einen Image-to-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": null,
  "consumed_credits": 30
}

Parameter

  • Name
    id
    Type
    path
    Description

    Die Task-ID aus der Antwort der Erstellung.

Rückgabewerte

Ein Stream von Image-to-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, haben 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 progress 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": null,
  "consumed_credits": 30
}
  • Name
    id
    Type
    string
    Description

    Die Task-ID. Behandeln Sie sie als eine undurchsichtige 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, hat keinen Schlüssel, statt eines leeren Strings.

    • 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, zurückgegeben zusammen mit einer OBJ-Datei, 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 sowohl mit 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, ist es 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, gerendert mit denselben Materialien und derselben Beleuchtung wie thumbnail_url. Verwenden Sie sie, um das Modell aus mehreren Winkeln 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 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 Text-prompt, 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

    Lesen 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 erledigt ist, als Prozentsatz. Der Wert ist 0, bis der Task beginnt, und 100, wenn er erfolgreich ist.

  • 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
    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 beendet wurde, in Unix-Millisekunden. Der Wert ist 0, bis der Task beendet 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 normalerweise 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. Meshy fügt sie nur hinzu, wenn Sie den Task mit allen folgenden Einstellungen erstellt haben:

      • ai_model: meshy-6, mit seinem Standard-Texturmodell
      • enable_pbr: true
      • einer texture_resolution von 2k oder 4k
  • 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. Der Wert ist null, außer wenn der Status FAILED ist. 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 er 0, da Meshy die Credits erstattet, wenn ein Task fehlschlägt.