Bild-zu-Bild-API

Die Bild-zu-Bild-API ist eine Funktion, mit der Sie Meshys KI-gestützte Bildbearbeitungsfunktionen in Ihre eigene Anwendung integrieren können. Transformieren und bearbeiten Sie vorhandene Bilder mithilfe von Referenzbildern und Text-Prompts mit unseren leistungsstarken KI-Modellen.

POST/openapi/v1/image-to-image

Image-to-Image-Aufgabe erstellen

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

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ärkerer Leistungsfä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 Bildbearbeitungsmodell mit hoher Wiedergabetreue (12 Credits pro Bild)
Name
prompt
Type
string
Erforderlich
Description
Eine Textbeschreibung der Transformation oder Bearbeitung, die Sie auf die Referenzbilder anwenden möchten.
Name
reference_image_urls
Type
array
Erforderlich
Description
Ein Array mit 1 bis 5 Referenzbildern, die für die Bildbearbeitungsaufgabe verwendet werden sollen. Derzeit unterstützen wir die Formate .jpg, .jpeg und .png.
Es gibt zwei Möglichkeiten, jedes Bild bereitzustellen:
- Öffentlich zugängliche URL: Eine URL, die über das öffentliche Internet zugänglich ist.
- Data URI: Eine base64-codierte Data URI des Bildes. Beispiel für eine Data URI: data:image/jpeg;base64,<your base64-encoded image data>.
Name
generate_multi_view
Type
boolean
Standard false
Description
Wenn auf true gesetzt, wird ein Multi-View-Bild generiert, das das Motiv aus mehreren Blickwinkeln zeigt.

Rückgabe

Die Eigenschaft result der Antwort enthält die Aufgaben-id der neu erstellten Image-to-Image-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, reference_image_urls) fehlt.
- Ungültiges Bildformat: Eines oder mehrere Referenzbilder haben nicht unterstützte Formate.
- Nicht erreichbare URL: Eine oder mehrere reference_image_urls konnten nicht heruntergeladen werden.
Name
401 - Unauthorized
Description
Die Authentifizierung ist 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/image-to-image

# Transform a reference image with a text prompt
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "reference_image_urls": [
      "<your publicly accessible image url or base64-encoded data URI>"
    ]
  }'


 ## Using Data URI example
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "reference_image_urls": [
      "data:image/png;base64,${YOUR_BASE64_ENCODED_IMAGE_DATA}"
    ]
  }'

Response

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

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

Eine Image-to-Image-Aufgabe abrufen

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

Parameter

Name
id
Type
path
Description
Eindeutiger Bezeichner der abzurufenden Image-to-Image-Aufgabe.

Rückgabe

Die Antwort enthält das Image-to-Image-Aufgabenobjekt. Weitere Details findest du im Abschnitt Das Image-to-Image-Aufgabenobjekt.

Request

GET

/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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/image-to-image/:id

Eine Image-to-Image-Aufgabe löschen

Dieser endpoint löscht eine Image-to-Image-Aufgabe dauerhaft, einschließlich aller zugehörigen Bilder und Daten. Diese Aktion kann nicht rückgängig gemacht werden.

Pfadparameter

Name
id
Type
path
Description
Die ID der zu löschenden Image-to-Image-Aufgabe.

Rückgabe

Gibt bei Erfolg 200 OK zurück.

Request

DELETE

/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

// Returns 200 Ok on success.

GET/openapi/v1/image-to-image

Image-to-Image-Aufgaben auflisten

Dieser endpoint ermöglicht es Ihnen, eine Liste von Image-to-Image-Aufgaben abzurufen.

Parameter

Name
page_num
Type
integer
Description
Seitenzahl für die Paginierung. Beginnt bei 1 und ist standardmäßig 1.
Name
page_size
Type
integer
Description
Limit für die 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 Image-to-Image-Aufgabenobjekte zurück.

Request

GET

/openapi/v1/image-to-image

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-image",
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "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/image-to-image/:id/stream

Eine Image-to-Image-Aufgabe streamen

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

Parameter

Name
id
Type
path
Description
Eindeutige Kennung für die zu streamende Image-to-Image-Aufgabe.

Rückgabe

Gibt einen Stream von den Image-to-Image-Aufgabenobjekten als Server-Sent Events zurück.

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

Request

GET

/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/image-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": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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 Image to Image Task-Objekt

Das Image to Image Task-Objekt ist eine Arbeitseinheit, die Meshy verfolgt, um aus Referenzbildern und 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. Bei Image-to-Image-Aufgaben ist dies immer image-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 Steuerung der Bildtransformation 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 zu 100.
Name
created_at
Type
timestamp
Description
Zeitstempel, wann die Aufgabe erstellt wurde, in Millisekunden.
Ein Zeitstempel stellt die Anzahl der Millisekunden dar, die seit dem 1. Januar 1970 UTC vergangen sind, gemäß dem RFC 3339-Standard. Beispielsweise 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, 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 vorangehenden 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 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 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 einem Fehler erstattet).

Example Image to Image Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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
}