lowpoly wird am 30.10.2026 abgeschaltet. meshy-7 wird als 3D-Generierungsmodell am 31.12.2026 abgeschaltet; als Texturmodell bleibt es verfügbar. Wechseln Sie vor diesen Terminen das Modell, um Fehler bei Anfragen zu vermeiden. Alle Abkündigungen ansehen

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

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 gibt 400 zurü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 Detailgrad
    • 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.

    Standardmodelle (model_type: standard):

    • meshy-6-lite
    • meshy-6
    • meshy-7.1
    • latest: Meshy 7.1
    • meshy-7 (veraltet): Senden Sie stattdessen meshy-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 mit target_polycount festlegen
    • meshy-t2.5 (Standard): schärferer Detailgrad für Game-Assets, Dreiecksausgabe und eine Flächenanzahl, die Sie mit target_polycount festlegen

    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 400 zurück.

    Verfügbare Werte:

    • standard
    • 2k: führt den Ultra-Durchlauf bei 2048³ aus
    • 4k: führt den Ultra-Durchlauf bei 4096³ aus, für feineres Oberflächendetail

    2k benötigt meshy-7.1, latest oder das veraltete meshy-7. 4k benötigt meshy-7.1 oder latest. Andere Modelle geben 400 zurück.

  • 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

    Die Smart-Topology-Ausgabe besteht ausschließlich aus Dreiecken. Das Senden von quad mit ai_model meshy-t2 oder meshy-t2.5 gibt 400 zurück.

  • Name
    decimation_mode
    Type
    integer
    Description

    Adaptive Flächenanzahl, nach Stufe. Wenn Sie dies festlegen, ignoriert Meshy target_polycount.

    Verfügbare Werte:

    • 1: ultra
    • 2: hoch
    • 3: mittel
    • 4: niedrig
  • Name
    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: true bei einem standard-Modell. Meshy vernetzt das Netz neu (dezimiert es) auf etwa diese Anzahl. Wenn Sie decimation_mode festlegen, verwendet Meshy dieses 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ächenanzahl. 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:

    FallBereichStandard
    Neuvernetzung100 bis 30000030000
    meshy-t2100 bis 150004000
    meshy-t2.5100 bis 3000015000

    Ein Wert außerhalb des Bereichs gibt 400 zurück.

    Für ein Low-Poly-Game-Asset verwenden Sie ein Smart-Topology-Modell, anstatt ein Standardmodell neu zu vernetzen. Siehe Modelle.

  • 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 Symmetrie
    • auto: wendet Symmetrie basierend auf der Eingabegeometrie an
    • on: erzwingt Symmetrie während der Generierung
  • Name
    pose_mode
    Type
    string
    Description

    Die Pose für ein Charaktermodell, a-pose oder t-pose. Um keine Pose zu erhalten, lassen Sie pose_mode und is_a_t_pose weg.

  • Name
    is_a_t_pose
    Type
    boolean
    ⚠ veraltet
    Standard false
    Description

    Senden Sie stattdessen pose_mode. Ob das Modell in einer A-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 prompt vor der Generierung auf schädliche Inhalte überprüft werden soll. Wenn Meshy schädliche Inhalte erkennt, gibt die Anfrage 400 zurü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:

    • glb
    • obj
    • fbx
    • stl
    • usdz
    • 3mf
  • 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_url zurü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_at nicht 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ü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 prompt oder mode, fehlt.
    • Prompt zu lang: prompt überschreitet die Zeichenbegrenzung.
    • 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 dann erneut. Siehe Fehler.

  • Name
    401 - Unauthorized
    Description

    Der API-Schlüssel fehlt oder ist ungültig. Überprüfen Sie den Authorization-Header.

  • Name
    402 - Payment Required
    Description

    Zum Beispiel:

    • Unzureichende Credits: Das Konto verfügt nicht über genügend Credits für diese Aufgabe, oder das Konto hat ein Credit-Limit erreicht. Überprüfen Sie Ihr Credit-Guthaben, und versuchen Sie es 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.


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

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

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

# 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 SUCCEEDED haben.

  • 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_model meshy-6 erzeugt Meshy außerdem eine Emission-Map, außer bei texture_resolution: 8k. meshy-6-lite, meshy-7 und latest erzeugen keine Emission-Map. Ebenso wenig ein Refine eines meshy-t2- oder meshy-t2.5-Vorschau-Tasks, der ai_model nicht setzt. Mit ai_model: meshy-n1 führt true zu 400.

  • 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 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 oder latest. Mit meshy-n1 geben sie 400 zurück. Bei 8k erzeugt Meshy keine Emission-Map.

  • Name
    hd_texture
    Type
    boolean
    ⚠ veraltet
    Standard false
    Description

    Senden Sie stattdessen texture_resolution. hd_texture: true entspricht texture_resolution: "4k". Wenn Sie beides senden, verwendet Meshy texture_resolution.

  • Name
    texture_prompt
    Type
    string
    Description

    Text, der die Texturierung steuert, bis zu 800 Zeichen. Längerer Text gibt 400 zurück. Senden Sie entweder texture_prompt oder texture_image_url, nicht beides. Wenn Sie beides senden, verwendet Meshy texture_prompt. Mit ai_model: meshy-n1 führt das Senden zu 400.

  • 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-n1 texturiert Meshy anhand dieses Bildes als Vorderansicht.

  • 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_model bei einem Refine nur das Texturmodell aus.

    Verfügbare Werte:

    • meshy-7: Meshy 7
    • latest: das neueste Texturmodell, derzeit Meshy 7
    • meshy-6: Meshy 6
    • meshy-6-lite: Meshy 6 Lite
    • meshy-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-n1 texturiert Meshy aus texture_image_url. Ohne diesen Parameter verwendet Meshy das Referenzbild, das ein meshy-7.1- oder latest-Vorschau-Task gespeichert hat. Jede andere Vorschau gibt 400 zurück, es sei denn, Sie senden texture_image_url. Die Vorschau darf höchstens 7.999.999 Dreiecke haben. Eine auf Quads remeshte Vorschau gibt 400 zurück.

  • 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. Wenn Meshy schädliche Inhalte erkennt, gibt die Anfrage 400 zurü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_model meshy-6 ist. meshy-7 und latest akzeptieren den Parameter, ignorieren ihn jedoch, ebenso ein Refine eines meshy-t2- oder meshy-t2.5-Vorschau-Tasks, der ai_model nicht setzt. Das Senden mit meshy-6-lite gibt 400 zurück. Mit meshy-n1 führt true zu 400.

  • 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:

    • 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 beim Abrufen des Tasks in alpha_thumbnail_url zurü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_at nicht 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 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_id ist 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_lighting wurde mit ai_model: "meshy-6-lite" gesendet.
    • No reference image for Meshy N1: ai_model: meshy-n1 wurde ohne texture_image_url gesendet, und die Vorschau hat kein Referenzbild, das Meshy N1 verwenden kann. Senden Sie texture_image_url.
    • Quad preview for Meshy N1: ai_model: meshy-n1 wurde für eine auf Quads remeshte Vorschau gesendet. Führen Sie den Refine mit einem anderen ai_model durch.
    • Too many triangles for Meshy N1: Mit ai_model: meshy-n1 hat die Vorschau mehr als 7.999.999 Dreiecke. Führen Sie den Refine mit einem anderen ai_model durch.
    • Unsupported option for Meshy N1: ai_model: meshy-n1 wurde mit einer dieser Optionen gesendet:
      • texture_prompt
      • enable_pbr: true
      • texture_resolution von 4k oder 8k
      • hd_texture: true ohne texture_resolution
      • remove_lighting: true

    Korrigieren Sie die Anfrage und senden Sie sie erneut. Siehe Fehler.

  • Name
    401 - Unauthorized
    Description

    Der API-Schlüssel fehlt oder ist ungültig. Überprüfen Sie den Authorization-Header.

  • Name
    402 - Payment Required
    Description

    Zum Beispiel:

    • 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.


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

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

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": null,

  "consumed_credits": 20
}

Parameter

  • Name
    id
    Type
    path
    Description

    Die Task-ID aus der Antwort der Erstellung.

Rückgabe

Das Text zu 3D Task-Objekt.

Beispiele

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

ModeBeispielmodell
PreviewPreview model
RefineRefined model

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

List Text to 3D tasks

Gibt eine Liste Ihrer 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": null,

    "consumed_credits": 20
  }
]

Parameter

  • Name
    page_num
    Type
    integer
    Standard 1
    Description

    Die zurückzugebende Seitenzahl, bis zu 255. Ein größerer Wert gibt 400 zurü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.


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

Einen Text-zu-3D-Task streamen

Streamt die Aktualisierungen 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": 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-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, 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_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-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, 2k oder 4k. Das Feld fehlt bei standard.

  • 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_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
    progress
    Type
    integer
    Description

    Wie viel des Tasks erledigt ist, in Prozent. 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 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: 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 Roughness-Map. Fehlt, wenn Sie den Task mit enable_pbr: false erstellt haben.

    • Name
      emission
      Type
      string
      Description

      Die Emission-Map. 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 eine meshy-t2- oder meshy-t2.5-Preview, ohne ai_model festzulegen.
  • Name
    preceding_tasks
    Type
    integer
    Description

    Die Anzahl der Tasks, die in der Warteschlange vor diesem liegen. Der Wert ist nur aussagekräftig, solange der Task PENDING ist.

  • Name
    task_error
    Type
    object
    Description

    Die Fehlerdetails, wenn der Task fehlschlägt. Der Wert ist null, es sei denn, der Status ist FAILED. 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.