Text-zu-Bild-API

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

Text zu Bild erzeugt Bilder. Um aus einem Bild ein 3D-Modell zu erstellen, verwende Bild zu 3D. Um aus einem Foto ein Objekt zu erstellen, das du in der Hand halten oder drucken kannst, verwende die Creative-Lab-APIs. Sie erzeugen zunächst ein Prototyp-Bild und bauen daraus anschließend ein 3D-Modell, zum Beispiel einen Schlüsselanhänger, Kühlschrankmagnet, eine Figur, Lampe oder Keycap.

POST/openapi/v1/text-to-image

Erstellen einer Text zu Bild-Aufgabe

Erstellt eine Text zu Bild-Aufgabe. Die Aufgabe läuft im Hintergrund. Wie lange eine Aufgabe normalerweise 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 generiert. 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-pro: das Pro-Modell mit höherer Qualität. Erfordert einen Pro-Plan oder höher. In einem niedrigeren Plan gibt es 402 zurück.
- 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)
Name
prompt
Type
string
Erforderlich
Description
Text, der das zu generierende Bild beschreibt. Eine detaillierte Beschreibung liefert bessere Ergebnisse.
Name
generate_multi_view
Type
boolean
Standard false
Description
Ob ein Mehransicht-Bild generiert werden soll, das das Motiv aus mehreren Blickwinkeln zeigt. Wenn dies true ist, können Sie aspect_ratio nicht senden. Werden beide gesendet, 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 und nano-banana-2-lite: Meshy behält das von Ihnen gewählte Modell bei. Das Bild hat immer das Format 3:4, und Meshy ignoriert aspect_ratio.
- nano-banana und nano-banana-pro: Meshy generiert 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 hat immer das Format 3:4, und Meshy ignoriert aspect_ratio.
- Die GPT Image-Modelle (gpt-image-2, gpt-image-2-5-flare und gpt-image-2-5-sunburst): Meshy behält das von Ihnen gewählte Modell und Ihr aspect_ratio bei.
Name
aspect_ratio
Type
string
Standard 1:1
Description
Das Seitenverhältnis 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 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 jedem beliebigen Hintergrund platzieren 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 gibt an, welches Problem gefunden wurde. Zum Beispiel:
- Fehlender Parameter: Ein erforderlicher Parameter, wie 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 in 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 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, wenn der Task erfolgreich 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,
  "preceding_tasks": 0,
  "image_urls": [
    "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
  ],
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3
}

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, 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-pro
- gpt-image-2
- gpt-image-2-5-flare
- gpt-image-2-5-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 viel des Tasks abgeschlossen ist, als Prozentsatz. Der Wert ist 0, bis der Task beginnt, und 100, wenn er erfolgreich ist.
Name
created_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task erstellt wurde, in Unix-Millisekunden.
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
finished_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task beendet wurde, in Unix-Millisekunden. Der Wert ist 0, bis der Task abgeschlossen ist.
Name
expires_at
Type
timestamp
Description
Zeitpunkt, zu dem die Ergebnisse des Tasks ablaufen, in Unix-Millisekunden.
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
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, normalerweise drei. Wenn Meshy nicht jede Ansicht trennen kann, gibt es weniger zurück, und der Task ist trotzdem erfolgreich. Andernfalls enthält es eine URL.
Name
task_error
Type
object
Description
Die Fehlerdetails, wenn der Task fehlschlägt. 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. Für einen FAILED-Task ist der Wert 0, da Meshy die Credits erstattet, wenn ein Task fehlschlägt.