Bild zu Bild API

Bearbeiten und transformieren Sie Bilder direkt in Ihrer eigenen Anwendung. Senden Sie Referenzbilder und einen Text-prompt, und die KI-Modelle von Meshy generieren daraus ein neues Bild.

Bild zu Bild erzeugt Bilder. Um aus einem Bild ein 3D-Modell zu erstellen, verwenden Sie Bild zu 3D. Um aus einem Foto ein Objekt zu machen, das Sie in der Hand halten oder drucken können, verwenden Sie die Creative Lab APIs. Diese erzeugen zunächst ein Prototyp-Bild und bauen daraus anschließend ein 3D-Modell, zum Beispiel einen Schlüsselanhänger, Kühlschrankmagnet, eine Figur, Lampe oder einen Keycap.

POST/openapi/v1/image-to-image

Erstellen einer Bild-zu-Bild-Aufgabe

Erstellt eine Bild-zu-Bild-Aufgabe. Die Aufgabe läuft im Hintergrund. Wie lange eine Aufgabe in der Regel dauert, erfahren Sie unter Verarbeitungszeiten.

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

Parameter

Name
ai_model
Type
string
Erforderlich
Description
Das KI-Modell, das das Bild generiert. Die Preise unterscheiden sich je nach Modell. Siehe Preise.
Verfügbare Werte:
- nano-banana: das Standardmodell
- nano-banana-2: leistungsfähiger als nano-banana
- nano-banana-2-lite: eine Lite-Version von nano-banana-2
- nano-banana-pro: das Pro-Modell mit höherer Qualität. Es erfordert einen Pro-Plan oder höher. Bei einem niedrigeren Plan wird 402 zurückgegeben.
- gpt-image-2: OpenAI GPT Image 2
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst)
Name
prompt
Type
string
Erforderlich
Description
Text, der die Bearbeitung oder Transformation beschreibt, die auf die Referenzbilder angewendet werden soll.

Name
input_task_id
Type
string
Erforderlich
Description
Erforderlich, sofern Sie nicht reference_image_urls senden. Die ID einer Text-zu-Bild- oder Bild-zu-Bild-Aufgabe, deren Bilder als Referenzen verwendet werden sollen, einschließlich Mehransicht-Aufgaben. Die Aufgabe muss eine sein, die Sie mit der API erstellt haben und die den Status SUCCEEDED hat.
Meshy verwendet jedes von der Aufgabe erzeugte Bild. Eine Einzelbild-Aufgabe liefert ein Referenzbild, und eine Mehransicht-Aufgabe liefert eines pro Ansicht. Eine einzelne Aufgaben-ID kann also mehrere der fünf Referenzplätze füllen.
Die Aufgabe muss sich noch innerhalb des Aufbewahrungszeitraums für Assets befinden. Nach Ablauf gibt ihre ID 404 zurück.

Name
reference_image_urls
Type
array
Erforderlich
Description
Erforderlich, sofern Sie nicht input_task_id senden. Ein bis fünf Referenzbilder zum Bearbeiten, jeweils eine öffentliche URL oder ein Data URI, zum Beispiel data:image/jpeg;base64,<your base64-encoded image data>. Ein leeres Array oder mehr als fünf Bilder geben 400 zurück. Wenn Sie beides senden, verwendet Meshy input_task_id.
Jedes Bild muss eine .jpg-, .jpeg-, .png- oder .webp-Datei von höchstens 20 MB und mindestens 32 × 32 Pixel sein.

Name
generate_multi_view
Type
boolean
Standard false
Description
Gibt an, ob ein Mehransicht-Bild erzeugt werden soll, das das Motiv aus mehreren Blickwinkeln zeigt. Bei true können Sie aspect_ratio nicht senden. Werden beide gesendet, wird 400 zurückgegeben.
Name
aspect_ratio
Type
string
Standard 1:1
Description
Das Seitenverhältnis des Ausgabebildes. Welche Werte Sie senden können, hängt von ai_model ab.
Verfügbare Werte:
- 1:1: quadratisch
- 16:9: Breitbild-Querformat
- 9:16: Breitbild-Hochformat
- 4:3: Standard-Querformat
- 3:4: Standard-Hochformat
- 3:2: Querformat, nur GPT-Image-Modelle
- 2:3: Hochformat, nur GPT-Image-Modelle
Die GPT-Image-Modelle sind gpt-image-2, gpt-image-2-5-flare und gpt-image-2-5-sunburst. Bei einem nano-banana-Modell geben 3:2 und 2:3 400 zurück.
Name
remove_background
Type
boolean
Standard false
Description
Gibt an, ob der Hintergrund entfernt werden soll. Bei true gibt Meshy das Ausgabebild als transparentes RGBA-PNG zurück, sodass Sie das Motiv auf einen beliebigen Hintergrund platzieren können.

Rückgabewerte

Das Feld result der Antwort enthält die ID der neuen Bild-zu-Bild-Aufgabe.

Fehlermodi

Name
400 - Bad Request
Description
Die Anfrage kann nicht ausgeführt werden. Die Fehlermeldung gibt an, welches Problem gefunden wurde. Zum Beispiel:
- Fehlender Parameter: Ein erforderlicher Parameter, wie ai_model oder prompt, fehlt, oder es wurde weder reference_image_urls noch input_task_id gesendet.
- Ungültige Eingabeaufgabe: input_task_id verweist nicht auf eine verwendbare Aufgabe. Es muss sich um eine SUCCEEDED Text-zu-Bild- oder Bild-zu-Bild-Aufgabe handeln, Mehransicht eingeschlossen, die noch eine Bildausgabe hat. Meshy lehnt eine Aufgabe eines anderen Typs, eine nicht erfolgreiche Aufgabe und eine Aufgabe, deren Bilder alle abgelaufen sind, ab.
- Ungültiges Bildformat: Ein oder mehrere Referenzbilder liegen nicht in einem unterstützten Format vor.
- Nicht erreichbare URL: Meshy kann ein oder mehrere reference_image_urls-Bilder nicht herunterladen.
- Bild zu groß: Ein oder mehrere reference_image_urls-Bilder sind größer als 20 MB.
- Bild zu klein: Ein oder mehrere reference_image_urls-Bilder sind kleiner als 32 × 32 Pixel.
- Ungültiger Parameter: aspect_ratio ist keiner der Werte, die das ausgewählte ai_model unterstützt.
- Konflikt: Die Anfrage sendet aspect_ratio zusammen mit generate_multi_view: true.
Korrigieren Sie die Anfrage und senden Sie sie erneut. Siehe Fehler.
Name
401 - Unauthorized
Description
Der API-Schlüssel fehlt oder ist ungültig. Überprüfen Sie den Authorization-Header.
Name
402 - Payment Required
Description
Das Konto kann diese Aufgabe nicht ausführen. Zum Beispiel:
- Kostenloser Plan: Das Erstellen einer Aufgabe erfordert einen kostenpflichtigen Plan. Aktualisieren Sie Ihren Plan in Ihren Abonnementeinstellungen und versuchen Sie es erneut.
- Unzureichende Credits: Das Konto verfügt nicht über genügend Credits für diese Aufgabe, oder das Konto hat ein Credit-Limit erreicht.
- Plan erforderlich: Die Anfrage verwendet nano-banana-pro mit einem Plan unterhalb von Pro.
Überprüfen Sie Ihr Credit-Guthaben und Ihren Plan, und versuchen Sie es dann erneut.
Name
404 - Not Found
Description
input_task_id entspricht keiner Aufgabe in Ihrem Konto. Eine nicht existierende Aufgabe und eine Aufgabe, die einem anderen Konto gehört, geben dieselbe Antwort zurück. Überprüfen Sie die ID.
Name
429 - Too Many Requests
Description
Sie haben Ihre Ratenbegrenzung überschritten. Warten Sie und versuchen Sie es dann erneut. Siehe Ratenbegrenzungen.

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

Eine Image-to-Image-Aufgabe abrufen

Gibt eine Image-to-Image-Aufgabe anhand ihrer ID zurück.

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

Parameter

Name
id
Type
path
Description
Die Task-ID aus der Antwort beim Erstellen.

Rückgabewerte

Das Image-to-Image-Task-Objekt.

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

Eine Bild-zu-Bild-Aufgabe löschen

Löscht eine Bild-zu-Bild-Aufgabe dauerhaft, einschließlich ihrer Bilder und Daten. Das Löschen kann nicht rückgängig gemacht werden.

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

Pfadparameter

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

Aufgabenstatus

Das Löschen einer PENDING-Aufgabe erstattet die Credits zurück, die bei ihrer Erstellung verwendet wurden.

Eine IN_PROGRESS-Aufgabe kann nicht gelöscht werden. Die Anfrage gibt 409 Conflict zurück, und die Aufgabe läuft weiter. Meshy erstattet keine Aufgabe, die bereits begonnen hat, sodass das Löschen Sie sowohl die Credits als auch das Ergebnis kosten würde. Warten Sie, bis sie SUCCEEDED, FAILED oder CANCELED erreicht, und löschen Sie sie dann.

Das Löschen einer Aufgabe in einem endgültigen Status (SUCCEEDED, FAILED oder CANCELED) erstattet ihre Credits nicht zurück.

Rückgabewerte

200 OK, wenn die Aufgabe gelöscht wurde, oder 409 Conflict, wenn die Aufgabe IN_PROGRESS ist.

GET/openapi/v1/image-to-image

Image zu Bild Aufgaben auflisten

Gibt eine Liste deiner Bild zu Bild- und Text zu Bild-Aufgaben zurück. Das Feld type jeder Aufgabe gibt an, um welche der beiden es sich handelt.

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

Parameter

Name
page_num
Type
integer
Description
Die zurückzugebende Seitenzahl. Beginnt bei und ist standardmäßig 1.
Name
page_size
Type
integer
Description
Die Anzahl der Aufgaben pro Seite, bis zu 100. Standardmäßig 10.
Name
sort_by
Type
string
Description
Die Sortierreihenfolge.
Verfügbare Werte:
- +created_at: älteste zuerst
- -created_at: neueste zuerst

Rückgabe

Eine paginierte Liste von Aufgabenobjekten im gleichen Format wie das Bild zu Bild Aufgabenobjekt.

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

Einen Image-to-Image-Task streamen

Streamt die Updates eines Image-to-Image-Tasks als Server-Sent Events (SSE).

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.
// These examples are shortened. Each event holds the full task object.
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=***"
  ]
}

Parameter

Name
id
Type
path
Description
Die Task-ID aus der Erstellungs-Antwort.

Rückgabe

Ein Stream von Image-to-Image-Task-Objekten als Server-Sent Events.

Jedes Event enthält das vollständige Task-Objekt, in derselben Form, die der Get-Endpunkt zurückgibt. Solange der Task PENDING oder IN_PROGRESS ist, haben seine Ergebnisfelder noch keine Werte.

Das Image-to-Image-Task-Objekt

Ein Image-to-Image-Task-Objekt beschreibt ein Bild, das aus Referenzbildern und einem Text-prompt erzeugt wurde. Es enthält den Status, den progress und die Bilder, wenn die Aufgabe erfolgreich abgeschlossen wurde.

Eigenschaften

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
}

Name
id
Type
string
Description
Die Task-ID. Behandeln Sie sie als eine undurchsichtige Zeichenfolge und verlassen Sie sich nicht auf ihr Format.
Name
type
Type
string
Description
Der Task-Typ, immer image-to-image.
Name
ai_model
Type
string
Description
Das vom Task verwendete KI-Modell.
Verfügbare Werte:
- nano-banana
- nano-banana-2
- nano-banana-2-lite
- nano-banana-pro
- gpt-image-2
- gpt-image-2-5-flare
- gpt-image-2-5-sunburst
Name
prompt
Type
string
Description
Der Text-prompt, der die Bearbeitung geleitet hat.
Name
status
Type
string
Description
Der Task-Status, einer von PENDING, IN_PROGRESS, SUCCEEDED, FAILED oder CANCELED.
Name
progress
Type
integer
Description
Wie viel der Aufgabe abgeschlossen ist, in Prozent. Der Wert ist 0, bis der Task startet, und 100, wenn er erfolgreich abgeschlossen wird.
Name
created_at
Type
timestamp
Description
Zeitpunkt der Erstellung des Tasks, in Unix-Millisekunden.
Name
started_at
Type
timestamp
Description
Zeitpunkt des Starts des Tasks, in Unix-Millisekunden. Der Wert ist 0, bis der Task startet.
Name
finished_at
Type
timestamp
Description
Zeitpunkt des Abschlusses des Tasks, in Unix-Millisekunden. Der Wert ist 0, bis der Task abgeschlossen ist.
Name
expires_at
Type
timestamp
Description
Zeitpunkt, zu dem die Ergebnisse des Tasks ablaufen, in Unix-Millisekunden.
Name
preceding_tasks
Type
integer
Description
Die Anzahl der Tasks, die in der Warteschlange vor diesem stehen. Der Wert ist nur relevant, solange der Task den Status PENDING hat.
Name
image_urls
Type
array
Description
Download-URLs für die generierten Bilder. Bei generate_multi_view: true enthält das Array eine URL pro Ansicht, in der Regel drei. Wenn Meshy nicht jede Ansicht trennen kann, werden weniger zurückgegeben, und der Task gilt trotzdem als erfolgreich. Andernfalls enthält es eine URL.
Name
task_error
Type
object
Description
Die Fehlerdetails, wenn der Task fehlschlägt. Siehe Fehler.
Name
consumed_credits
Type
integer
Description
Die Anzahl der vom Task verbrauchten Credits. Vorhanden, wenn der Status PENDING, IN_PROGRESS oder SUCCEEDED ist. Bei einem Task mit dem Status FAILED ist der Wert 0, da Meshy die Credits erstattet, wenn ein Task fehlschlägt.