Text zu Bild API

Die Text zu Bild API ist eine Funktion, die es Ihnen ermöglicht, die KI-Bilderzeugungsfähigkeiten von Meshy in Ihre eigene Anwendung zu integrieren. Erzeugen Sie hochwertige Bilder aus Texteingaben mit unseren leistungsstarken KI-Modellen.

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. 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 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 (9 Credits pro Bild)
Name
prompt
Type
string
Erforderlich
Description
Eine Textbeschreibung des Bildes, das Sie erzeugen möchten. Seien Sie beschreibend für beste Ergebnisse.
Name
generate_multi_view
Type
boolean
Standard false
Description
Wenn auf true gesetzt, wird ein Mehransicht-Bild erzeugt, das das Motiv aus mehreren Blickwinkeln zeigt.
Wenn generate_multi_view auf true gesetzt ist, kann der aspect_ratio Parameter nicht gesetzt werden.
Name
pose_mode
Type
string
Description
Geben Sie den Pose-Modus für die Charaktererzeugung an. Wenn weggelassen, wird das Bild ohne Pose-Voreinstellungen erzeugt.
Verfügbare Werte: a-pose, t-pose
Name
aspect_ratio
Type
string
Standard 1:1
Description
Geben Sie das Seitenverhältnis des erzeugten Bildes an. Erlaubte 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: 1:1, 16:9, 9:16, 3:2, 2:3
Verfügbare Werte:
- 1:1: Quadratformat
- 16:9: Breitbild-Landschaft
- 9:16: Breitbild-Porträt
- 4:3: Standard-Landschaft (nicht unterstützt von gpt-image-2)
- 3:4: Standard-Porträt (nicht unterstützt von gpt-image-2)
- 3:2: Landschaft (nur unterstützt von gpt-image-2)
- 2:3: Porträt (nur unterstützt von gpt-image-2)
Name
remove_background
Type
boolean
Standard false
Description
Wenn auf true gesetzt, wird das erzeugte Bild als transparentes RGBA PNG mit entferntem Hintergrund zurückgegeben, sodass Sie das Motiv auf jeden Hintergrund zusammensetzen können.

Rückgaben

Die result Eigenschaft 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 nicht einer der erlaubten 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-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.

Anfrage

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

Antwort

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

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

Abrufen einer Text zu Bild Aufgabe

Dieser Endpunkt ermöglicht es Ihnen, eine Text zu Bild Aufgabe mit 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
Eindeutiger Bezeichner für die abzurufende Text zu Bild Aufgabe.

Rückgabe

Die Antwort enthält das Text zu Bild Aufgabenobjekt. Überprüfen Sie den Abschnitt Das Text zu Bild Aufgabenobjekt für Details.

Anfrage

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

Antwort

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

Löschen einer Text zu Bild Aufgabe

Dieser Endpunkt löscht dauerhaft eine Text zu Bild Aufgabe, 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ückgaben

Gibt 200 OK bei Erfolg zurück.

Anfrage

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

Antwort

// Returns 200 Ok on success.

GET/openapi/v1/text-to-image

Liste der Text zu Bild Aufgaben

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

Parameter

Name
page_num
Type
integer
Description
Seitenzahl für die Paginierung. Beginnt und standardmäßig 1.
Name
page_size
Type
integer
Description
Begrenzung der Seitengröße. Standardmäßig 10 Einträge. Maximal erlaubt sind 50 Einträge.
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ückgaben

Gibt eine paginierte Liste von The Text to Image Task Objects zurück.

Anfrage

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

Antwort

[
  {
    "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

Streamen einer Text zu Bild Aufgabe

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

Parameter

Name
id
Type
path
Description
Eindeutiger Bezeichner für die Text zu Bild Aufgabe, die gestreamt werden soll.

Rückgaben

Gibt einen Stream von Die Text zu Bild Aufgaben Objekte als Server-Sent Events zurück.

Für PENDING oder IN_PROGRESS Aufgaben wird der Antwortstream nur die notwendigen progress und status Felder enthalten.

Anfrage

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

Antwortstream

// 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 ein Bild aus einer Text-Prompt-Eingabe zu generieren. Das Objekt hat die folgenden Eigenschaften:

Eigenschaften

Name
id
Type
string
Description
Eindeutiger Bezeichner für die Aufgabe. Während wir eine k-sortierbare UUID für Aufgaben-IDs als Implementierungsdetail verwenden, sollten Sie keine Annahmen über das Format der ID machen.
Name
type
Type
string
Description
Der Typ der Bildgenerierungsaufgabe. Für Text zu Bild Aufgaben wird dies immer text-to-image sein.
Name
ai_model
Type
string
Description
Das AI-Modell, das für diese Aufgabe verwendet wird. 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 verwendet wurde, um das Bild zu generieren.
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 ist, wird diese Eigenschaft 0 sein. Sobald die Aufgabe erfolgreich abgeschlossen ist, wird dies 100 sein.
Name
created_at
Type
timestamp
Description
Zeitstempel, wann die Aufgabe erstellt wurde, in Millisekunden.
Ein Zeitstempel repräsentiert die Anzahl der Millisekunden, die seit dem 1. Januar 1970 UTC vergangen sind, gemäß dem RFC 3339 Standard. Zum Beispiel wird Freitag, der 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, wann die Aufgabe gestartet wurde, in Millisekunden. Wenn die Aufgabe noch nicht gestartet ist, wird diese Eigenschaft 0 sein.
Name
finished_at
Type
timestamp
Description
Zeitstempel, wann die Aufgabe abgeschlossen wurde, in Millisekunden. Wenn die Aufgabe noch nicht abgeschlossen ist, wird diese Eigenschaft 0 sein.
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 vorhergehenden Aufgaben.
Der Wert dieses Feldes ist nur dann sinnvoll, 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 verschiedene 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 task_error Objektreferenz.
Name
consumed_credits
Type
integer
Description
Die Anzahl der Credits, die von dieser Aufgabe verbraucht wurden. Vorhanden, wenn der Aufgabenstatus PENDING, IN_PROGRESS oder SUCCEEDED ist. Gibt 0 für FAILED Aufgaben zurück (Credits werden bei einem Fehler zurückerstattet).

Beispiel Text zu Bild Aufgabenobjekt

{
  "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
}