Text-zu-Bild-API

Die Text-zu-Bild-API ist eine Funktion, mit der du Meshys KI-Bildgenerierungsfunktionen in deine eigene Anwendung integrieren kannst. Erzeuge hochwertige Bilder aus Text-Prompts mit unseren leistungsstarken KI-Modellen.

POST/openapi/v1/text-to-image

Eine Text-zu-Bild-Aufgabe erstellen

Dieser endpoint ermöglicht es Ihnen, eine neue Text-zu-Bild-Aufgabe zu erstellen. Siehe Das Text-zu-Bild-Aufgabenobjekt, um zu sehen, welche Eigenschaften im Text-zu-Bild-Aufgabenobjekt enthalten sind.

Parameter

Name
ai_model
Type
string
Erforderlich
Description
ID des Modells, das für die Bilderzeugung verwendet werden soll.
Verfügbare Werte:
- nano-banana: Standardmodell (3 Credits pro Bild)
- nano-banana-2: Ausgewogenes Modell mit stärkerer Fähigkeit als der Standard (6 Credits pro Bild)
- nano-banana-pro: Pro-Modell mit verbesserter Qualität (9 Credits pro Bild)
- gpt-image-2: OpenAI GPT Image 2, ein hochauflösendes Bildmodell mit eingeschränkter Unterstützung für Seitenverhältnisse (9 Credits pro Bild)
Name
prompt
Type
string
Erforderlich
Description
Eine Textbeschreibung des Bildes, das Sie generieren möchten. Seien Sie für beste Ergebnisse möglichst beschreibend.
Name
generate_multi_view
Type
boolean
Standard false
Description
Wenn auf true gesetzt, wird ein Multi-View-Bild generiert, das das Motiv aus mehreren Winkeln zeigt.
Wenn generate_multi_view true ist, kann der Parameter aspect_ratio nicht gesetzt werden.
Name
pose_mode
Type
string
Description
Geben Sie den Pose-Modus für die Charaktergenerierung an. Wenn ausgelassen, wird das Bild ohne Pose-Voreinstellungen generiert.
Verfügbare Werte: a-pose, t-pose
Name
aspect_ratio
Type
string
Standard 1:1
Description
Geben Sie das Seitenverhältnis des generierten Bildes an. Zulässige Werte hängen vom ausgewählten ai_model ab:
- nano-banana, nano-banana-2, nano-banana-pro: 1:1, 16:9, 9:16, 4:3, 3:4
- gpt-image-2: nur 1:1, 3:2, 2:3
Verfügbare Werte:
- 1:1: Quadratisches Format
- 16:9: Breitbild-Querformat (nicht unterstützt von gpt-image-2)
- 9:16: Breitbild-Hochformat (nicht unterstützt von gpt-image-2)
- 4:3: Standard-Querformat (nicht unterstützt von gpt-image-2)
- 3:4: Standard-Hochformat (nicht unterstützt von gpt-image-2)
- 3:2: Querformat (nur unterstützt von gpt-image-2)
- 2:3: Hochformat (nur unterstützt von gpt-image-2)

Rückgabe

Die Eigenschaft result der Antwort enthält die Aufgaben-id der neu erstellten Text-zu-Bild-Aufgabe.

Fehlermodi

Name
400 - Bad Request
Description
Die Anfrage war nicht akzeptabel. Häufige Ursachen:
- Fehlender Parameter: Ein erforderlicher Parameter (z. B. ai_model, prompt) fehlt.
- Ungültiger Parameter: ai_model oder aspect_ratio ist keiner der zulässigen Werte.
- Konflikt: generate_multi_view und aspect_ratio können nicht gleichzeitig verwendet werden.
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/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"
}

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

Eine Text-zu-Bild-Aufgabe abrufen

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

Parameter

Name
id
Type
path
Description
Eindeutige Kennung der abzurufenden Text-zu-Bild-Aufgabe.

Rückgabe

Die Antwort enthält das Text-zu-Bild-Aufgabenobjekt. Sieh im Abschnitt Das Text-zu-Bild-Aufgabenobjekt für Details nach.

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=***"
  ]
}

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

Text-zu-Bild-Aufgabe löschen

Dieser endpoint löscht eine Text-zu-Bild-Aufgabe dauerhaft, einschließlich aller zugehörigen Bilder und Daten. Diese Aktion ist unwiderruflich.

Pfadparameter

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

Rückgabe

Gibt bei Erfolg 200 OK zurück.

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

// Returns 200 Ok on success.

GET/openapi/v1/text-to-image

Text-zu-Bild-Aufgaben auflisten

Dieser endpoint ermöglicht es Ihnen, eine Liste von Text-zu-Bild-Aufgaben abzurufen.

Parameter

Name
page_num
Type
integer
Description
Seitennummer für die Paginierung. Beginnt und ist standardmäßig 1.
Name
page_size
Type
integer
Description
Begrenzung der Seitengröße. Standardmäßig 10 Elemente. 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-zu-Bild-Aufgabenobjekte zurück.

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=***"
    ]
  }
]

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

Text-zu-Bild-Aufgabe streamen

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

Parameter

Name
id
Type
path
Description
Eindeutige Kennung der zu streamenden Text-zu-Bild-Aufgabe.

Rückgaben

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

Für PENDING- oder IN_PROGRESS-Aufgaben enthält der Antwortstream nur die erforderlichen Felder progress und status.

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.
// 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",
  "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=***"
  ]
}

Das Text-zu-Bild-Aufgabenobjekt

Das Text-zu-Bild-Aufgabenobjekt ist eine Arbeitseinheit, die Meshy verfolgt, um aus einer Text-Prompt-Eingabe ein Bild zu generieren. Das Objekt hat die folgenden Eigenschaften:

Eigenschaften

Name
id
Type
string
Description
Eindeutige Kennung für die Aufgabe. Obwohl wir als Implementierungsdetail eine k-sortierbare UUID für Aufgaben-IDs verwenden, sollten Sie keine Annahmen über das Format der ID treffen.
Name
type
Type
string
Description
Der Typ der Bildgenerierungsaufgabe. Für Text-to-Image-Aufgaben ist dies immer text-to-image.
Name
ai_model
Type
string
Description
Das für diese Aufgabe verwendete KI-Modell. Mögliche Werte sind nano-banana, nano-banana-2, nano-banana-pro oder gpt-image-2.
Name
prompt
Type
string
Description
Der Text-Prompt, der zur Generierung des Bildes verwendet wurde.
Name
status
Type
string
Description
Status der Aufgabe. Mögliche Werte sind einer von PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Fortschritt der Aufgabe. Wenn die Aufgabe noch nicht gestartet wurde, ist diese Eigenschaft 0. Sobald die Aufgabe erfolgreich abgeschlossen wurde, wird dieser Wert zu 100.
Name
created_at
Type
timestamp
Description
Zeitstempel, wann die Aufgabe erstellt wurde, in Millisekunden.
Ein Zeitstempel stellt die Anzahl der seit dem 1. Januar 1970 UTC verstrichenen Millisekunden dar, gemäß dem RFC 3339-Standard. Zum Beispiel wird Freitag, 1. September 2023 12:00:00 PM GMT als 1693569600000 dargestellt. Dies gilt für alle Zeitstempel in der Meshy API.
Name
started_at
Type
timestamp
Description
Zeitstempel, wann die Aufgabe gestartet wurde, in Millisekunden. Wenn die Aufgabe noch nicht gestartet wurde, ist diese Eigenschaft 0.
Name
finished_at
Type
timestamp
Description
Zeitstempel, wann die Aufgabe abgeschlossen wurde, in Millisekunden. Wenn die Aufgabe noch nicht abgeschlossen wurde, ist diese Eigenschaft 0.
Name
expires_at
Type
timestamp
Description
Zeitstempel, wann das Aufgabenergebnis abläuft, in Millisekunden.
Name
preceding_tasks
Type
integer
Description
Die Anzahl der vorhergehenden Aufgaben.
Der Wert dieses Feldes ist nur aussagekräftig, wenn der Aufgabenstatus PENDING ist.
Name
image_urls
Type
array
Description
Ein Array herunterladbarer URLs zu den generierten Bildern. Wenn generate_multi_view aktiviert ist, enthält dieses Array drei Bild-URLs, die unterschiedliche Blickwinkel darstellen. Andernfalls enthält es eine einzelne Bild-URL.
Name
task_error
Type
object
Description
Fehlerdetails für fehlgeschlagene Aufgaben. Siehe Fehler für die vollständige task_error-Objektreferenz.
Name
consumed_credits
Type
integer
Description
Die Anzahl der durch diese Aufgabe verbrauchten Credits. Vorhanden, wenn der Aufgabenstatus PENDING, IN_PROGRESS oder SUCCEEDED ist. Gibt 0 für FAILED-Aufgaben zurück (Credits werden bei einem Fehlschlag erstattet).

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
}