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

Multi-Bild zu 3D API

Erstelle ein 3D-Modell aus ein bis vier Bildern desselben Objekts, die aus unterschiedlichen Winkeln aufgenommen wurden.


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

Erstellen einer Multi-Bild zu 3D-Aufgabe

Erstellt eine Multi-Bild zu 3D-Aufgabe. Die Aufgabe läuft im Hintergrund. Wie lange eine Aufgabe in der Regel dauert, erfahren Sie unter Bearbeitungszeiten. Welche Felder eine Aufgabe besitzt, erfahren Sie unter Das Multi-Bild zu 3D-Aufgabenobjekt.

Request

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

# With Ultra 2K geometry, PBR texturing, and GLB format
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_urls": [
      "<your publicly accessible image url or base64-encoded data URI>",
      "<your second publicly accessible image url or base64-encoded data URI>"
    ],
    "ai_model": "meshy-7.1",
    "geometry_resolution": "2k",
    "should_texture": true,
    "enable_pbr": true,
    "target_formats": ["glb"]
  }'

# Textured with Meshy N1 from the input images, the first as the front view
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_urls": [
      "<your front view image url or base64-encoded data URI>",
      "<your back view 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, außer Sie senden image_urls. Die ID einer Text zu Bild- oder Bild zu Bild-Aufgabe, einschließlich einer Mehransicht-Aufgabe. Meshy verwendet deren ein bis vier Bilder als Eingabe. Die Aufgabe muss eine sein, die Sie mit der API erstellt haben und den Status SUCCEEDED aufweist.

  • Name
    image_urls
    Type
    array
    Erforderlich
    Description

    Erforderlich, außer Sie senden input_task_id. Ein bis vier Bilder, jeweils als öffentliche URL oder als Data URI, zum Beispiel data:image/jpeg;base64,<your base64-encoded image data>. Wenn Sie beide senden, verwendet Meshy input_task_id.

    Jedes Bild muss eine .jpg-, .jpeg-, .png- oder .webp-Datei von höchstens 20 MB sein, mindestens 32 Pixel auf jeder Seite und höchstens 178.956.970 Pixel (Breite × Höhe) haben. Mehr als vier Bilder führt zu 400.

    Für die besten Ergebnisse sollten die Bilder dasselbe Objekt aus unterschiedlichen Blickwinkeln zeigen. Mit meshy-7.1 oder latest verwendet Meshy das erste Bild als Vorderansicht, die Reihenfolge der anderen spielt keine Rolle.

  • Name
    ai_model
    Type
    string
    Standard latest
    Description

    Das KI-Modell, das das 3D-Modell generiert.

    Verfügbare Werte:

    • latest: Meshy 7.1
    • meshy-7.1
    • meshy-6
    • meshy-6-lite
    • meshy-7: veraltet, senden Sie stattdessen meshy-7.1. Es wird am 31. Dezember 2026 eingestellt.

    Unter Modelle erfahren Sie, welches Modell zu Ihrem Projekt passt, etwa für ein reales Objekt oder einen 3D-Druck.

  • Name
    geometry_resolution
    Type
    string
    Standard standard
    Description

    Wie viel Geometriedetail generiert werden soll.

    Verfügbare Werte:

    • standard
    • 2k: führt den Ultra-Durchgang bei 2048³ aus. Benötigt meshy-7.1, latest oder das veraltete meshy-7.
  • Name
    ultra_mode
    Type
    boolean
    ⚠ veraltet
    Standard false
    Description

    Senden 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 den Texturierungsschritt und liefert ein Netz ohne Texturen.

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

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

    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

    Jedes ai_model akzeptiert beide. Eine texturierte Anfrage mit meshy-6 oder meshy-6-lite liefert 400, ebenso eine Option, die das gewählte Texturmodell nicht unterstützt. Mit should_texture: false ignoriert Meshy texture_model, aber ein unbekannter Wert liefert weiterhin 400.

    Mit meshy-n1 texturiert Meshy aus texture_image_urls oder texture_image_url, oder aus den Eingabebildern, wenn Sie keines von beiden senden. Das erste Bild ist die Vorderansicht. Ein generiertes Modell mit über 7.999.999 Dreiecken lässt die Aufgabe fehlschlagen, und Meshy erstattet dessen Credits zurück.

    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 Metallic-, Roughness- und Normal-Maps generiert werden sollen. Das Meshy 6-Texturmodell generiert zusätzlich eine Emission-Map, außer bei texture_resolution: 8k. Mit texture_model: meshy-n1 liefert true den Wert 400.

  • Name
    texture_resolution
    Type
    string
    Standard 2k
    Description

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

    Verfügbare Werte:

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

    4k und 8k benötigen das Meshy 7- oder Meshy 6-Texturmodell und liefern bei den anderen 400. Bei 8k generiert Meshy keine Emission-Map.

  • Name
    hd_texture
    Type
    boolean
    ⚠ veraltet
    Standard false
    Description

    Senden Sie stattdessen texture_resolution. hd_texture: true entspricht texture_resolution: "4k". Wenn Sie beide 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. Mit texture_model: meshy-n1 liefert das Senden 400.

  • Name
    texture_image_url
    Type
    string
    Description

    Ein 2D-Bild, das die Textur steuert, als öffentliche URL oder als Data URI, zum Beispiel 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 und höchstens 178.956.970 Pixel (Breite × Höhe) haben.

    Wenn Sie sowohl texture_image_url als auch texture_prompt senden, verwendet Meshy texture_prompt. Mit texture_model: meshy-n1 texturiert Meshy aus diesem Bild als Vorderansicht.

  • Name
    texture_image_urls
    Type
    string[]
    Description

    Ein bis vier Bilder des Objekts aus unterschiedlichen Ansichten, die die Textur steuern. Meshy verwendet das erste Bild als Vorderansicht. Die Reihenfolge der anderen Ansichten (links, hinten, rechts) spielt keine Rolle.

    Jedes Bild folgt denselben Regeln wie texture_image_url. Es ist eine öffentliche URL oder eine Data URI, im Format .jpg, .jpeg, .png oder .webp, von höchstens 20 MB, mindestens 32 Pixel auf jeder Seite und höchstens 178.956.970 Pixel (Breite × Höhe).

    Diese Bilder steuern nur die Textur und sind unabhängig von image_urls. Die beiden Listen können unterschiedliche Bilder und unterschiedliche Bildanzahlen enthalten.

    texture_image_urls benötigt das Meshy 7- oder Meshy N1-Texturmodell. Senden Sie es mit einem der folgenden:

    • ai_model von meshy-7.1, latest oder dem veralteten meshy-7
    • texture_model von meshy-7 oder meshy-n1

    Sie können es nicht zusammen mit texture_image_url oder texture_prompt senden.

  • Name
    should_remesh
    Type
    boolean
    Standard true (meshy-6-lite), false (other models)
    Description

    Ob das Modell nach der Generierung neu vernetzt werden soll. Für das qualitativ hochwertigste 3D-Modell setzen Sie es 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

    Mit texture_model: meshy-n1 liefert quad den Wert 400, wenn das Modell neu vernetzt wird, was meshy-6-lite standardmäßig tut.

  • Name
    target_polycount
    Type
    integer
    Standard 30000
    Description

    Die anvisierte Anzahl an Flächen, von 100 bis 300000. Das Ergebnis kann je nach Geometrie des Modells vom Zielwert abweichen. Ein Wert außerhalb des Bereichs liefert 400.

  • Name
    decimation_mode
    Type
    integer
    Description

    Adaptive Flächenanzahl, nach Stufe. Wenn Sie dies 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 auch das GLB von vor der Neuvernetzung gespeichert werden soll, zurückgegeben in model_urls.pre_remeshed_glb.

  • Name
    symmetry_mode
    Type
    string
    ⚠ veraltet
    Standard auto
    Description

    Lassen Sie es weg. Es hat keinen Einfluss auf das Ergebnis.

    Verfügbare Werte:

    • off: keine Symmetrie
    • auto: Symmetrie basierend auf 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

    Senden Sie stattdessen pose_mode. Ob das Modell in einer A- oder T-Pose generiert werden soll.

  • Name
    image_enhancement
    Type
    boolean
    Standard true
    Description

    Ob die Eingabebilder vor der Generierung optimiert werden sollen. false behält das exakte Erscheinungsbild der Eingabebilder bei, ohne Stilverarbeitung. Nur mit meshy-6, meshy-7.1 oder latest unterstützt. Wird es mit meshy-6-lite gesendet, liefert dies 400.

  • Name
    remove_lighting
    Type
    boolean
    Standard true
    Description

    Ob Glanzlichter und Schatten aus der Basisfarbtextur entfernt werden sollen. Das sauberere Ergebnis funktioniert besser unter Ihrer eigenen Beleuchtung. Nur das Meshy 6-Texturmodell verwendet dies, und bei texture_resolution: 8k entfernt es die Beleuchtung immer. Mit texture_model: meshy-n1 liefert true den Wert 400. Mit ai_model: meshy-6-lite und seinem Standard-Texturmodell liefert das Senden 400.

  • Name
    moderation
    Type
    boolean
    Standard false
    Description

    Ob die Eingaben auf schädliche Inhalte geprüft werden sollen. Meshy prüft jedes Eingabebild, texture_image_url oder jedes Bild in texture_image_urls sowie den Text in texture_prompt. Findet Meshy schädliche Inhalte, liefert die Anfrage 400, und Meshy erstellt keine Aufgabe.

  • Name
    target_formats
    Type
    string[]
    Description

    Die zu generierenden 3D-Dateiformate. Meshy generiert und liefert nur die von Ihnen aufgelisteten Formate, was die Aufgabe verkürzen kann.

    Verfügbare Werte:

    • glb
    • obj
    • fbx
    • stl
    • usdz
    • 3mf

    Lassen Sie es weg, generiert Meshy jedes Format außer 3mf. Meshy generiert 3mf nur, wenn Sie es auflisten.

  • 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, außer Sie legen origin_at fest.

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.

  • Name
    alpha_thumbnail
    Type
    boolean
    Standard false
    Description

    Ob zusätzlich eine Vorschau mit transparentem Hintergrund (RGBA) gerendert werden soll, zurückgegeben in alpha_thumbnail_url, wenn Sie die Aufgabe abrufen. thumbnail_url ändert sich nicht.

  • Name
    multi_view_thumbnails
    Type
    boolean
    Standard false
    Description

    Ob zusätzlich Vorder-, Rechts-, Rück- und Linksansicht-Vorschauen gerendert werden sollen, zurückgegeben in thumbnail_urls, wenn Sie die Aufgabe abrufen. thumbnail_url ändert sich nicht und zeigt weiterhin die Vorderansicht. Dies verlängert die Aufgabe um etwa 5 Sekunden.

Rückgabewerte

Das Feld result der Antwort enthält die ID der neuen Multi-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_urls noch input_task_id wurde gesendet.
    • Ungültige Eingabe-Aufgabe: input_task_id ist keine SUCCEEDED Text zu Bild- oder Bild zu Bild-Aufgabe oder keine Mehransicht-Aufgabe.
    • Ungültige Bildanzahl: image_urls oder texture_image_urls enthält nicht 1 bis 4 Bilder.
    • Ungültiges Bildformat: Ein Bild in image_urls liegt in keinem unterstützten Format vor.
    • Widersprüchliche Textureingaben: texture_image_urls wurde zusammen mit texture_image_url, mit texture_prompt oder mit should_texture: false gesendet.
    • Nicht unterstütztes Modell für Mehransicht-Textur: texture_image_urls wurde mit ai_model von meshy-6 oder meshy-6-lite gesendet, außer texture_model ist meshy-7 oder meshy-n1.
    • Unerreichbare URL: Meshy kann ein Bild in image_urls oder texture_image_urls nicht herunterladen.
    • Bild zu groß: Ein Bild in image_urls, texture_image_url oder texture_image_urls ist größer als 20 MB.
    • Ungültige Bildgröße: Ein Bild in image_urls, texture_image_url oder texture_image_urls hat eine Seite kürzer als 32 Pixel oder mehr als 178.956.970 Pixel (Breite × Höhe).
    • Nicht unterstützte Auflösung für Mehrbild-Eingabe: geometry_resolution ist "4k", was dieser Endpunkt nicht unterstützt. Verwenden Sie 2k oder standard.
    • Nicht unterstütztes Modell für Bildoptionen: image_enhancement wurde mit ai_model: "meshy-6-lite" gesendet, oder remove_lighting wurde mit ai_model: "meshy-6-lite" und seinem Standard-Texturmodell gesendet.
    • Ungültiges Texturmodell: texture_model ist kein gültiger Texturmodellname.
    • Texturmodell nicht verfügbar: Eine texturierte Anfrage sendete texture_model von meshy-6 oder meshy-6-lite. Multi-Bild zu 3D akzeptiert nur Texturmodelle, die aus mehreren Ansichten texturieren. Senden Sie meshy-7 oder meshy-n1, oder lassen Sie texture_model weg.
    • Nicht unterstützte Option für das Texturmodell: Die Anfrage verlangt vom Texturmodell eine Option, die es nicht unterstützt, etwa 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. Überprü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. Überprü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 Abonnement-Einstellungen 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. Überprü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 dann erneut. Siehe Ratenbegrenzungen.


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

Eine Multi-Bild-zu-3D-Aufgabe abrufen

Gibt eine Multi-Bild-zu-3D-Aufgabe anhand ihrer ID zurück.

Request

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "multi-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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 30
}

Parameter

  • Name
    id
    Type
    path
    Description

    Die Aufgaben-ID aus der Antwort der Erstellung.

Rückgabe

Das Multi-Bild-zu-3D-Aufgabenobjekt.


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

Eine Multi-Bild zu 3D-Aufgabe löschen

Löscht eine Multi-Bild zu 3D-Aufgabe dauerhaft, einschließlich ihrer Modelle und Daten. Eine Löschung kann nicht rückgängig gemacht werden.

Request

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

Aufgabenstatus

Das Löschen einer PENDING-Aufgabe erstattet die Credits, die bei ihrer Erstellung verwendet wurden.

Eine IN_PROGRESS-Aufgabe kann nicht gelöscht werden. Die Anfrage gibt 409 Conflict zurück, und die Aufgabe läuft weiter. Meshy erstattet keine Aufgabe, die bereits gestartet wurde, daher würde das Löschen sowohl die Credits als auch das Ergebnis kosten. Warten Sie, bis sie SUCCEEDED, FAILED oder CANCELED erreicht, und löschen Sie sie dann.

Das Löschen einer Aufgabe in einem Endstatus (SUCCEEDED, FAILED oder CANCELED) erstattet keine Credits.

Rückgabewerte

200 OK, wenn die Aufgabe gelöscht wurde, oder 409 Conflict, wenn sich die Aufgabe im Status IN_PROGRESS befindet.


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

Liste der Multi-Bild zu 3D-Aufgaben

Gibt eine Liste deiner Multi-Bild zu 3D-Aufgaben zurück.

Request

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "multi-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"
      }
    ],
    "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 liefert 400.

  • 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 Multi-Bild zu 3D-Aufgabenobjekten.


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

Einen Multi-Bild-zu-3D-Task streamen

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

Request

GET
/openapi/v1/multi-image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.ai/openapi/v1/multi-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": "multi-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"
    }
  ],
  "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

Ein Stream von Multi-Bild-zu-3D-Task-Objekten als Server-Sent Events.

Jedes Ereignis 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 Multi-Bild-zu-3D-Task-Objekt

Ein Multi-Bild-zu-3D-Task-Objekt beschreibt eine Generierung eines 3D-Modells aus ein bis vier Bildern eines Objekts. Es enthält den Status, den progress und die Modelldateien, wenn der Task erfolgreich ist.

Eigenschaften

Example Multi-Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "multi-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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 30
}
  • Name
    id
    Type
    string
    Description

    Die Task-ID. Behandeln Sie sie als intransparente Zeichenkette und verlassen Sie sich nicht auf ihr Format.

  • Name
    type
    Type
    string
    Description

    Der Task-Typ, immer multi-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 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, zurückgegeben zusammen mit der 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 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 Modells. Sie ist identisch mit thumbnail_urls.front, wenn dieses Feld vorhanden ist.

  • 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. Jede ist eine signierte URL zu einem 512×512-PNG, gerendert mit denselben Materialien und derselben Beleuchtung wie thumbnail_url. Sie können diese verwenden, um das Modell aus mehreren Blickwinkeln in der Vorschau zu betrachten, 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. Ein Task, der ohne multi_view_thumbnails: true erstellt wurde, hat 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_urls
    Type
    string[]
    Description

    Download-URLs für die Textur-Referenzbilder, mit denen Sie den Task erstellt haben, in der Reihenfolge, in der Sie sie gesendet haben. Nur vorhanden, wenn Sie den Task mit texture_image_urls erstellt haben.

  • 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, nämlich 2k. Ein standard-Task hat dieses Feld nicht.

  • Name
    progress
    Type
    integer
    Description

    Wie viel des Tasks erledigt ist, als Prozentsatz. Der Wert 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. 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 die Ergebnisse des Tasks ablaufen, 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

    Download-URLs für die vom Task generierten Texturkarten, als Array von Objekten. Es enthält normalerweise ein Objekt. Jedes Objekt hat diese Felder:

    • Name
      base_color
      Type
      string
      Description

      Die Basisfarbkarte.

    • Name
      metallic
      Type
      string
      Description

      Die Metallic-Karte. Nicht enthalten, wenn Sie den Task mit enable_pbr: false erstellt haben.

    • Name
      normal
      Type
      string
      Description

      Die Normal Map. Nicht enthalten, wenn Sie den Task mit enable_pbr: false erstellt haben.

    • Name
      roughness
      Type
      string
      Description

      Die Roughness-Karte. Nicht enthalten, wenn Sie den Task mit enable_pbr: false erstellt haben.

    • Name
      emission
      Type
      string
      Description

      Die Emission-Karte. Nur enthalten, wenn Sie den Task mit all Folgendem 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 Credits, die der Task verbraucht hat. 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.