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.
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
# 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_urlsenden. 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 StatusSUCCEEDEDhaben und genau ein Bild erzeugt haben.
- Name
- image_url
- Type
- string
- Erforderlich
- Description
Erforderlich, sofern Sie nicht
input_task_idsenden. 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 Meshyinput_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 Detailgradsmart-topology: ein Netz aus einem Smart-Topology-Modell, das Sie mitai_modelauswählen (meshy-t2odermeshy-t2.5)
Bei
smart-topologyignoriert Meshyshould_remesh,save_pre_remeshed_modelunddecimation_modeund akzeptiert nurtopology: 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_typeab.Standardmodelle (
model_type: standard):latest: Meshy 7.1meshy-7.1meshy-6meshy-6-litemeshy-7(veraltet): verwenden Sie stattdessenmeshy-7.1. Es wird am 31. Dezember 2026 eingestellt.
Smart-Topology-Modelle (
model_type: smart-topology) erzeugen Dreiecke, mit einer Flächenanzahl, die Sie übertarget_polycountfestlegen können:meshy-t2: sauberere topology und nativ getrennte Teilemeshy-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:
standard2k: führt den Ultra-Durchgang bei 2048³ aus4k: führt den Ultra-Durchgang bei 4096³ aus, für das meiste Oberflächendetail
2kerfordertmeshy-7.1,latestoder das veraltetemeshy-7.4kerfordertmeshy-7.1oderlatest.
- Name
- ultra_mode
- Type
- boolean
- ⚠ veraltet
- Standard false
- Description
Verwenden Sie stattdessen
geometry_resolution.ultra_mode: trueentsprichtgeometry_resolution: "2k".
- Name
- should_texture
- Type
- boolean
- Standard true
- Description
Ob Texturen generiert werden sollen.
trueliefert ein texturiertes Modell, undfalseüberspringt das Texturieren und liefert ein untexturiertes Netz.
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_modelzu verwenden. Es ändert nicht die Credit-Kosten.Verfügbare Werte:
meshy-7: Meshy 7, mit PBR-Texturen und Texturen bis zu 8Kmeshy-n1: Meshy N1, eine 2K-Basisfarbtextur nur aus Referenzbildernmeshy-6-lite: Meshy 6 Lite, eine 2K-Textur zu den geringsten Kostenmeshy-6: Meshy 6, nur als Standard fürai_model: meshy-6
Jedes
ai_modelakzeptiertmeshy-7,meshy-n1undmeshy-6-lite. Eine Option, die das gewählte Texturmodell nicht unterstützt, liefert400. Beimeshy-n1schlägt die Aufgabe bei einem generierten Modell mit über 7.999.999 Dreiecken fehl, und Meshy erstattet dessen Credits. Beishould_texture: falseignoriert Meshytexture_model, aber ein unbekannter Wert liefert trotzdem400.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.
trueerfordertshould_texture: trueund liefert400beishould_texture: false. Beitexture_model: meshy-n1lieferttrueden Fehler400.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×20484k: 4096×40968k: 8192×8192
4kund8kerfordern das Texturmodell Meshy 7 oder Meshy 6 und liefern bei den anderen400. Bei8kerzeugt Meshy keine Emission Map.
- Name
- hd_texture
- Type
- boolean
- ⚠ veraltet
- Standard false
- Description
Verwenden Sie stattdessen
texture_resolution.hd_texture: trueentsprichttexture_resolution: "4k". Wenn Sie beides senden, verwendet Meshytexture_resolution.
- Name
- texture_prompt
- Type
- string
- Description
Text, der die Textur leitet, bis zu 800 Zeichen. Längerer Text liefert
400. Beitexture_model: meshy-n1liefert das Senden400.
- 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_promptundtexture_image_url. Wenn Sie beides senden, verwendet Meshytexture_prompt. Zu den Credit-Kosten des Texturierens siehe Preise.Bei
texture_model: meshy-n1texturiert Meshy anhand dieses Bildes als Vorderansicht, oder anhand des Eingabebildes, wenn Sie es weglassen.Das Texturieren anhand eines Bildes funktioniert möglicherweise nicht gut, wenn die Form des Bildes stark von der Geometrie des 3D-Modells abweicht.
- Name
- should_remesh
- Type
- boolean
- Standard true (meshy-6-lite), false (other models)
- Description
Ob die Neuvernetzungsphase ausgeführt werden soll. Für das qualitativ hochwertigste 3D-Modell setzen Sie diesen Wert auf
false.
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 Netztriangle: ein dezimiertes Dreiecksnetz
Die Ausgabe von Smart Topology besteht ausschließlich aus Dreiecken, daher liefert
quadbeimeshy-t2odermeshy-t2.5den Fehler400. Beitexture_model: meshy-n1liefertquad400, wenn das Modell neu vernetzt wird, wasmeshy-6-litestandardmäß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: ultra2: hoch3: mittel4: 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_remeshbei einemstandard-Modelltrueist, dezimiert Meshy das Netz auf etwa diese Anzahl. Wenn Siedecimation_modefestlegen, verwendet Meshy diesen und ignorierttarget_polycount. - Smart Topology: Wenn
model_typesmart-topologyist undai_modelmeshy-t2odermeshy-t2.5ist, generiert Meshy das Modell mit dieser Flächenanzahl. Es läuft keine Neuvernetzung, und Sie benötigenshould_remeshnicht.
Bereich und Standardwert hängen vom Fall ab:
Fall Bereich Standard Neuvernetzung 100bis30000030000meshy-t2100bis150004000meshy-t2.5100bis3000015000Ein 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.
- Neuvernetzung: Wenn
- 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 Symmetrieauto: Symmetrie, gewählt anhand der Eingabegeometrieon: erzwungene Symmetrie
- Name
- pose_mode
- Type
- string
- Description
Die Pose für ein Charaktermodell,
a-poseodert-pose. Um keine Pose zu erhalten, lassen Siepose_modeundis_a_t_poseweg.
- 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
organicundhard. Jeder andere Wert liefert400.
- Name
- image_enhancement
- Type
- boolean
- Standard true
- Description
Ob das Eingabebild vor der Generierung optimiert werden soll.
falsebehält das exakte Aussehen des Eingabebildes bei, ohne Stilverarbeitung.Dies funktioniert nur mit
meshy-6,meshy-7.1oderlatest. Beimeshy-6-liteodermodel_type: smart-topologyliefert es400.
- 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
trueden Fehler400. Beimodel_type: smart-topology, oder beiai_model: meshy-6-liteund dessen Standard-Texturmodell, liefert das Senden400.
- Name
- moderation
- Type
- boolean
- Standard false
- Description
Ob diese Eingaben vor der Generierung auf schädliche Inhalte geprüft werden sollen:
image_urltexture_image_urltexture_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:
glbobjfbxstlusdz3mf
- 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_atfest.
- 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_urlzurü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_urlszurückgegeben werden.thumbnail_urländert sich nicht und zeigt weiterhin die Vorderansicht. Dies verlängert die Aufgabe um etwa 5 Sekunden.
auto_size = true- Name
- origin_at
- Type
- string
- Standard bottom
- Description
Wo der Ursprung des Modells platziert werden soll,
bottomodercenter.
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_urlnochinput_task_idwurde gesendet. - Ungültige Eingabeaufgabe:
input_task_idist keineSUCCEEDED-Text-zu-Bild- oder Bild-zu-Bild-Aufgabe, die genau ein Bild erzeugt hat. - Ungültiges Bildformat: Das Bild unter
image_urlist keine JPG-, JPEG-, PNG- oder WebP-Datei. - Unerreichbare URL: Meshy kann das Bild unter
image_urlnicht herunterladen, weil die URL404liefert oder eine Zeitüberschreitung auftritt. - Bild zu groß: Das Bild unter
image_urlodertexture_image_urlist größer als 20 MB. - Ungültige Bildgröße: Das Bild unter
image_urlodertexture_image_urlhat 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_pbristtrue, undshould_textureistfalse. - Nicht unterstütztes Modell für Ultra:
geometry_resolutionist2koder4k, mit einemai_model, das dies nicht ausführen kann. - Nicht unterstütztes Modell für Bildoptionen: einer der folgenden Fälle:
image_enhancementwurde mitai_model: "meshy-6-lite"odermodel_type: "smart-topology"gesendet.remove_lightingwurde mitmodel_type: "smart-topology"gesendet, oder mitai_model: "meshy-6-lite"und dessen Standard-Texturmodell.
- Ungültiges Texturmodell:
texture_modelist keiner der verfügbaren Werte. - Texturmodell nicht verfügbar:
texture_modelistmeshy-6mit einemai_modelungleichmeshy-6. Senden Siemeshy-7,meshy-n1odermeshy-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: truemitmeshy-n1oder eine4k-Textur mitmeshy-6-lite. Siehe Modelle.
Korrigieren Sie die Anfrage und senden Sie sie erneut. Siehe Fehler.
- Fehlender Parameter: Weder
- 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_idstimmt 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.
Ein Bild-zu-3D-Task abrufen
Gibt einen Bild-zu-3D-Task anhand seiner ID zurück.
Request
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
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
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.
Image to 3D-Aufgaben auflisten
Gibt eine Liste Ihrer Bild zu 3D-Aufgaben zurück.
Request
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 gibt400zurü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.
Einen Image-to-3D-Task streamen
Streamt die Updates eines Bild-zu-3D-Tasks als Server-Sent Events (SSE).
Request
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_formats3mfenthä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: trueals auchsave_pre_remeshed_model: trueerstellt haben.
- Name
- thumbnail_url
- Type
- string
- Description
Download-URL für ein Vorschaubild des 3D-Modells. Wenn
thumbnail_urlsvorhanden ist, ist es dasselbe Bild wiethumbnail_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_urlmit transparentem Hintergrund (RGBA). Nur vorhanden, wenn Sie den Task mitalpha_thumbnail: trueerstellt 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: trueerstellt haben und der TaskSUCCEEDEDerreicht hat. Tasks, die ohnemulti_view_thumbnails: trueerstellt 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,
2koder4k. Einstandard-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, und100, 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,FAILEDoderCANCELED.
- 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: falseerstellt haben.
- Name
normal- Type
- string
- Description
Download-URL für die Normal Map. Das Feld fehlt, wenn Sie den Task mit
enable_pbr: falseerstellt haben.
- Name
roughness- Type
- string
- Description
Download-URL für die Rauheitskarte. Das Feld fehlt, wenn Sie den Task mit
enable_pbr: falseerstellt 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-Texturmodellenable_pbr: true- einer
texture_resolutionvon2koder4k
- 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
PENDINGist.
- Name
- task_error
- Type
- object
- Description
Die Fehlerdetails, wenn der Task fehlschlägt. Der Wert ist
null, außer wenn der StatusFAILEDist. Siehe Fehler.
- Name
- consumed_credits
- Type
- integer
- Description
Die Anzahl der vom Task verbrauchten Credits. Vorhanden, wenn der Status
PENDING,IN_PROGRESSoderSUCCEEDEDist. Bei einemFAILED-Task ist er0, da Meshy die Credits erstattet, wenn ein Task fehlschlägt.