Text zu 3D API
Generieren Sie 3D-Modelle aus Textprompts in Ihrer eigenen Anwendung.
Text zu 3D funktioniert in zwei Schritten. Erstellen Sie zunächst einen preview-Task (mode: "preview"), um ein 3D-Netz ohne Textur zu generieren, sodass Sie die Form überprüfen können. Senden Sie dann die Task-ID des erfolgreichen Previews an einen refine-Task (mode: "refine"), um das Netz zu texturieren. Beide Schritte verwenden denselben Endpunkt.
Create a Text to 3D preview task
Erstellt eine Text-zu-3D-Preview-Aufgabe, die aus einem Text-prompt ein unstrukturiertes 3D-Netz (nur Geometrie) ohne Textur generiert. Dies ist der erste Schritt des zweistufigen Workflows. Nachdem die Preview erfolgreich war, senden Sie deren Task-ID in einer refine-Aufgabe, um das Netz zu texturieren. Siehe Erstellen einer Text-zu-3D-refine-Aufgabe. Das vollständige Antwortschema finden Sie unter Das Text-zu-3D-Task-Objekt.
Die Aufgabe läuft im Hintergrund. Wie lange eine Aufgabe normalerweise dauert, erfahren Sie unter Verarbeitungszeiten.
Request
# Simple preview with required params only
curl https://api.meshy.ai/openapi/v2/text-to-3d \
-H 'Authorization: Bearer ${YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"mode": "preview",
"prompt": "a monster mask"
}'
# Preview with Ultra 4K geometry, remesh, and A-pose
curl https://api.meshy.ai/openapi/v2/text-to-3d \
-H 'Authorization: Bearer ${YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"mode": "preview",
"prompt": "a futuristic robot warrior",
"ai_model": "meshy-7.1",
"geometry_resolution": "4k",
"should_remesh": true,
"target_polycount": 100000,
"pose_mode": "a-pose",
"target_formats": ["glb"]
}'
Response
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
Parameter
- Name
- mode
- Type
- string
- Erforderlich
- Description
Der Schritt des zweistufigen Workflows. Senden Sie
preview, um eine Preview-Aufgabe zu erstellen.
- Name
- prompt
- Type
- string
- Erforderlich
- Description
Text, der das zu generierende Objekt beschreibt, bis zu 800 Zeichen. Längerer Text gibt
400zurück.
- Name
- model_type
- Type
- string
- Standard standard
- Description
Der Typ des zu generierenden 3D-Netzes.
Verfügbare Werte:
standard: ein 3D-Netz mit hohem Detailgradsmart-topology: ein Smart-Topology-Netz. Wählen Sie das Modell mitai_model(meshy-t2odermeshy-t2.5).
Bei
smart-topologyignoriert Meshyshould_remeshunddecimation_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):meshy-6-litemeshy-6meshy-7.1latest: Meshy 7.1meshy-7(veraltet): Senden Sie stattdessenmeshy-7.1. Es wird am 31. Dezember 2026 eingestellt.
Smart-Topology-Modelle (
model_type: smart-topology):meshy-t2: sauberere topology, nativ getrennte Teile, Dreiecksausgabe und eine Flächenanzahl, die Sie mittarget_polycountfestlegenmeshy-t2.5(Standard): schärferer Detailgrad für Game-Assets, Dreiecksausgabe und eine Flächenanzahl, die Sie mittarget_polycountfestlegen
Unter Modelle finden Sie, welches Modell zu Ihrem Projekt passt, etwa ein Spielcharakter oder ein 3D-Druck.
- Name
- geometry_resolution
- Type
- string
- Standard standard
- Description
Der Geometrie-Generierungsdurchlauf. Gilt nur für Preview-Aufgaben. Ein refine mit diesem Parameter gibt
400zurück.Verfügbare Werte:
standard2k: führt den Ultra-Durchlauf bei 2048³ aus4k: führt den Ultra-Durchlauf bei 4096³ aus, für feineres Oberflächendetail
2kbenötigtmeshy-7.1,latestoder das veraltetemeshy-7.4kbenötigtmeshy-7.1oderlatest. Andere Modelle geben400zurück.
- Name
- ultra_mode
- Type
- boolean
- ⚠ veraltet
- Standard false
- Description
Senden Sie stattdessen
geometry_resolution.ultra_mode: trueentsprichtgeometry_resolution: "2k".
- 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 senden Sie
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 Smart-Topology-Ausgabe besteht ausschließlich aus Dreiecken. Das Senden von
quadmitai_modelmeshy-t2odermeshy-t2.5gibt400zurück.
- Name
- decimation_mode
- Type
- integer
- Description
Adaptive Flächenanzahl, nach Stufe. Wenn Sie dies festlegen, ignoriert Meshy
target_polycount.Verfügbare Werte:
1: ultra2: hoch3: mittel4: niedrig
- Name
- target_polycount
- Type
- integer
- Description
Die anzustrebende Flächenanzahl. Das Ergebnis kann je nach Geometrie vom Zielwert abweichen. Es gilt in zwei separaten Fällen:
- Neuvernetzung: mit
should_remesh: truebei einemstandard-Modell. Meshy vernetzt das Netz neu (dezimiert es) auf etwa diese Anzahl. Wenn Siedecimation_modefestlegen, verwendet Meshy dieses und ignorierttarget_polycount. - Smart Topology: mit
model_type: smart-topologyundai_modelmeshy-t2odermeshy-t2.5. Meshy generiert das Modell direkt mit dieser Flächenanzahl. Es läuft keine Neuvernetzung, und Sie benötigenshould_remeshnicht.
Die folgende Tabelle zeigt den Bereich und den Standardwert für jeden Fall:
Fall Bereich Standard Neuvernetzung 100bis30000030000meshy-t2100bis150004000meshy-t2.5100bis3000015000Ein Wert außerhalb des Bereichs gibt
400zurück.Für ein Low-Poly-Game-Asset verwenden Sie ein Smart-Topology-Modell, anstatt ein Standardmodell neu zu vernetzen. Siehe Modelle.
- Neuvernetzung: mit
- Name
- symmetry_mode
- Type
- string
- ⚠ veraltet
- Standard auto
- Description
Lassen Sie ihn weg. Dieser Parameter wirkt sich nicht auf die Ausgabe aus.
Verfügbare Werte:
off: deaktiviert Symmetrieauto: wendet Symmetrie basierend auf der Eingabegeometrie anon: erzwingt Symmetrie während der Generierung
- 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
Senden Sie stattdessen
pose_mode. Ob das Modell in einer A-Pose oder einer T-Pose generiert werden soll.
- Name
- art_style
- Type
- string
- ⚠ veraltet
- Standard realistic
- Description
Lassen Sie ihn weg. Meshy ignoriert ihn.
- Name
- moderation
- Type
- boolean
- Standard false
- Description
Ob
promptvor der Generierung auf schädliche Inhalte überprüft werden soll. Wenn Meshy schädliche Inhalte erkennt, gibt die Anfrage400zurück, und Meshy erstellt keine Aufgabe.
- Name
- target_formats
- Type
- string[]
- Description
Die zu generierenden Dateiformate. Meshy generiert und gibt nur diese Formate zurück, was die Aufgabe verkürzen kann. Wenn Sie dies weglassen, generiert Meshy jedes Format außer
3mf, das es nur generiert, wenn Sie es anfordern.Verfügbare Werte:
glbobjfbxstlusdz3mf
- Name
- alpha_thumbnail
- Type
- boolean
- Standard false
- Description
Ob zusätzlich eine Preview mit transparentem Hintergrund (RGBA) gerendert werden soll, die beim Abrufen der Aufgabe in
alpha_thumbnail_urlzurückgegeben wird.thumbnail_urländert sich nicht.
- Name
- auto_size
- Type
- boolean
- Standard false
- Description
Ob die reale Höhe des Objekts mit KI-Bildverarbeitung geschätzt und das Modell darauf skaliert werden soll. Meshy setzt den Ursprung an die Unterseite, sofern Sie
origin_atnicht festlegen.
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 Text-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: Ein erforderlicher Parameter, wie
promptodermode, fehlt. - Prompt zu lang:
promptüberschreitet die Zeichenbegrenzung. - Nicht unterstütztes Modell für Ultra:
geometry_resolutionist2koder4k, mit einemai_model, das dies nicht ausführen kann.
Korrigieren Sie die Anfrage, und senden Sie sie dann erneut. Siehe Fehler.
- Fehlender Parameter: Ein erforderlicher Parameter, wie
- 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 dann erneut.
- Kostenloser Plan: Das Erstellen einer Aufgabe erfordert einen kostenpflichtigen Plan. Aktualisieren Sie Ihren Plan in Ihren Abonnement-Einstellungen, und versuchen Sie es dann erneut.
- Name
403 - Forbidden- Description
Die Inhaltsmoderation hat den prompt oder ein Eingabebild blockiert. Ändern Sie die Eingabe, und versuchen Sie es dann erneut.
- Name
429 - Too Many Requests- Description
Sie haben Ihre Ratenbegrenzung überschritten. Warten Sie, und versuchen Sie es dann erneut. Siehe Ratenbegrenzungen.
Einen Text-zu-3D-Refine-Task erstellen
Erstellt einen Text-zu-3D-Refine-Task, der das Netz eines abgeschlossenen Vorschau-Tasks texturiert. Senden Sie die ID eines erfolgreichen Vorschau-Tasks als preview_task_id. Siehe Einen Text-zu-3D-Vorschau-Task erstellen. Dies ist der zweite Schritt des zweistufigen Workflows.
Der Task läuft im Hintergrund. Wie lange ein Task normalerweise dauert, erfahren Sie unter Verarbeitungszeiten.
Request
# Basic refine task
curl https://api.meshy.ai/openapi/v2/text-to-3d \
-H 'Authorization: Bearer ${YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"mode": "refine",
"preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"enable_pbr": true
}'
# Refine with auto-size and GLB format
curl https://api.meshy.ai/openapi/v2/text-to-3d \
-H 'Authorization: Bearer ${YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"mode": "refine",
"preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"target_formats": ["glb"],
"auto_size": true
}'
# Refine with Meshy N1 from the preview's stored reference image
curl https://api.meshy.ai/openapi/v2/text-to-3d \
-H 'Authorization: Bearer ${YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"mode": "refine",
"preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"ai_model": "meshy-n1"
}'
Response
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
Parameter
- Name
- mode
- Type
- string
- Erforderlich
- Description
Der Schritt des zweistufigen Workflows. Senden Sie
refine, um einen Refine-Task zu erstellen.
- Name
- preview_task_id
- Type
- string
- Erforderlich
- Description
Die ID des zu texturierenden Vorschau-Tasks. Der Vorschau-Task muss den Status
SUCCEEDEDhaben.
- Name
- enable_pbr
- Type
- boolean
- Standard false
- Description
Ob zusätzlich zur Grundfarbe auch PBR-Texturen (Metallic, Roughness und Normal) erzeugt werden sollen.
Mit
ai_modelmeshy-6erzeugt Meshy außerdem eine Emission-Map, außer beitexture_resolution: 8k.meshy-6-lite,meshy-7undlatesterzeugen keine Emission-Map. Ebenso wenig ein Refine einesmeshy-t2- odermeshy-t2.5-Vorschau-Tasks, derai_modelnicht setzt. Mitai_model: meshy-n1führttruezu400.
- Name
- texture_resolution
- Type
- string
- Standard 2k
- Description
Die Auflösung der Grundfarbtextur. Gilt nur für Refine-Tasks. Eine Vorschau mit diesem Parameter gibt
400zurück.Verfügbare Werte:
2k: 2048×20484k: 4096×40968k: 8192×8192
Höhere Auflösungen erfassen mehr Oberflächendetails.
4kund8kbenötigenai_modelmeshy-6,meshy-7oderlatest. Mitmeshy-n1geben sie400zurück. Bei8kerzeugt Meshy keine Emission-Map.
- Name
- hd_texture
- Type
- boolean
- ⚠ veraltet
- Standard false
- Description
Senden 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 Texturierung steuert, bis zu 800 Zeichen. Längerer Text gibt
400zurück. Senden Sie entwedertexture_promptodertexture_image_url, nicht beides. Wenn Sie beides senden, verwendet Meshytexture_prompt. Mitai_model: meshy-n1führt das Senden zu400.
- Name
- texture_image_url
- Type
- string
- Description
Ein 2D-Bild, das die Texturierung steuert, als öffentliche URL oder als base64-codierte Data URI, z. B.
data:image/jpeg;base64,<Ihre base64-codierten Bilddaten>.Das Bild muss eine
.jpg-,.jpeg-,.png- oder.webp-Datei mit höchstens 20 MB sein, mindestens 32 Pixel pro Seite und höchstens 178.956.970 Pixel (Breite × Höhe) haben.Mit
ai_model: meshy-n1texturiert Meshy anhand dieses Bildes als Vorderansicht.Die Texturierung anhand eines Bildes funktioniert möglicherweise nicht gut, wenn sich die Form im Bild stark vom Modell unterscheidet.
- Name
- ai_model
- Type
- string
- Standard inherited from the preview task
- Description
Das KI-Modell, das das Netz texturiert. Das Netz stammt aus der Vorschau, daher wählt
ai_modelbei einem Refine nur das Texturmodell aus.Verfügbare Werte:
meshy-7: Meshy 7latest: das neueste Texturmodell, derzeit Meshy 7meshy-6: Meshy 6meshy-6-lite: Meshy 6 Litemeshy-n1: eine 2K-Grundfarbtextur nur aus einem Referenzbild. Kein Text-Prompt, keine PBR-Texturen, kein 4K oder 8K.
Die oben genannten Werte sind Texturmodelle. Lassen Sie den Parameter weg, um mit dem Modell zu texturieren, das zur Vorschau passt. Senden Sie einen Wert, um ihn zu überschreiben.
Mit
meshy-n1texturiert Meshy austexture_image_url. Ohne diesen Parameter verwendet Meshy das Referenzbild, das einmeshy-7.1- oderlatest-Vorschau-Task gespeichert hat. Jede andere Vorschau gibt400zurück, es sei denn, Sie sendentexture_image_url. Die Vorschau darf höchstens 7.999.999 Dreiecke haben. Eine auf Quads remeshte Vorschau gibt400zurück.
- Name
- moderation
- Type
- boolean
- Standard false
- Description
Ob
texture_promptundtexture_image_urlvor der Generierung auf schädliche Inhalte geprüft werden sollen. Wenn Meshy schädliche Inhalte erkennt, gibt die Anfrage400zurück und Meshy erstellt keinen Task.
- Name
- remove_lighting
- Type
- boolean
- Standard true
- Description
Ob Glanzlichter und Schatten aus der Grundfarbtextur entfernt werden sollen. Das sauberere Ergebnis funktioniert besser bei individueller Beleuchtung.
Wirkt sich nur aus, wenn
ai_modelmeshy-6ist.meshy-7undlatestakzeptieren den Parameter, ignorieren ihn jedoch, ebenso ein Refine einesmeshy-t2- odermeshy-t2.5-Vorschau-Tasks, derai_modelnicht setzt. Das Senden mitmeshy-6-litegibt400zurück. Mitmeshy-n1führttruezu400.
- Name
- target_formats
- Type
- string[]
- Description
Die zu erzeugenden Dateiformate. Meshy erzeugt und liefert nur diese Formate, was den Task verkürzen kann. Wenn Sie den Parameter weglassen, erzeugt Meshy jedes Format außer
3mf, das nur erzeugt wird, wenn Sie es anfordern.Verfügbare Werte:
glbobjfbxstlusdz3mf
- Name
- alpha_thumbnail
- Type
- boolean
- Standard false
- Description
Ob zusätzlich eine Vorschau mit transparentem Hintergrund (RGBA) gerendert werden soll, die beim Abrufen des Tasks in
alpha_thumbnail_urlzurückgegeben wird.thumbnail_urländert sich nicht.
- Name
- auto_size
- Type
- boolean
- Standard false
- Description
Ob die reale Höhe des Objekts mittels KI-Bildverständnis geschätzt und das Modell darauf skaliert werden soll. Meshy setzt den Ursprung standardmäßig unten, sofern Sie
origin_atnicht festlegen.
auto_size = true- Name
- origin_at
- Type
- string
- Standard bottom
- Description
Wo der Ursprung des Modells platziert werden soll,
bottomodercenter.
Rückgabewerte
Das Feld result der Antwort enthält die ID des neuen Text-zu-3D-Tasks.
Fehlerfälle
- Name
400 - Bad Request- Description
Die Anfrage kann nicht ausgeführt werden. Die Fehlermeldung gibt an, welches Problem gefunden wurde. Zum Beispiel:
- Invalid task ID:
preview_task_idist ungültig oder entspricht keinem Ihrer Vorschau-Tasks. - Task not ready: Der Vorschau-Task war noch nicht erfolgreich.
- Model mismatch: Das KI-Modell des Vorschau-Tasks funktioniert nicht mit dem angeforderten Refine-Modell.
- Unsupported model for remove_lighting:
remove_lightingwurde mitai_model: "meshy-6-lite"gesendet. - No reference image for Meshy N1:
ai_model: meshy-n1wurde ohnetexture_image_urlgesendet, und die Vorschau hat kein Referenzbild, das Meshy N1 verwenden kann. Senden Sietexture_image_url. - Quad preview for Meshy N1:
ai_model: meshy-n1wurde für eine auf Quads remeshte Vorschau gesendet. Führen Sie den Refine mit einem anderenai_modeldurch. - Too many triangles for Meshy N1: Mit
ai_model: meshy-n1hat die Vorschau mehr als 7.999.999 Dreiecke. Führen Sie den Refine mit einem anderenai_modeldurch. - Unsupported option for Meshy N1:
ai_model: meshy-n1wurde mit einer dieser Optionen gesendet:texture_promptenable_pbr: truetexture_resolutionvon4koder8khd_texture: trueohnetexture_resolutionremove_lighting: true
Korrigieren Sie die Anfrage und senden Sie sie erneut. Siehe Fehler.
- Invalid task ID:
- 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:
- Insufficient credits: Das Konto hat nicht genügend Credits für diesen Task, oder das Konto hat ein Credit-Limit erreicht. Prüfen Sie Ihr Credit-Guthaben und versuchen Sie es dann erneut.
- Free plan: Das Erstellen eines Tasks erfordert einen kostenpflichtigen Plan. Upgraden Sie Ihren Plan in Ihren Abonnement-Einstellungen und versuchen Sie es dann erneut.
- Name
403 - Forbidden- Description
Die Inhaltsmoderation hat den Prompt oder ein Eingabebild blockiert. Ändern Sie die Eingabe und versuchen Sie es dann erneut.
- Name
429 - Too Many Requests- Description
Sie haben Ihre Ratenbegrenzung überschritten. Warten Sie und versuchen Sie es dann erneut. Siehe Ratenbegrenzungen.
Einen Text-zu-3D-Task abrufen
Gibt einen Text-zu-3D-Task anhand seiner ID zurück. Dies funktioniert sowohl für Preview- als auch für Refine-Tasks.
Request
curl https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"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=***",
"mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?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=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"prompt": "a monster mask",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20
}
Parameter
- Name
- id
- Type
- path
- Description
Die Task-ID aus der Antwort der Erstellung.
Rückgabe
Beispiele
Die folgende Tabelle zeigt ein Beispielmodell für jeden mode.
| Mode | Beispielmodell |
|---|---|
| Preview | ![]() |
| Refine | ![]() |
Eine Text-zu-3D-Aufgabe löschen
Löscht eine Text-zu-3D-Aufgabe dauerhaft, einschließlich ihrer Modelle und Daten. Eine Löschung kann nicht rückgängig gemacht werden.
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v2/text-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 zurück, 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 Credits für eine Aufgabe, die
bereits gestartet wurde. Das Löschen würde Sie daher 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 mit einem endgültigen Status (SUCCEEDED, FAILED oder CANCELED)
führt zu keiner Erstattung der Credits.
Rückgabe
200 OK, wenn die Aufgabe gelöscht wurde, oder 409 Conflict, wenn sich die Aufgabe
im Status IN_PROGRESS befindet.
List Text to 3D tasks
Gibt eine Liste Ihrer Text-zu-3D-Aufgaben zurück.
Request
curl https://api.meshy.ai/openapi/v2/text-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"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=***",
"mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"prompt": "a monster mask",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20
}
]
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 Text zu 3D Task-Objekten.
Einen Text-zu-3D-Task streamen
Streamt die Aktualisierungen eines Text-zu-3D-Tasks als Server-Sent Events (SSE).
Request
curl -N https://api.meshy.ai/openapi/v2/text-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",
"progress": 50,
"status": "IN_PROGRESS"
}
event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
},
"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": 20
}
Parameter
- Name
- id
- Type
- path
- Description
Die Task-ID aus der Antwort der Erstellung.
Rückgabe
Ein Stream von Text-zu-3D-Task-Objekten als Server-Sent Events.
Jedes Event enthält das vollständige Task-Objekt, in derselben Form, die der Get-Endpunkt zurückgibt. Solange der Task PENDING oder IN_PROGRESS ist, besitzen seine Ergebnisfelder noch keine Werte.
Das Text zu 3D-Taskobjekt
Ein Text zu 3D-Taskobjekt beschreibt einen Task, der ein 3D-Modell aus einem Text-prompt generiert. Es enthält den Status, den progress und die Modelldateien, wenn der Task erfolgreich ist. Text zu 3D hat zwei Phasen, preview und refine. Ein preview-Task generiert ein 3D-Modell, das nur aus einem Netz besteht, und ein refine-Task generiert aus dem Ergebnis des Preview ein texturiertes 3D-Modell.
Eigenschaften
Example Text to 3D Task Object
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"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=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
"mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
"stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
},
"prompt": "a monster mask",
"texture_prompt": "green slimy skin with scales and warts",
"texture_image_url": "",
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"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": 20
}
- Name
- id
- Type
- string
- Description
Die Task-ID. Behandeln Sie sie als undurchsichtige Zeichenfolge und verlassen Sie sich nicht auf ihr Format.
- Name
- type
- Type
- string
- Description
Der Task-Typ,
text-to-3d-previewfür einen preview-Task odertext-to-3d-refinefür einen refine-Task.
- 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, anstatt einer leeren Zeichenfolge.
- Name
glb- Type
- string
- Description
Die GLB-Datei.
- Name
fbx- Type
- string
- Description
Die FBX-Datei.
- Name
usdz- Type
- string
- Description
Die USDZ-Datei.
- Name
obj- Type
- string
- Description
Die OBJ-Datei.
- Name
mtl- Type
- string
- Description
Die MTL-Datei.
- Name
stl- Type
- string
- Description
Die STL-Datei.
- Name
3mf- Type
- string
- Description
Die 3MF-Datei. Nur vorhanden, wenn
target_formats3mfenthält.
- Name
- prompt
- Type
- string
- Description
Der
prompt, den Sie zum Erstellen des Tasks gesendet haben, unverändert.
- Name
- texture_prompt
- Type
- string
- Description
Der Text-prompt, den Sie gesendet haben, um die Texturierung in der refine-Phase zu steuern.
- Name
- ultra_mode
- Type
- boolean
- ⚠ veraltet
- Description
Verwenden Sie stattdessen
geometry_resolution.
- Name
- geometry_resolution
- Type
- string
- Description
Die Ultra-Stufe, mit der der preview-Task ausgeführt wurde,
2koder4k. Das Feld fehlt beistandard.
- Name
- texture_image_url
- Type
- string
- Description
Download-URL für das Bild, das Sie zur Steuerung der Texturierung gesendet haben.
- Name
- thumbnail_url
- Type
- string
- Description
Download-URL für eine Miniaturansicht des 3D-Modells.
- 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
- progress
- Type
- integer
- Description
Wie viel des Tasks erledigt ist, in Prozent. Der Wert ist
0, bis der Task startet, 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
- 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
Download-URLs für die generierten Texturmaps, als Array von Objekten. Es enthält normalerweise ein Objekt. Jedes Objekt hat diese Felder:
- Name
base_color- Type
- string
- Description
Die Base-Color-Map.
- Name
metallic- Type
- string
- Description
Die Metallic-Map. Fehlt, wenn Sie den Task mit
enable_pbr: falseerstellt haben.
- Name
normal- Type
- string
- Description
Die Normal Map. Fehlt, wenn Sie den Task mit
enable_pbr: falseerstellt haben.
- Name
roughness- Type
- string
- Description
Die Roughness-Map. Fehlt, wenn Sie den Task mit
enable_pbr: falseerstellt haben.
- Name
emission- Type
- string
- Description
Die Emission-Map. Fehlt in jedem dieser Fälle:
- Sie haben den Task mit
enable_pbr: falseerstellt. ai_modelistmeshy-6-lite,meshy-7,meshy-7.1oderlatest.texture_resolutionist8k.- Der Task verfeinert eine
meshy-t2- odermeshy-t2.5-Preview, ohneai_modelfestzulegen.
- Sie haben den Task mit
- 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, es sei denn, der Status istFAILED. Siehe Fehler.
- Name
- consumed_credits
- Type
- integer
- Description
Die Anzahl der Credits, die der Task verbraucht hat. Vorhanden, wenn der Status
PENDING,IN_PROGRESSoderSUCCEEDEDist. Bei einemFAILED-Task ist der Wert0, da Meshy die Credits erstattet, wenn ein Task fehlschlägt.

