Bild zu Bild API

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

Dieser Endpunkt erzeugt Bilder. Wenn das Ziel ein Objekt ist, das Sie in der Hand halten oder drucken können — ein Schlüsselanhänger, Kühlschrankmagnet, eine Figur, Lampe oder Keycap aus einem Foto — verwenden Sie die Creative Lab APIs (Prototypbild → 3D-Modell erstellen). Wenn das Ziel ein 3D-Modell dessen ist, was auf dem Bild zu sehen ist, verwenden Sie Bild zu 3D.

POST/openapi/v1/image-to-image

Erstellen einer Bild-zu-Bild-Aufgabe

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

Die Aufgabe läuft im Hintergrund. Wie lange dies in der Regel dauert, erfahren Sie unter Verarbeitungszeiten.

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-2-lite: Lite-Variante von nano-banana-2 (3 Credits pro Bild)
- nano-banana-pro: Pro-Modell mit verbesserter Qualität (9 Credits pro Bild)
- gpt-image-2: OpenAI GPT Image 2, ein hochpräzises Bildbearbeitungsmodell (12 Credits pro Bild)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), ein hochpräzises Bildbearbeitungsmodell (12 Credits pro Bild)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), ein hochpräzises Bildbearbeitungsmodell (12 Credits pro Bild)
Name
prompt
Type
string
Erforderlich
Description
Eine Textbeschreibung der Transformation oder Bearbeitung, die Sie auf die Referenzbilder anwenden möchten.

Nur eines von input_task_id oder reference_image_urls ist erforderlich. Wenn beide angegeben werden, hat input_task_id Priorität.

Name
input_task_id
Type
string
Erforderlich
Description
Die ID einer abgeschlossenen Bildgenerierungsaufgabe, deren Ausgabebilder als Referenzbilder verwendet werden sollen. Diese Aufgabe muss eine der folgenden Aufgaben sein: Text zu Bild oder Bild zu Bild, einschließlich ihrer Mehransicht-Varianten. Außerdem muss sie über die API ausgeführt worden sein und den Status SUCCEEDED haben.
Alle Ausgabebilder der Quellaufgabe werden verwendet. Eine Einzelbildaufgabe liefert 1 Referenzbild; eine Mehransicht-Aufgabe liefert eines pro generierter Ansicht, sodass eine einzelne Task-ID mehrere der 5 Referenzplätze füllen kann.
Die Quellaufgabe muss sich noch innerhalb des Zeitraums der Aufbewahrung von Assets befinden – sobald dieser abläuft, liefert ihre ID 404 zurück.

Name
reference_image_urls
Type
array
Erforderlich
Description
Ein Array mit 1 bis 5 Referenzbildern, die für die Bildbearbeitungsaufgabe verwendet werden sollen. Derzeit werden die Formate .jpg, .jpeg, .png und .webp unterstützt.
Maximale Dateigröße: 20 MB pro Bild.
Es gibt zwei Möglichkeiten, jedes Bild bereitzustellen:
- Öffentlich zugängliche URL: Eine URL, die aus dem öffentlichen Internet zugänglich ist.
- Data URI: Ein base64-kodierter Data URI des Bildes. Beispiel für einen Data URI: data:image/jpeg;base64,<Ihre base64-kodierten Bilddaten>.

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
aspect_ratio
Type
string
Standard 1:1
Description
Legen Sie das Seitenverhältnis des Ausgabebildes fest. Die zulässigen Werte hängen vom ausgewählten ai_model ab:
- nano-banana, nano-banana-2, nano-banana-2-lite, 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 Ausgabebild als transparentes RGBA-PNG mit entferntem Hintergrund zurückgegeben, sodass Sie das Motiv in beliebige Hintergründe einfügen können.

Rückgabewerte

Die Eigenschaft result der Antwort enthält die id der neu erstellten Bild-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, oder es wurde weder reference_image_urls noch input_task_id angegeben.
- Ungültige Eingabeaufgabe: input_task_id muss sich auf eine SUCCEEDED-Aufgabe vom Typ Text zu Bild oder Bild zu Bild beziehen (einschließlich Mehransicht), die noch über Bildausgaben verfügt. Eine Aufgabe eines anderen Typs, eine nicht erfolgreich abgeschlossene Aufgabe oder eine Aufgabe, deren Bilder alle abgelaufen sind, wird abgelehnt.
- Ungültiges Bildformat: Ein oder mehrere Referenzbilder haben ein nicht unterstütztes Format.
- Nicht erreichbare URL: Ein oder mehrere reference_image_urls konnten nicht heruntergeladen werden.
- Bild zu groß: Ein oder mehrere Bilder in reference_image_urls überschreiten 20 MB.
- Ungültiger Parameter: aspect_ratio ist keiner der für das ausgewählte ai_model 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
404 - Not Found
Description
Die input_task_id bezieht sich nicht auf eine Aufgabe, die Ihrem Konto gehört. Eine nicht existierende Aufgabe und eine Aufgabe, die einem anderen Konto gehört, liefern dieselbe Antwort.
Name
429 - Too Many Requests
Description
Sie haben Ihre Ratenbegrenzung ü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}"
    ]
  }'


 ## Chaining from a previous task, instead of passing image URLs
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",
    "input_task_id": "<your Text to Image or Image to Image task id>"
  }'

Response

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

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

Eine Bild-zu-Bild-Aufgabe abrufen

Dieser Endpunkt ermöglicht es Ihnen, eine Bild-zu-Bild-Aufgabe anhand einer gültigen id abzurufen. Weitere Informationen zu den Eigenschaften des Bild-zu-Bild-Aufgabenobjekts finden Sie unter Das Bild-zu-Bild-Aufgabenobjekt.

Parameter

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

Rückgabewerte

Die Antwort enthält das Bild-zu-Bild-Aufgabenobjekt. Weitere Details finden Sie im Abschnitt Das Bild-zu-Bild-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 Bild-zu-Bild-Aufgabe löschen

Dieser Endpunkt löscht eine Bild-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 Bild-zu-Bild-Aufgabe.

Aufgabenstatus

Eine Aufgabe, die sich noch im Status PENDING befindet, wird gelöscht, und die zum Erstellungszeitpunkt verbrauchten Credits werden erstattet.

Eine Aufgabe, die sich bereits IN_PROGRESS befindet, 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, werden nicht erstattet. 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 die Aufgabe 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 sich die Aufgabe im Status IN_PROGRESS befindet.

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

// 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/image-to-image

List Image to Image Tasks

Dieser Endpunkt ermöglicht es Ihnen, eine Liste von Bild-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
Seitengrößenlimit. Standardmäßig 10 Einträge. Maximal erlaubt sind 100 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ückgabewerte

Gibt eine paginierte Liste von Die Bild-zu-Bild-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

Streamen einer Bild-zu-Bild-Aufgabe

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

Parameter

Name
id
Type
path
Description
Eindeutiger Bezeichner der Bild-zu-Bild-Aufgabe, die gestreamt werden soll.

Rückgabewerte

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

Bei Aufgaben mit dem Status PENDING oder IN_PROGRESS enthält der Antwort-Stream 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 einem Text-prompt-Input ein Bild zu generieren. Das Objekt verfügt über die folgenden Eigenschaften:

Eigenschaften

Name
id
Type
string
Description
Eindeutige Kennung für den Task. Obwohl wir als Implementierungsdetail eine k-sortierbare UUID für Task-IDs verwenden, solltest du keine Annahmen über das Format der ID treffen.
Name
type
Type
string
Description
Der Typ des Bildgenerierungs-Tasks. Für Image-to-Image-Tasks ist dies immer image-to-image.
Name
ai_model
Type
string
Description
Das für diesen Task verwendete KI-Modell. Mögliche Werte sind nano-banana, nano-banana-2, nano-banana-2-lite, 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 Steuerung der Bildtransformation verwendet wurde.
Name
status
Type
string
Description
Status des Tasks. Mögliche Werte sind einer von PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Fortschritt des Tasks. Wenn der Task noch nicht gestartet wurde, ist diese Eigenschaft 0. Sobald der Task erfolgreich war, wird sie zu 100.
Name
created_at
Type
timestamp
Description
Zeitstempel der Erstellung des Tasks, in Millisekunden.
Ein Zeitstempel repräsentiert die Anzahl der Millisekunden, die seit dem 1. Januar 1970 UTC vergangen sind, gemäß dem Standard RFC 3339. Beispielsweise 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 des Starts des Tasks, in Millisekunden. Wenn der Task noch nicht gestartet wurde, ist diese Eigenschaft 0.
Name
finished_at
Type
timestamp
Description
Zeitstempel des Abschlusses des Tasks, in Millisekunden. Wenn der Task noch nicht abgeschlossen ist, ist diese Eigenschaft 0.
Name
expires_at
Type
timestamp
Description
Zeitstempel, wann das Taskergebnis abläuft, in Millisekunden.
Name
preceding_tasks
Type
integer
Description
Die Anzahl der vorangehenden Tasks.
Der Wert dieses Felds ist nur dann aussagekräftig, wenn der Taskstatus PENDING ist.
Name
image_urls
Type
array
Description
Ein Array mit 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 Tasks. Siehe Fehler für die vollständige Referenz des task_error-Objekts.
Name
consumed_credits
Type
integer
Description
Die Anzahl der von diesem Task verbrauchten Credits. Vorhanden, wenn der Taskstatus PENDING, IN_PROGRESS oder SUCCEEDED ist. Gibt 0 für FAILED-Tasks zurück (Credits werden bei einem Fehlschlag 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
}