Text zu 3D API

Text zu 3D API ist eine Funktion, mit der Sie Meshys Text-zu-3D-Funktionen in Ihre eigene Anwendung integrieren können. In diesem Abschnitt finden Sie alle Informationen, die Sie für den Einstieg in diese API benötigen.

Text zu 3D verwendet einen zweistufigen Workflow. Erstellen Sie zuerst eine Preview-Aufgabe (mode: "preview"), um ein 3D-Mesh ohne Textur zu generieren, damit Sie die Form bewerten können. Übergeben Sie anschließend die Aufgaben-ID der abgeschlossenen Preview an eine Refine-Aufgabe (mode: "refine"), um die Textur auf das Mesh anzuwenden. Beide Schritte verwenden denselben endpoint.

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

Text-to-3D-Vorschauaufgabe erstellen

Dieser endpoint erstellt eine Text-to-3D-Vorschauaufgabe, die aus einem Text-Prompt ein untexturiertes 3D-Mesh (nur Geometrie) generiert. Dies ist der erste Schritt des zweistufigen Workflows. Sobald die Vorschau erfolgreich ist, verwenden Sie die zurückgegebene Aufgaben-ID, um eine Verfeinerungsaufgabe zu erstellen für die Texturierung. Siehe Das Text-to-3D-Aufgabenobjekt für das vollständige Antwortschema.

Parameter

Name
mode
Type
string
Erforderlich
Description
Dieses Feld sollte beim Erstellen einer Vorschauaufgabe auf "preview" gesetzt werden.
Name
prompt
Type
string
Erforderlich
Description
Beschreiben Sie, welche Art von Objekt das 3D-Modell ist. Maximal 600 Zeichen.
Name
model_type
Type
string
Standard standard
Description
Geben Sie den Typ der 3D-Mesh-Generierung an.
Verfügbare Werte:
- standard: Reguläre 3D-Mesh-Generierung mit hohem Detailgrad.
- lowpoly: Generiert ein Low-Poly-Mesh, das für sauberere Polygone optimiert ist.
Wenn lowpoly ausgewählt ist, werden ai_model, topology, target_polycount, should_remesh ignoriert.
Name
ai_model
Type
string
Standard latest
Description
ID des zu verwendenden Modells. Verfügbare Werte: meshy-5, meshy-6, latest (Meshy 6).
Name
should_remesh
Type
boolean
Standard false (meshy-6), true (others)
Description
Steuert, ob die remesh-Phase aktiviert wird. Wenn auf false gesetzt, gibt die API direkt das Dreiecks-Mesh mit der höchsten Präzision zurück.

Gilt nur wenn should_remesh = true

Name
topology
Type
string
Standard triangle
Description
Geben Sie die Topologie des generierten Modells an.
Verfügbare Werte:
- quad: Generiert ein überwiegend aus Quads bestehendes Mesh.
- triangle: Generiert ein reduziertes Dreiecks-Mesh.
Name
target_polycount
Type
integer
Standard 30,000
Description
Geben Sie die Zielanzahl der Polygone im generierten Modell an. Die tatsächliche Anzahl der Polygone kann je nach Komplexität der Geometrie vom Zielwert abweichen.
Der gültige Wertebereich variiert je nach Benutzerstufe:
- 100 bis 300.000 (einschließlich)
Name
decimation_mode
Type
integer
Description
Aktivieren Sie adaptive Dezimierung, indem Sie eine Polygonanzahl-Stufe festlegen. Wenn gesetzt, wird target_polycount ignoriert.
Verfügbare Werte:
- 1: Adaptiv — ultrahohe Polygonanzahl.
- 2: Adaptiv — hohe Polygonanzahl.
- 3: Adaptiv — mittlere Polygonanzahl.
- 4: Adaptiv — niedrige Polygonanzahl.

Name
symmetry_mode
Type
string
⚠ veraltet
Standard auto
Description
Veraltet. Dieser Parameter beeinflusst die Ausgabe nicht mehr.
Das Feld symmetry_mode steuert das Symmetrieverhalten während des Modellgenerierungsprozesses.
Die gültigen Werte sind:
- off: Deaktiviert Symmetrie.
- auto: Bestimmt und wendet Symmetrie automatisch basierend auf der Eingabegeometrie an.
- on: Erzwingt Symmetrie während der Generierung.
Name
pose_mode
Type
string
Standard ""
Description
Geben Sie den Posenmodus für das generierte Modell an.
Verfügbare Werte:
- a-pose: Generiert das Modell in einer A-Pose.
- t-pose: Generiert das Modell in einer T-Pose.
- "" (leerer String): Es wird keine spezifische Pose angewendet.
Name
is_a_t_pose
Type
boolean
⚠ veraltet
Standard false
Description
Verwenden Sie stattdessen pose_mode. Ob das Modell in einer A-/T-Pose generiert werden soll.
Name
art_style
Type
string
⚠ veraltet
Standard realistic
Description
Wird von Meshy-6 nicht unterstützt. Anfragen mit Meshy-6 ignorieren art_style, und einige Kombinationen können Fehler verursachen. Verfügbare Werte: realistic, sculpture.
enable_pbr sollte bei Verwendung des Sculpture-Stils auf false gesetzt werden, da der Sculpture-Stil eigene PBR-Maps generiert.
Name
moderation
Type
boolean
Standard false
Description
Wenn auf true gesetzt, wird der Eingabeinhalt automatisch auf potenziell schädliche Inhalte geprüft. Wenn schädliche Inhalte erkannt werden, wird die Aufgabe nicht mit der Generierung fortfahren.
Der Text aus prompt wird geprüft.
Name
target_formats
Type
string[]
Description
Gibt an, welche 3D-Dateiformate in die Ausgabe aufgenommen werden sollen. Nur die angeforderten Formate werden generiert und zurückgegeben, wodurch die Fertigstellungszeit der Aufgabe reduziert werden kann. Wenn ausgelassen, werden alle unterstützten Formate einbezogen.
Verfügbare Werte: glb, obj, fbx, stl, usdz, 3mf
Wenn ausgelassen, werden alle Formate außer 3mf generiert. 3mf wird nur einbezogen, wenn es ausdrücklich angegeben ist.
Name
alpha_thumbnail
Type
boolean
Standard false
Description
Wenn auf true gesetzt, rendert die Aufgabe zusätzlich eine Version der Vorschau mit transparentem Hintergrund (RGBA) und gibt sie in der GET-Antwort als alpha_thumbnail_url zurück. Das bestehende Feld thumbnail_url bleibt unverändert.
Name
auto_size
Type
boolean
Standard false
Description
Wenn auf true gesetzt, verwendet der Dienst KI-Vision, um die reale Höhe des Objekts automatisch zu schätzen und die Größe des Modells entsprechend anzupassen. Der Ursprung ist standardmäßig bottom, sofern origin_at nicht ausdrücklich gesetzt ist.

Gilt nur wenn auto_size = true

Name
origin_at
Type
string
Standard bottom
Description
Position des Ursprungs, wenn auto_size aktiviert ist.
Verfügbare Werte: bottom, center.

Rückgabewerte

Die Eigenschaft result der Antwort enthält die Aufgaben-id der neu erstellten Text-to-3D-Aufgabe.

Fehlermodi

Name
400 - Bad Request
Description
Die Anfrage war unzulässig. Häufige Ursachen:
- Fehlender Parameter: Ein erforderlicher Parameter (z. B. prompt, mode) fehlt.
- Ungültiger Parameter: art_style ist keiner der zulässigen Werte.
- Prompt zu lang: Der prompt überschreitet die Zeichenbegrenzung.
Name
401 - Unauthorized
Description
Authentifizierung fehlgeschlagen. Bitte überprüfen Sie Ihren API key.
Name
402 - Payment Required
Description
Nicht genügend Credits, um diese Aufgabe auszuführen.
Name
429 - Too Many Requests
Description
Sie haben Ihr Ratenlimit überschritten.

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 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",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

Response

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

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

Text-zu-3D-Refine-Task erstellen

Dieser endpoint erstellt einen Text-zu-3D-Refine-Task, der eine Textur auf ein abgeschlossenes Preview-Mesh anwendet. Sie müssen die preview_task_id aus einem erfolgreichen Preview-Task angeben. Dies ist der zweite Schritt des zweistufigen Workflows.

Parameter

Name
mode
Type
string
Erforderlich
Description
Dieses Feld sollte beim Erstellen eines Refine-Tasks auf "refine" gesetzt werden.
Name
preview_task_id
Type
string
Erforderlich
Description
Die entsprechende Preview-Task-ID.
Der Status des angegebenen Preview-Tasks muss SUCCEEDED sein.
Name
enable_pbr
Type
boolean
Standard false
Description
Generiert zusätzlich zur Basisfarbe PBR-Maps (Metallic, Roughness, Normal). Eine Emission-Map ist ebenfalls enthalten, wenn ai_model meshy-6 oder latest ist.
Name
hd_texture
Type
boolean
Standard false
Description
Generiert die Basisfarbtextur mit 4K-Auflösung (4096×4096) für höhere Detailgenauigkeit.
Wird nur unterstützt, wenn ai_model meshy-6 oder latest ist. PBR-Maps werden immer mit 2K generiert.
Name
texture_prompt
Type
string
Description
Geben Sie einen zusätzlichen Text-Prompt an, um den Texturierungsprozess zu steuern. Maximal 600 Zeichen.
Name
texture_image_url
Type
string
Description
Geben Sie ein 2D-Bild an, um den Texturierungsprozess zu steuern. Derzeit unterstützen wir die Formate .jpg, .jpeg und .png.
Es gibt zwei Möglichkeiten, das Bild bereitzustellen:
- Öffentlich zugängliche URL: Eine URL, die über das öffentliche Internet zugänglich ist
- Data URI: Eine base64-codierte Data URI des Bildes. Beispiel für eine Data URI: data:image/jpeg;base64,<your base64-encoded image data>
Die Bildtexturierung funktioniert möglicherweise nicht optimal, wenn zwischen dem ursprünglichen Asset und dem hochgeladenen Bild erhebliche Geometrieunterschiede bestehen. Nur eines von texture_image_url oder texture_prompt darf zur Steuerung des Texturierungsprozesses verwendet werden. Wenn beide Parameter angegeben werden, wird standardmäßig texture_prompt verwendet, um das Modell zu texturieren.
Name
ai_model
Type
string
Standard latest
Description
ID des Modells, das für das Refine verwendet werden soll. Verfügbare Werte: meshy-5, meshy-6, latest (Meshy 6).
Name
moderation
Type
boolean
Standard false
Description
Wenn auf true gesetzt, werden die Eingabeinhalte automatisch auf potenziell schädliche Inhalte überprüft. Wenn schädliche Inhalte erkannt werden, wird der Task nicht mit der Generierung fortfahren.
Sowohl der Text aus texture_prompt als auch das Bild aus texture_image_url werden überprüft.
Name
remove_lighting
Type
boolean
Standard true
Description
Entfernt Highlights und Schatten aus der Basisfarbtextur und erzeugt so ein saubereres Ergebnis, das unter benutzerdefinierten Beleuchtungs-Setups besser funktioniert.
Wird nur unterstützt, wenn ai_model meshy-6 oder latest ist.
Name
target_formats
Type
string[]
Description
Gibt an, welche 3D-Dateiformate in der Ausgabe enthalten sein sollen. Nur die angeforderten Formate werden generiert und zurückgegeben, wodurch sich die Task-Abschlusszeit reduzieren kann. Wenn weggelassen, werden alle unterstützten Formate einbezogen.
Verfügbare Werte: glb, obj, fbx, stl, usdz, 3mf
Wenn weggelassen, werden alle Formate außer 3mf generiert. 3mf wird nur einbezogen, wenn es ausdrücklich angegeben wird.
Name
alpha_thumbnail
Type
boolean
Standard false
Description
Wenn auf true gesetzt, rendert der Task zusätzlich eine Version der Vorschau mit transparentem Hintergrund (RGBA) und gibt sie in der GET-Antwort als alpha_thumbnail_url zurück. Das vorhandene Feld thumbnail_url bleibt unverändert.
Name
auto_size
Type
boolean
Standard false
Description
Wenn auf true gesetzt, verwendet der Service KI-Vision, um die reale Höhe des Objekts automatisch zu schätzen und die Größe des Modells entsprechend anzupassen. Der Ursprung ist standardmäßig bottom, sofern origin_at nicht ausdrücklich gesetzt ist.

Gilt nur wenn auto_size = true

Name
origin_at
Type
string
Standard bottom
Description
Position des Ursprungs, wenn auto_size aktiviert ist.
Verfügbare Werte: bottom, center.

Rückgabe

Die Eigenschaft result der Antwort enthält die Task-id des neu erstellten Text-zu-3D-Tasks.

Fehlermodi

Name
400 - Bad Request
Description
Die Anfrage war nicht akzeptabel. Häufige Ursachen:
- Ungültige Task-ID: Die preview_task_id ist ungültig oder existiert nicht.
- Task nicht bereit: Der Preview-Task war noch nicht erfolgreich.
- Modellinkompatibilität: Das KI-Modell des Preview-Tasks ist nicht mit dem angeforderten Refine-Modell kompatibel.
Name
401 - Unauthorized
Description
Authentifizierung fehlgeschlagen. Bitte überprüfen Sie Ihre API key.
Name
402 - Payment Required
Description
Unzureichende Credits, um diesen Task auszuführen.
Name
404 - Not Found
Description
Der durch preview_task_id angegebene Preview-Task wurde nicht gefunden.
Name
429 - Too Many Requests
Description
Sie haben Ihr Rate Limit überschritten.

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"
}

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

Eine Text-to-3D-Aufgabe abrufen

Dieser endpoint ermöglicht es dir, eine Text-to-3D-Aufgabe anhand einer gültigen Aufgaben-id abzurufen. Siehe Das Text-to-3D-Aufgabenobjekt, um zu sehen, welche Eigenschaften im Text-to-3D-Aufgabenobjekt enthalten sind.

Dieser endpoint funktioniert sowohl für Vorschau- als auch für Verfeinerungsaufgaben.

Parameter

Name
id
Type
path
Description
Eindeutige Kennung der abzurufenden Text-to-3D-Aufgabe.

Rückgabe

Die Antwort enthält das Text-to-3D-Aufgabenobjekt. Details findest du im Abschnitt Das Text-to-3D-Aufgabenobjekt.

Beispiele

Modus	Beispielmodell
Vorschau
Verfeinern

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
}

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

Eine Text-zu-3D-Aufgabe löschen

Dieser endpoint löscht eine Text-zu-3D-Aufgabe dauerhaft, einschließlich aller zugehörigen Modelle und Daten. Diese Aktion ist unumkehrbar.

Pfadparameter

Name
id
Type
path
Description
Die ID der zu löschenden Text-zu-3D-Aufgabe.

Rückgabe

Gibt bei Erfolg 200 OK zurück.

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

// Returns 200 Ok on success.

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

Text-to-3D-Aufgaben auflisten

Dieser endpoint ermöglicht es Ihnen, eine Liste von Text-to-3D-Aufgaben abzurufen.

Parameter

Name
page_num
Type
integer
Standard 1
Description
Seitenzahl für die Paginierung.
Name
page_size
Type
integer
Standard 10
Description
Limit für die Seitengröße. Maximal zulässig sind 50 Elemente.
Name
sort_by
Type
string
Description
Feld, nach dem sortiert werden soll.
Verfügbare Werte:
- +created_at: Nach Erstellungszeit in aufsteigender Reihenfolge sortieren.
- -created_at: Nach Erstellungszeit in absteigender Reihenfolge sortieren.

Rückgabe

Gibt eine paginierte Liste der Text-to-3D-Aufgabenobjekte 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
  }
]

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

Eine Text-zu-3D-Aufgabe streamen

Dieser endpoint streamt Echtzeit-Updates für eine Text-zu-3D-Aufgabe mithilfe von Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Eindeutiger Bezeichner für die zu streamende Text-zu-3D-Aufgabe.

Rückgabe

Gibt einen Stream von Text-zu-3D-Aufgabenobjekten als Server-Sent Events zurück.

Bei PENDING- oder IN_PROGRESS-Aufgaben enthält der Antwort-Stream nur die erforderlichen Felder progress und status.

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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
}

Das Text-to-3D-Aufgabenobjekt

Das Text-to-3D-Aufgabenobjekt ist eine Arbeitseinheit, die Meshy nachverfolgt, um aus einer Text-Eingabe ein 3D-Modell zu generieren. Es gibt zwei Stufen der Text-to-3D-API: preview und refine. Die Preview-Stufe dient dazu, ein reines Mesh-3D-Modell zu generieren, und die Refine-Stufe dient dazu, basierend auf dem Ergebnis der Preview-Stufe ein 3D-Modell mit Textur zu generieren.

Das Objekt hat die folgenden Eigenschaften:

Properties

Name
id
Type
string
Description
Eindeutiger Bezeichner für den Task. Obwohl wir als Implementierungsdetail eine k-sortierbare UUID für Task-IDs verwenden, solltest du keine Annahmen über das Format der ID treffen.
Name
type
Type
string
Description
Typ des Text-to-3D-Tasks. Mögliche Werte sind text-to-3d-preview für Tasks der Vorschauphase und text-to-3d-refine für Tasks der Verfeinerungsphase.
Name
model_urls
Type
object
Description
Herunterladbare URL zur von Meshy generierten texturierten 3D-Modelldatei. Die Eigenschaft für ein Format wird weggelassen, wenn das Format nicht generiert wurde, anstatt einen leeren String zurückzugeben.
- Name
  glb
  Type
  string
  Description
  Herunterladbare URL zur GLB-Datei.
- Name
  fbx
  Type
  string
  Description
  Herunterladbare URL zur FBX-Datei.
- Name
  usdz
  Type
  string
  Description
  Herunterladbare URL zur USDZ-Datei.
- Name
  obj
  Type
  string
  Description
  Herunterladbare URL zur OBJ-Datei.
- Name
  mtl
  Type
  string
  Description
  Herunterladbare URL zur MTL-Datei.
- Name
  stl
  Type
  string
  Description
  Herunterladbare URL zur STL-Datei.
- Name
  3mf
  Type
  string
  Description
  Herunterladbare URL zur 3MF-Datei. Nur vorhanden, wenn 3mf über target_formats angefordert wurde.
Name
prompt
Type
string
Description
Dies ist der unveränderte prompt, der zum Erstellen des Tasks verwendet wurde.
Name
negative_prompt
Type
string
⚠ veraltet
Description
Aus Gründen der Abwärtskompatibilität beibehalten. Dieses Feld hat keine funktionalen Auswirkungen auf generierte Modelle.
Name
art_style
Type
string
⚠ veraltet
Description
Der unveränderte art_style, der zum Erstellen des Vorschau-Tasks verwendet wurde. Wird von Meshy-6 nicht unterstützt.
Name
texture_richness
Type
string
⚠ veraltet
Description
Aus Gründen der Abwärtskompatibilität beibehalten. Dieses Feld hat keine funktionalen Auswirkungen auf generierte Modelle.
Name
texture_prompt
Type
string
Description
Zusätzlicher Text-Prompt, der bereitgestellt wird, um den Texturierungsprozess während der Verfeinerungsphase zu steuern.
Name
texture_image_url
Type
string
Description
Herunterladbare URL zum Texturbild, das zur Steuerung des Texturierungsprozesses verwendet wurde.
Name
thumbnail_url
Type
string
Description
Herunterladbare URL zum Vorschaubild der Modelldatei.
Name
alpha_thumbnail_url
Type
string
Description
Herunterladbare URL zu einer Version von thumbnail_url mit transparentem Hintergrund (RGBA). Nur vorhanden, wenn der Task mit alpha_thumbnail: true erstellt wurde und die transparente Vorschau erfolgreich gerendert wurde; andernfalls wird dieses Feld weggelassen.
Name
video_url
Type
string
⚠ veraltet
Description
Herunterladbare URL zum Vorschauvideo. Wird in einer zukünftigen Version entfernt.
Name
progress
Type
integer
Description
Fortschritt des Tasks. Wenn der Task noch nicht gestartet wurde, ist diese Eigenschaft 0. Sobald der Task erfolgreich abgeschlossen wurde, wird sie zu 100.
Name
started_at
Type
timestamp
Description
Zeitstempel, wann der Task gestartet wurde, in Millisekunden. Wenn der Task noch nicht gestartet wurde, ist diese Eigenschaft 0.
Ein Zeitstempel stellt die Anzahl der Millisekunden dar, die seit dem 1. Januar 1970 UTC vergangen sind, gemäß dem RFC 3339-Standard. Zum Beispiel wird Freitag, der 1. September 2023, 12:00:00 Uhr GMT als 1693569600000 dargestellt. Dies gilt für alle Zeitstempel in der Meshy API.
Name
created_at
Type
timestamp
Description
Zeitstempel, wann der Task erstellt wurde, in Millisekunden.
Name
finished_at
Type
timestamp
Description
Zeitstempel, wann der Task abgeschlossen wurde, in Millisekunden. Wenn der Task noch nicht abgeschlossen ist, ist diese Eigenschaft 0.
Name
status
Type
string
Description
Status des Tasks. Mögliche Werte sind einer von PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Ein Array von Textur-URL-Objekten, die aus dem Task generiert werden. Normalerweise enthält dies nur ein Textur-URL-Objekt. Jede Textur-URL hat die folgenden Eigenschaften:
- Name
  base_color
  Type
  string
  Description
  Herunterladbare URL zum Base-Color-Map-Bild.
- Name
  metallic
  Type
  string
  Description
  Herunterladbare URL zum Metallic-Map-Bild.
  Wenn der Task mit enable_pbr: false erstellt wird, wird diese Eigenschaft weggelassen.
- Name
  normal
  Type
  string
  Description
  Herunterladbare URL zum Normal-Map-Bild.
  Wenn der Task mit enable_pbr: false erstellt wird, wird diese Eigenschaft weggelassen.
- Name
  roughness
  Type
  string
  Description
  Herunterladbare URL zum Roughness-Map-Bild.
  Wenn der Task mit enable_pbr: false erstellt wird, wird diese Eigenschaft weggelassen.
- Name
  emission
  Type
  string
  Description
  Herunterladbare URL zum Emission-Map-Bild.
  Wenn der Task mit enable_pbr: false erstellt wird oder ai_model meshy-5 ist, wird diese Eigenschaft weggelassen.
Name
preceding_tasks
Type
integer
Description
Die Anzahl der vorhergehenden Tasks.
Der Wert dieses Felds ist nur aussagekräftig, wenn der Task-Status PENDING ist.
Name
task_error
Type
object
Description
Fehlerdetails für fehlgeschlagene Tasks. Siehe Fehler für die vollständige task_error-Objektreferenz.
Name
consumed_credits
Type
integer
Description
Die Anzahl der von diesem Task verbrauchten Credits. Vorhanden, wenn der Task-Status PENDING, IN_PROGRESS oder SUCCEEDED ist. Gibt 0 für FAILED-Tasks zurück (Credits werden bei einem Fehler erstattet).

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,
  "seed": 1234,
  "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
}