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

Erzeuge Bilder aus einem Text-prompt mit den KI-Modellen von Meshy.


POST/openapi/v1/text-to-image

Eine Text zu Bild-Aufgabe erstellen

Erstellt eine Text zu Bild-Aufgabe. Die Aufgabe läuft im Hintergrund. Wie lange eine Aufgabe in der Regel dauert, erfahren Sie unter Verarbeitungszeiten.

Request

POST
/openapi/v1/text-to-image
# Generate an image from a text prompt
curl https://api.meshy.ai/openapi/v1/text-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "aspect_ratio": "16:9"
  }'

Response

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

Parameter

  • Name
    ai_model
    Type
    string
    Erforderlich
    Description

    Das KI-Modell, das das Bild erzeugt. Die Preise unterscheiden sich je nach Modell. Preise finden Sie unter Preise.

    Verfügbare Werte:

    • nano-banana: das Standardmodell
    • nano-banana-2: leistungsfähiger als nano-banana
    • nano-banana-2-lite: eine Lite-Version von nano-banana-2
    • nano-banana-2-1: Nano Banana 2.1
    • nano-banana-pro: das Pro-Modell mit höherer Qualität. Benötigt einen Pro-Plan oder höher. Bei einem niedrigeren Plan wird 402 zurückgegeben.
    • gpt-image-2: OpenAI GPT Image 2
    • gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare)
    • gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst)
    • gpt-image-2-6-flare: OpenAI GPT Image 2.6 (Flare)
    • gpt-image-2-6-sunburst: OpenAI GPT Image 2.6 (Sunburst)
  • Name
    prompt
    Type
    string
    Erforderlich
    Description

    Text, der das zu erzeugende Bild beschreibt. Eine detaillierte Beschreibung liefert bessere Ergebnisse.

  • Name
    generate_multi_view
    Type
    boolean
    Standard false
    Description

    Ob ein Mehransicht-Bild erzeugt werden soll, das das Motiv aus mehreren Blickwinkeln zeigt. Wenn dieser Wert true ist, kann aspect_ratio nicht gesendet werden. Wenn beide gesendet werden, wird 400 zurückgegeben.

  • Name
    pose_mode
    Type
    string
    Description

    Die Pose für einen Charakter, a-pose oder t-pose. Lassen Sie den Parameter weg, wenn keine Pose gewünscht ist.

    Wie eine Pose funktioniert, hängt von ai_model ab:

    • nano-banana-2, nano-banana-2-lite und nano-banana-2-1: Meshy behält das von Ihnen gewählte Modell bei. Das Bild ist immer 3:4, und Meshy ignoriert aspect_ratio.
    • nano-banana und nano-banana-pro: Meshy erzeugt das Bild mit nano-banana-pro, sodass das ai_model der Aufgabe als nano-banana-pro zurückgelesen wird. Dies erfordert einen Pro-Plan oder höher. Das Bild ist immer 3:4, und Meshy ignoriert aspect_ratio.
    • Die GPT Image-Modelle (gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst, gpt-image-2-6-flare und gpt-image-2-6-sunburst): Meshy behält das von Ihnen gewählte Modell und Ihr aspect_ratio bei.
  • Name
    aspect_ratio
    Type
    string
    Standard 1:1
    Description

    Die Form des Bildes. Welche Werte Sie senden können, hängt von ai_model ab.

    Verfügbare Werte:

    • 1:1: quadratisch
    • 16:9: Breitbild, Querformat
    • 9:16: Breitbild, Hochformat
    • 4:3: Standard-Querformat
    • 3:4: Standard-Hochformat
    • 3:2: Querformat, nur GPT Image-Modelle
    • 2:3: Hochformat, nur GPT Image-Modelle

    Die nano-banana-Modelle (nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-2-1 und nano-banana-pro) geben für 3:2 und 2:3 400 zurück.

  • Name
    remove_background
    Type
    boolean
    Standard false
    Description

    Ob der Hintergrund des Bildes entfernt werden soll. true liefert ein transparentes RGBA-PNG, sodass Sie das Motiv auf einen beliebigen Hintergrund setzen können.

Rückgabewerte

Das Feld result der Antwort enthält die ID der neuen Text zu Bild-Aufgabe.

Fehlerfälle

  • Name
    400 - Bad Request
    Description

    Die Anfrage kann nicht ausgeführt werden. Die Fehlermeldung nennt das gefundene Problem. Zum Beispiel:

    • Fehlender Parameter: Ein erforderlicher Parameter, z. B. ai_model oder prompt, fehlt.
    • Ungültiger Parameter: ai_model oder aspect_ratio ist keiner der zulässigen Werte.
    • Konflikt: aspect_ratio wurde zusammen mit generate_multi_view: true gesendet.

    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

    Das Konto kann diese Aufgabe nicht ausführen. Zum Beispiel:

    • Kostenloser Plan: Das Erstellen einer Aufgabe erfordert einen kostenpflichtigen Plan. Aktualisieren Sie Ihren Plan in Ihren Abonnementeinstellungen und versuchen Sie es erneut.
    • Unzureichende Credits: Das Konto verfügt nicht über genügend Credits für diese Aufgabe (Insufficient funds), oder das Konto hat ein Credit-Limit erreicht.
    • Plan erforderlich: Die Anfrage verwendet nano-banana-pro oder pose_mode mit nano-banana bei einem Plan unterhalb von Pro (Only Pro and above users can use nano-banana-pro, oder Only Pro and above users can use A/T pose feature (requires nano-banana-pro)).

    Überprüfen Sie Ihr Credit-Guthaben und Ihren Plan, 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/v1/text-to-image/:id

Eine Text zu Bild-Aufgabe abrufen

Gibt eine Text zu Bild-Aufgabe anhand ihrer ID zurück.

Request

GET
/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.ai/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1692771650657,
  "started_at": 1692771667037,
  "finished_at": 1692771669037,
  "expires_at": 1692771679037,
  "image_urls": [
    "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
  ]
}

Parameter

  • Name
    id
    Type
    path
    Description

    Die Task-ID aus der Antwort der Erstellung.

Rückgabe

Das Text zu Bild-Aufgabenobjekt.


DELETE/openapi/v1/text-to-image/:id

Löschen einer Text-zu-Bild-Aufgabe

Löscht eine Text zu Bild-Aufgabe dauerhaft, einschließlich ihrer Bilder und Daten. Eine Löschung kann nicht rückgängig gemacht werden.

Request

DELETE
/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/text-to-image/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 Aufgabe mit dem Status PENDING erstattet die Credits, die bei ihrer Erstellung verwendet wurden.

Eine Aufgabe mit dem Status IN_PROGRESS kann nicht gelöscht werden. Die Anfrage gibt 409 Conflict zurück, und die Aufgabe läuft weiter. Meshy erstattet keine Aufgabe, die bereits gestartet wurde, daher würde das Löschen Sie 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 in einem Endstatus (SUCCEEDED, FAILED oder CANCELED) erstattet ihre Credits nicht.

Rückgabewerte

200 OK, wenn die Aufgabe gelöscht wird, oder 409 Conflict, wenn die Aufgabe IN_PROGRESS ist.


GET/openapi/v1/text-to-image

Liste der Text-zu-Bild-Aufgaben abrufen

Gibt eine Liste Ihrer Text-zu-Bild- und Bild-zu-Bild-Aufgaben zurück. Das Feld type jeder Aufgabe gibt an, um welche der beiden es sich handelt.

Request

GET
/openapi/v1/text-to-image
curl https://api.meshy.ai/openapi/v1/text-to-image?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-image",
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1692771650657,
    "started_at": 1692771667037,
    "finished_at": 1692771669037,
    "expires_at": 1692771679037,
    "image_urls": [
      "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
    ]
  }
]

Parameter

  • Name
    page_num
    Type
    integer
    Description

    Die zurückzugebende Seitenzahl. Beginnt bei und ist standardmäßig 1.

  • Name
    page_size
    Type
    integer
    Description

    Die Anzahl der Aufgaben pro Seite, bis zu 100. Standardmäßig 10.

  • 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 Aufgabenobjekten, im gleichen Format wie das Text-zu-Bild-Aufgabenobjekt.


GET/openapi/v1/text-to-image/:id/stream

Streamen eines Text-zu-Bild-Tasks

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

Request

GET
/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.ai/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// These examples are shortened. Each event holds the full task object.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1692771650657,
  "started_at": 1692771667037,
  "finished_at": 1692771669037,
  "expires_at": 1692771679037,
  "image_urls": [
    "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
  ]
}

Parameter

  • Name
    id
    Type
    path
    Description

    Die Task-ID aus der Erstellungsantwort.

Rückgabe

Ein Stream von Text-zu-Bild-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-zu-Bild-Task-Objekt

Ein Text-zu-Bild-Task-Objekt beschreibt eine Bildgenerierung aus einem Text-prompt. Es enthält den Status, den progress und die Bild-URLs, sobald der Task erfolgreich abgeschlossen ist.

Eigenschaften

Example Text to Image Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1692771650657,
  "started_at": 1692771667037,
  "finished_at": 1692771669037,
  "expires_at": 1692771679037,
  "image_urls": [
    "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
  ],
  "task_error": null,

  "consumed_credits": 3
}
  • 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, immer text-to-image.

  • Name
    ai_model
    Type
    string
    Description

    Das vom Task verwendete KI-Modell.

    Mögliche Werte:

    • nano-banana
    • nano-banana-2
    • nano-banana-2-lite
    • nano-banana-2-1
    • nano-banana-pro
    • gpt-image-2
    • gpt-image-2-5-flare
    • gpt-image-2-5-sunburst
    • gpt-image-2-6-flare
    • gpt-image-2-6-sunburst
  • Name
    prompt
    Type
    string
    Description

    Der Text-prompt, mit dem Sie den Task erstellt haben.

  • Name
    status
    Type
    string
    Description

    Der Task-Status, einer von PENDING, IN_PROGRESS, SUCCEEDED, FAILED oder CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Wie weit der Task fortgeschritten ist, als Prozentwert. Er ist 0, bis der Task startet, und 100, wenn er erfolgreich abgeschlossen wird.

  • Name
    created_at
    Type
    timestamp
    Description

    Zeitpunkt der Task-Erstellung, in Unix-Millisekunden.

  • Name
    started_at
    Type
    timestamp
    Description

    Zeitpunkt des Task-Starts, in Unix-Millisekunden. Fehlt, bis der Task startet.

  • Name
    finished_at
    Type
    timestamp
    Description

    Zeitpunkt des Task-Abschlusses, in Unix-Millisekunden. Fehlt, bis der Task abgeschlossen ist.

  • Name
    expires_at
    Type
    timestamp
    Description

    Zeitpunkt, zu dem die Ergebnisse des Tasks ablaufen, in Unix-Millisekunden. Fehlt, bis der Task abgeschlossen ist.

  • 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. Das Feld wird weggelassen, wenn der Wert 0 ist.

  • Name
    image_urls
    Type
    array
    Description

    Download-URLs für die generierten Bilder. Bei generate_multi_view: true enthält das Array eine URL pro Ansicht, üblicherweise drei. Kann Meshy nicht jede Ansicht trennen, gibt es weniger URLs zurück, und der Task gilt dennoch als erfolgreich. Andernfalls enthält es genau eine URL.

  • Name
    task_error
    Type
    object
    Description

    Die Fehlerdetails, falls der Task fehlschlägt. Der Wert ist null, außer wenn der Status FAILED ist. Siehe Fehler.

  • Name
    consumed_credits
    Type
    integer
    Description

    Die Anzahl der vom Task verbrauchten Credits. 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.