Text zu Bild API

Die Text zu Bild API ist eine Funktion, mit der Sie die KI-Bildgenerierungsfunktionen von Meshy in Ihre eigene Anwendung integrieren können. Erzeugen Sie hochwertige Bilder aus Textprompts mithilfe unserer leistungsstarken KI-Modelle.

POST/openapi/v1/text-to-image

Erstellen einer Text-zu-Bild-Aufgabe

Dieser Endpunkt ermöglicht es Ihnen, eine neue Text-zu-Bild-Aufgabe zu erstellen. Weitere Informationen dazu, welche Eigenschaften im Text-zu-Bild-Aufgabenobjekt enthalten sind, finden Sie unter Das Text-zu-Bild-Aufgabenobjekt.

Parameter

  • Name
    ai_model
    Type
    string
    Erforderlich
    Description

    ID des Modells, das für die Bildgenerierung verwendet werden soll.

    Verfügbare Werte:

    • nano-banana: Standardmodell (3 Credits pro Bild)
    • nano-banana-2: Ausgewogenes Modell mit stärkeren Fähigkeiten als das Standardmodell (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 (9 Credits pro Bild)
    • gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), ein hochauflösendes Bildmodell (9 Credits pro Bild)
    • gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), ein hochauflösendes Bildmodell (9 Credits pro Bild)
  • Name
    prompt
    Type
    string
    Erforderlich
    Description

    Eine Textbeschreibung des Bildes, das Sie generieren möchten. Beschreiben Sie es möglichst detailliert, um die besten Ergebnisse zu erzielen.

  • Name
    generate_multi_view
    Type
    boolean
    Standard false
    Description

    Wenn auf true gesetzt, wird ein Mehransicht-Bild generiert, das das Motiv aus mehreren Blickwinkeln zeigt.

    Wenn generate_multi_view auf true gesetzt ist, kann der Parameter aspect_ratio nicht gesetzt werden.

  • Name
    pose_mode
    Type
    string
    Description

    Legt den pose_mode für die Charaktergenerierung fest. Wenn nicht angegeben, wird das Bild ohne voreingestellte Posen generiert.

    Verfügbare Werte: a-pose, t-pose

  • Name
    aspect_ratio
    Type
    string
    Standard 1:1
    Description

    Legt das Seitenverhältnis des generierten Bildes fest. Die zulässigen Werte hängen vom gewä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, gpt-image-2-5-flare, gpt-image-2-5-sunburst: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3

    Verfügbare Werte:

    • 1:1: Quadratisches Format
    • 16:9: Breitbild-Querformat
    • 9:16: Breitbild-Hochformat
    • 4:3: Standard-Querformat
    • 3:4: Standard-Hochformat
    • 3:2: Querformat (nur von den GPT-Image-Modellen unterstützt)
    • 2:3: Hochformat (nur von den GPT-Image-Modellen unterstützt)
  • Name
    remove_background
    Type
    boolean
    Standard false
    Description

    Wenn auf true gesetzt, wird das generierte Bild als transparentes RGBA-PNG mit entferntem Hintergrund zurückgegeben, sodass Sie das Motiv mit jedem beliebigen Hintergrund kombinieren können.

Rückgabewerte

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

Fehlerfälle

  • 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 entspricht keinem der zulässigen Werte.
    • Konflikt: generate_multi_view und aspect_ratio können nicht gleichzeitig verwendet werden.
  • Name
    401 - Unauthorized
    Description

    Die Authentifizierung ist fehlgeschlagen. Bitte überprüfen Sie Ihren API-Schlüssel.

  • Name
    402 - Payment Required
    Description

    Unzureichende Credits, um diese Aufgabe auszuführen.

  • Name
    429 - Too Many Requests
    Description

    Sie haben Ihre Ratenbegrenzung ü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

Text zu Bild-Task abrufen

Dieser Endpunkt ermöglicht es Ihnen, einen Text zu Bild-Task anhand einer gültigen Task-id abzurufen. Weitere Informationen zu den Eigenschaften des Text zu Bild-Task-Objekts finden Sie unter Das Text zu Bild-Task-Objekt.

Parameter

  • Name
    id
    Type
    path
    Description

    Eindeutige Kennung für den abzurufenden Text zu Bild-Task.

Rückgabewerte

Die Antwort enthält das Text zu Bild-Task-Objekt. Weitere Details finden Sie im Abschnitt Das Text zu Bild-Task-Objekt.

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

Eine Text-zu-Bild-Aufgabe löschen

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

Pfadparameter

  • Name
    id
    Type
    path
    Description

    Die ID der zu löschenden Text zu Bild-Aufgabe.

Aufgabenstatus

Eine Aufgabe, die noch PENDING ist, wird gelöscht, und die bei der Erstellung verbrauchten Credits werden erstattet.

Eine Aufgabe, die bereits IN_PROGRESS ist, kann nicht gelöscht werden: Die Anfrage wird mit 409 Conflict abgelehnt, und die Aufgabe läuft weiter. Credits für eine Aufgabe, die der Worker bereits gestartet hat, sind nicht erstattungsfähig. Ein Löschen mitten im Ablauf würde Sie daher sowohl die Credits als auch das Ergebnis kosten. Warten Sie, bis der Status SUCCEEDED, FAILED oder CANCELED erreicht ist, und löschen Sie sie dann.

Eine Aufgabe in einem Endzustand (SUCCEEDED, FAILED oder CANCELED) wird ohne Erstattung gelöscht.

Rückgabewerte

Gibt bei Erfolg 200 OK zurück, oder 409 Conflict, wenn die Aufgabe IN_PROGRESS ist.

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 is left 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."
}
GET/openapi/v1/text-to-image

Text-zu-Bild-Aufgaben auflisten

Dieser Endpunkt 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 bei und ist standardmäßig 1.

  • Name
    page_size
    Type
    integer
    Description

    Begrenzung der Seitengröße. Standardmäßig 10 Elemente. Maximal zulässig sind 100 Elemente.

  • Name
    sort_by
    Type
    string
    Description

    Feld, nach dem sortiert werden soll. Verfügbare Werte:

    • +created_at: Sortierung nach Erstellungszeit in aufsteigender Reihenfolge.
    • -created_at: Sortierung nach Erstellungszeit in absteigender Reihenfolge.

Rückgabewerte

Gibt eine paginierte Liste von The Text to Image Task Objects 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

Einen Text-zu-Bild-Task streamen

Dieser Endpunkt streamt Echtzeit-Updates für einen Text-zu-Bild-Task mittels Server-Sent Events (SSE).

Parameter

  • Name
    id
    Type
    path
    Description

    Eindeutige Kennung für den zu streamenden Text-zu-Bild-Task.

Rückgabewerte

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

Bei Tasks mit dem Status PENDING oder IN_PROGRESS enthält der Antwort-Stream nur die notwendigen 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=***"
  ]
}

The Text to Image Task Object

Das Text to Image Task Object ist eine Arbeitseinheit, die Meshy verwaltet, um ein Bild aus einer Eingabe als Text-prompt zu generieren. Das Objekt hat die folgenden Eigenschaften:

Properties

  • Name
    id
    Type
    string
    Description

    Eindeutige Kennung der Aufgabe. Obwohl wir als Implementierungsdetail eine k-sortierbare UUID für Task-IDs verwenden, sollten Sie keine Annahmen über das Format der id treffen.

  • Name
    type
    Type
    string
    Description

    Der Typ der Bildgenerierungsaufgabe. Bei Text to Image Tasks 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, gpt-image-2, gpt-image-2-5-flare oder gpt-image-2-5-sunburst.

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

  • Name
    created_at
    Type
    timestamp
    Description

    Zeitstempel der Erstellung der Aufgabe, in Millisekunden.

    Ein Zeitstempel repräsentiert die Anzahl der Millisekunden seit dem 1. Januar 1970 UTC, gemäß dem Standard RFC 3339. Zum Beispiel wird Freitag, 1. September 2023, 12:00:00 Uhr GMT als 1693569600000 dargestellt. Dies gilt für alle Zeitstempel in der Meshy API.

  • Name
    started_at
    Type
    timestamp
    Description

    Zeitstempel des Starts der Aufgabe, in Millisekunden. Wenn die Aufgabe noch nicht gestartet wurde, ist diese Eigenschaft 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Zeitstempel des Abschlusses der Aufgabe, in Millisekunden. Wenn die Aufgabe noch nicht abgeschlossen wurde, ist diese Eigenschaft 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Zeitstempel, wann das Ergebnis der Aufgabe abläuft, in Millisekunden.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Die Anzahl der vorangehenden Aufgaben.

    Der Wert dieses Feldes ist nur dann aussagekräftig, wenn der Aufgabenstatus PENDING ist.

  • Name
    image_urls
    Type
    array
    Description

    Ein Array von herunterladbaren URLs zu den generierten Bildern. Wenn generate_multi_view aktiviert ist, enthält dieses Array drei Bild-URLs, die unterschiedliche Betrachtungswinkel 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 Referenz des task_error-Objekts.

  • Name
    consumed_credits
    Type
    integer
    Description

    Die Anzahl der von dieser Aufgabe verbrauchten Credits. Vorhanden, wenn der Aufgabenstatus PENDING, IN_PROGRESS oder SUCCEEDED ist. Gibt 0 für FAILED-Aufgaben zurück (Credits werden bei 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
}