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.

POST/openapi/v2/text-to-3d

Create a Text to 3D preview task

Erstellt eine Text zu 3D Preview-Aufgabe, die aus einem Text-prompt ein untexturiertes 3D-Netz (nur Geometrie) 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 Create a Text to 3D refine task. Das vollständige Antwortschema finden Sie unter The Text to 3D task object.

Die Aufgabe läuft im Hintergrund. Wie lange eine Aufgabe üblicherweise dauert, erfahren Sie unter Processing times.

Request

POST

/openapi/v2/text-to-3d

# 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 führt zu 400.
Name
model_type
Type
string
Standard standard
Description
Der Typ des zu generierenden 3D-Netzes.
Verfügbare Werte:
- standard: ein hochdetailliertes 3D-Netz
- smart-topology: ein Smart-Topology-Netz. Wählen Sie das Modell mit ai_model (meshy-t2 oder meshy-t2.5).
Bei smart-topology ignoriert Meshy should_remesh und decimation_mode und akzeptiert nur topology: triangle.
Name
ai_model
Type
string
Standard latest
Description
Das KI-Modell, das das 3D-Modell generiert. Die verfügbaren Werte hängen von model_type ab.
Standard-Modelle (model_type: standard):
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest: Meshy 7.1
- meshy-7 (veraltet): senden Sie stattdessen meshy-7.1
Smart-Topology-Modelle (model_type: smart-topology):
- meshy-t2: sauberere topology, nativ getrennte Teile, Dreiecks-Ausgabe und eine Flächenzahl, die Sie mit target_polycount festlegen
- meshy-t2.5 (Standard): schärfere Details für Game-Assets, Dreiecks-Ausgabe und eine Flächenzahl, die Sie mit target_polycount festlegen
Name
geometry_resolution
Type
string
Standard standard
Description
Der Geometrie-Generierungsdurchlauf. Gilt nur für Preview-Aufgaben. Ein refine mit diesem Parameter führt zu 400.
Verfügbare Werte:
- standard
- 2k: führt den Ultra-Durchlauf mit 2048³ aus
- 4k: führt den Ultra-Durchlauf mit 4096³ aus, für feinere Oberflächendetails
2k benötigt meshy-7.1, latest oder das veraltete meshy-7. 4k benötigt meshy-7.1 oder latest. Andere Modelle führen zu 400.
Name
ultra_mode
Type
boolean
⚠ veraltet
Standard false
Description
Senden Sie stattdessen geometry_resolution. ultra_mode: true entspricht geometry_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.

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
Smart-Topology-Ausgabe besteht ausschließlich aus Dreiecken. Das Senden von quad mit ai_model meshy-t2 oder meshy-t2.5 führt zu 400.
Name
decimation_mode
Type
integer
Description
Adaptive Flächenzahl, nach Stufe. Wenn Sie dies festlegen, ignoriert Meshy target_polycount.
Verfügbare Werte:
- 1: ultra
- 2: hoch
- 3: mittel
- 4: niedrig

Name
target_polycount
Type
integer
Description
Die Anzahl der anzustrebenden Flächen. Das Ergebnis kann je nach Geometrie vom Zielwert abweichen. Es gilt in zwei getrennten Fällen:
- Neuvernetzung: mit should_remesh: true bei einem standard-Modell. Meshy vernetzt das Netz neu (dezimiert) auf etwa diese Zahl. Wenn Sie decimation_mode festlegen, verwendet Meshy diesen Wert und ignoriert target_polycount.
- Smart Topology: mit model_type: smart-topology und ai_model meshy-t2 oder meshy-t2.5. Meshy generiert das Modell direkt mit dieser Flächenzahl. Es läuft keine Neuvernetzung, und Sie benötigen should_remesh nicht.
Die folgende Tabelle zeigt den Bereich und den Standardwert für jeden Fall:
Fall Bereich Standard
Neuvernetzung 100 bis 300000 30000
meshy-t2 100 bis 15000 4000
meshy-t2.5 100 bis 30000 15000
Ein Wert außerhalb des Bereichs führt zu 400.

Fall	Bereich	Standard
Neuvernetzung	`100` bis `300000`	`30000`
`meshy-t2`	`100` bis `15000`	`4000`
`meshy-t2.5`	`100` bis `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ veraltet
Standard auto
Description
Lassen Sie diesen Parameter weg. Er beeinflusst die Ausgabe nicht.
Verfügbare Werte:
- off: deaktiviert Symmetrie
- auto: wendet Symmetrie basierend auf der Eingabegeometrie an
- on: erzwingt Symmetrie während der Generierung
Name
pose_mode
Type
string
Standard ""
Description
Die Pose des generierten Modells.
Verfügbare Werte:
- a-pose: eine A-Pose
- t-pose: eine T-Pose
- "" (leerer String): keine bestimmte Pose
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 diesen Parameter weg. Meshy ignoriert ihn.
Name
moderation
Type
boolean
Standard false
Description
Ob prompt vor der Generierung auf schädliche Inhalte geprüft werden soll. Wenn Meshy schädliche Inhalte erkennt, führt die Anfrage zu 400, und Meshy erstellt keine Aufgabe.
Name
target_formats
Type
string[]
Description
Die zu generierenden Dateiformate. Meshy generiert und liefert nur diese Formate, was die Aufgabe verkürzen kann. Wenn Sie diesen Parameter weglassen, generiert Meshy jedes Format außer 3mf, das nur auf Anfrage generiert wird.
Verfügbare Werte:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
Standard false
Description
Ob zusätzlich eine Vorschau mit transparentem Hintergrund (RGBA) gerendert werden soll, die in alpha_thumbnail_url zurückgegeben wird, wenn Sie die Aufgabe abrufen. thumbnail_url ändert sich dadurch nicht.
Name
auto_size
Type
boolean
Standard false
Description
Ob die reale Höhe des Objekts per KI-Vision geschätzt und das Modell entsprechend in der Größe angepasst werden soll. Meshy setzt den Ursprung standardmäßig unten, sofern Sie nicht origin_at festlegen.

Gilt nur wenn auto_size = true

Name
origin_at
Type
string
Standard bottom
Description
Wo der Ursprung des Modells platziert werden soll, bottom oder center.

Rückgabewerte

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

Fehlerursachen

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 prompt oder mode, fehlt.
- Prompt zu lang: prompt überschreitet das Zeichenlimit.
- Nicht unterstütztes Modell für Ultra: geometry_resolution ist 2k oder 4k, mit einem ai_model, das dies nicht ausführen kann.
Korrigieren Sie die Anfrage und senden Sie sie erneut. Siehe Errors.
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
429 - Too Many Requests
Description
Sie haben Ihre Ratenbegrenzung überschritten. Warten Sie und versuchen Sie es erneut. Siehe Rate limits.

POST/openapi/v2/text-to-3d

Create a Text to 3D refine task

Erstellt einen Text zu 3D refine-Task, der das Netz eines abgeschlossenen preview-Tasks texturiert. Sende die ID eines erfolgreichen preview-Tasks als preview_task_id. Siehe Einen Text zu 3D preview-Task erstellen. Dies ist der zweite Schritt des zweistufigen Workflows.

Der Task läuft im Hintergrund. Wie lange ein Task üblicherweise dauert, erfährst du unter Verarbeitungszeiten.

Request

POST

/openapi/v2/text-to-3d

# 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
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Parameter

Name
mode
Type
string
Erforderlich
Description
Der Schritt des zweistufigen Workflows. Sende refine, um einen refine-Task zu erstellen.
Name
preview_task_id
Type
string
Erforderlich
Description
Die ID des zu texturierenden preview-Tasks. Der preview-Task muss den Status SUCCEEDED haben.
Name
enable_pbr
Type
boolean
Standard false
Description
Ob zusätzlich zur Basisfarbe auch PBR-Texturen (Metallic, Roughness und Normal) generiert werden sollen.
Mit ai_model meshy-6 generiert Meshy zudem eine Emission-Map, außer bei texture_resolution: 8k. meshy-6-lite, meshy-7, meshy-7.1 und latest generieren keine Emission-Map. Ebenso wenig ein refine eines meshy-t2- oder meshy-t2.5-preview, bei dem ai_model nicht gesetzt ist.
Name
texture_resolution
Type
string
Standard 2k
Description
Die Auflösung der Basisfarbtextur. Gilt nur für refine-Tasks. Ein preview mit diesem Parameter liefert 400 zurück.
Verfügbare Werte:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
Höhere Auflösungen erfassen mehr Oberflächendetails. 4k und 8k benötigen ai_model meshy-6, meshy-7.1 oder latest. Bei 8k generiert Meshy keine Emission-Map.
Name
hd_texture
Type
boolean
⚠ veraltet
Standard false
Description
Sende stattdessen texture_resolution. hd_texture: true entspricht texture_resolution: "4k". Wenn du beide sendest, verwendet Meshy texture_resolution.
Name
texture_prompt
Type
string
Description
Text, der die Texturierung steuert, bis zu 800 Zeichen. Längerer Text liefert 400 zurück. Sende texture_prompt oder texture_image_url, nicht beides. Wenn du beide sendest, verwendet Meshy texture_prompt.
Name
texture_image_url
Type
string
Description
Ein 2D-Bild, das die Texturierung steuert, als öffentliche URL oder als base64-kodierte Data URI, z. B. data:image/jpeg;base64,<deine base64-kodierten Bilddaten>.
Das Bild muss eine .jpg-, .jpeg-, .png- oder .webp-Datei mit höchstens 20 MB sein.
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.
Verfügbare Werte:
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest: Meshy 7.1
- meshy-7 (veraltet): sende stattdessen meshy-7.1
Lass ihn weg, um das Modell des preview-Tasks zu verwenden, sodass preview und dessen refine durchgängig auf demselben Modell laufen. Sende einen Wert, um ihn zu überschreiben. Ein explizites latest wird genauso aufgelöst wie beim preview-Task, sodass ein latest-preview und sein latest-refine immer dasselbe Texturmodell verwenden.
Name
moderation
Type
boolean
Standard false
Description
Ob texture_prompt und texture_image_url vor der Generierung auf schädliche Inhalte geprüft werden sollen. Erkennt Meshy schädliche Inhalte, liefert die Anfrage 400 zurück und Meshy erstellt keinen Task.
Name
remove_lighting
Type
boolean
Standard true
Description
Ob Glanzlichter und Schatten aus der Basisfarbtextur entfernt werden sollen. Das sauberere Ergebnis funktioniert besser bei individueller Beleuchtung.
Wirkt sich nur aus, wenn ai_model meshy-6 ist. meshy-7.1 und latest akzeptieren den Parameter und ignorieren ihn, ebenso ein refine eines meshy-t2- oder meshy-t2.5-preview, bei dem ai_model nicht gesetzt ist. Wird er mit meshy-6-lite gesendet, liefert dies 400 zurück.
Name
target_formats
Type
string[]
Description
Die zu generierenden Dateiformate. Meshy generiert und liefert nur diese Formate, was den Task verkürzen kann. Lässt du ihn weg, generiert Meshy jedes Format außer 3mf, das nur auf Anfrage generiert wird.
Verfügbare Werte:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
Standard false
Description
Ob zusätzlich eine Vorschau mit transparentem Hintergrund (RGBA) gerendert werden soll, die in alpha_thumbnail_url zurückgegeben wird, wenn du den Task abrufst. thumbnail_url ändert sich dadurch nicht.
Name
auto_size
Type
boolean
Standard false
Description
Ob die reale Höhe des Objekts per KI-Bildanalyse geschätzt und das Modell darauf skaliert werden soll. Meshy setzt den Ursprung unten, sofern du origin_at nicht festlegst.

Gilt nur wenn auto_size = true

Name
origin_at
Type
string
Standard bottom
Description
Wo der Ursprung des Modells platziert werden soll, bottom oder center.

Rückgabe

Das Feld result der Antwort enthält die ID des neuen Text zu 3D-Tasks.

Fehlerarten

Name
400 - Bad Request
Description
Die Anfrage kann nicht ausgeführt werden. Die Fehlermeldung gibt an, welches Problem gefunden wurde. Zum Beispiel:
- Ungültige Task-ID: preview_task_id ist ungültig oder stimmt mit keinem deiner preview-Tasks überein.
- Task nicht bereit: Der preview-Task war noch nicht erfolgreich.
- Modell-Nichtübereinstimmung: Das KI-Modell des preview-Tasks funktioniert nicht mit dem angeforderten refine-Modell.
- Nicht unterstütztes Modell für remove_lighting: remove_lighting wurde mit ai_model: "meshy-6-lite" gesendet.
Korrigiere die Anfrage und sende sie erneut. Siehe Fehler.
Name
401 - Unauthorized
Description
Der API-Schlüssel fehlt oder ist ungültig. Überprüfe den Authorization-Header.
Name
402 - Payment Required
Description
Zum Beispiel:
- Unzureichende Credits: Das Konto verfügt nicht über genügend Credits für diesen Task, oder das Konto hat ein Credit-Limit erreicht. Überprüfe dein Credit-Guthaben und versuche es erneut.
- Kostenloser Plan: Das Erstellen eines Tasks erfordert einen kostenpflichtigen Plan. Aktualisiere deinen Plan in den Abonnement-Einstellungen und versuche es erneut.
Name
429 - Too Many Requests
Description
Du hast deine Ratenbegrenzung überschritten. Warte und versuche es erneut. Siehe Ratenbegrenzungen.

GET/openapi/v2/text-to-3d/:id

Eine Text zu 3D-Aufgabe abrufen

Gibt eine Text zu 3D-Aufgabe anhand ihrer ID zurück. Dies funktioniert sowohl für preview- als auch für refine-Aufgaben.

Request

GET

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

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": {

    "message": ""

  },

  "consumed_credits": 20
}

Parameter

Name
id
Type
path
Description
Die Task-ID aus der Antwort der Erstellung.

Rückgabewerte

Das Text zu 3D-Task-Objekt.

Beispiele

Die folgende Tabelle zeigt ein Beispielmodell für jeden mode.

Mode	Beispielmodell
Preview
Refine

DELETE/openapi/v2/text-to-3d/:id

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

DELETE

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

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.

GET/openapi/v2/text-to-3d

Text-zu-3D-Aufgaben auflisten

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

Request

GET

/openapi/v2/text-to-3d

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": {

      "message": ""

    },

    "consumed_credits": 20
  }
]

Parameter

Name
page_num
Type
integer
Standard 1
Description
Die zurückzugebende Seitenzahl.
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ückgabe

Eine paginierte Liste von Text-zu-3D-Aufgabenobjekten.

GET/openapi/v2/text-to-3d/:id/stream

Einen Text-zu-3D-Task streamen

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

Request

GET

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

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": {

  "message": ""

},

"consumed_credits": 20
}

Parameter

Name
id
Type
path
Description
Die Task-ID aus der Antwort beim Erstellen.

Rückgabewerte

Ein Stream von Text-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 Text-to-3D-Task-Objekt

Ein Text-to-3D-Task-Objekt beschreibt eine Aufgabe, die aus einem Text-prompt ein 3D-Modell erzeugt. Es enthält den Status, den progress und die Modelldateien, sobald die Aufgabe erfolgreich war. Text zu 3D hat zwei Stufen, preview und refine. Ein Preview-Task erzeugt ein 3D-Modell, das nur aus einem Netz besteht, und ein Refine-Task erzeugt aus dem Ergebnis des Previews 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": {

    "message": ""

  },

  "consumed_credits": 20
}

Name
id
Type
string
Description
Die Task-ID. Behandeln Sie sie als eine undurchsichtige Zeichenfolge und verlassen Sie sich nicht auf ihr Format.
Name
type
Type
string
Description
Der Task-Typ: text-to-3d-preview für einen Preview-Task oder text-to-3d-refine fü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, statt eines leeren Strings.
- 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_formats 3mf enthä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-Stufe zu steuern.
Name
ultra_mode
Type
boolean
⚠ veraltet
Description
Verwenden Sie stattdessen geometry_resolution.
Name
geometry_resolution
Type
string
Description
Die Ultra-Stufe, in der der Preview-Task ausgeführt wurde, 2k oder 4k. Das Feld fehlt bei standard.
Name
texture_image_url
Type
string
Description
Download-URL für das Bild, das Sie gesendet haben, um die Texturierung zu steuern.
Name
thumbnail_url
Type
string
Description
Download-URL für ein Vorschaubild (Miniaturansicht) des 3D-Modells.
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
video_url
Type
string
⚠ veraltet
Description
Verlassen Sie sich nicht auf dieses Feld, da es in einer zukünftigen Version entfernt wird. Download-URL für das Vorschauvideo.
Name
progress
Type
integer
Description
Wie viel von der Aufgabe 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
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 generierten Texturkarten, als Array von Objekten. Es enthält normalerweise ein Objekt. Jedes Objekt hat folgende Felder:
- Name
  base_color
  Type
  string
  Description
  Die Basisfarbkarte.
- Name
  metallic
  Type
  string
  Description
  Die Metallic-Karte. Fehlt, wenn Sie den Task mit enable_pbr: false erstellt haben.
- Name
  normal
  Type
  string
  Description
  Die Normal Map. Fehlt, wenn Sie den Task mit enable_pbr: false erstellt haben.
- Name
  roughness
  Type
  string
  Description
  Die Rauheitskarte. Fehlt, wenn Sie den Task mit enable_pbr: false erstellt haben.
- Name
  emission
  Type
  string
  Description
  Die Emissionskarte. Fehlt in jedem dieser Fälle:
  
  Sie haben den Task mit enable_pbr: false erstellt.
  
  ai_model ist meshy-6-lite, meshy-7, meshy-7.1 oder latest.
  
  texture_resolution ist 8k.
  
  Der Task verfeinert (refine) einen meshy-t2- oder meshy-t2.5-Preview, ohne ai_model zu setzen.
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. 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.