lowpoly wird am 30.10.2026 abgeschaltet. meshy-7 wird als 3D-Generierungsmodell am 31.12.2026 abgeschaltet; als Texturmodell bleibt es verfügbar. Wechseln Sie vor diesen Terminen das Modell, um Fehler bei Anfragen zu vermeiden. Alle Abkündigungen ansehen

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.


POST/openapi/v1/image-to-image

Create an Image to Image task

Erstellt eine Bild-zu-Bild-Aufgabe. Die Aufgabe läuft im Hintergrund. Wie lange eine Aufgabe normalerweise 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 variieren 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 leichte Version von nano-banana-2
    • nano-banana-2-1: Nano Banana 2.1
    • 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)
    • gpt-image-2-6-flare: OpenAI GPT Image 2.6 (Flare)
    • gpt-image-2-6-sunburst: OpenAI GPT Image 2.6 (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 den Status SUCCEEDED besitzt.

    Meshy verwendet jedes von der Aufgabe erzeugte Bild. Eine Einzelbild-Aufgabe liefert ein Referenzbild, eine Mehransicht-Aufgabe liefert eines pro Ansicht. So kann eine einzige Aufgaben-ID mehrere der fünf Referenzplätze füllen.

    Die Aufgabe muss sich noch innerhalb des Aufbewahrungszeitraums von Assets befinden. Nach dessen 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 zu bearbeitende Referenzbilder, jeweils eine öffentliche URL oder eine Data URI, zum Beispiel data:image/jpeg;base64,<your base64-encoded image data>. Ein leeres Array oder mehr als fünf Bilder führt zu 400. Wenn Sie beides senden, verwendet Meshy input_task_id.

    Jedes Bild muss eine .jpg-, .jpeg-, .png- oder .webp-Datei mit höchstens 20 MB und mindestens 32 Pixeln auf jeder Seite sein.

  • Name
    generate_multi_view
    Type
    boolean
    Standard false
    Description

    Ob ein Mehransicht-Bild erzeugt werden soll, das das Motiv aus mehreren Blickwinkeln zeigt. Bei true können Sie aspect_ratio nicht senden. Wenn Sie beides senden, wird 400 zurückgegeben.

  • Name
    aspect_ratio
    Type
    string
    Standard 1:1
    Description

    Das Seitenverhältnis des Ausgabebilds. 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, gpt-image-2-5-sunburst, gpt-image-2-6-flare und gpt-image-2-6-sunburst. Bei einem nano-banana-Modell führen 3:2 und 2:3 zu 400.

  • Name
    remove_background
    Type
    boolean
    Standard false
    Description

    Ob der Hintergrund entfernt werden soll. Bei true gibt Meshy das Ausgabebild als transparentes RGBA-PNG zurück, sodass Sie das Motiv auf einem beliebigen Hintergrund platzieren können.

Rückgabewerte

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

Fehlerarten

  • 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 weder reference_image_urls noch input_task_id wurde gesendet.
    • Ungültige Eingabeaufgabe: input_task_id verweist nicht auf eine nutzbare Aufgabe. Es muss sich um eine SUCCEEDED-Text-zu-Bild- oder Bild-zu-Bild-Aufgabe handeln, Mehransicht eingeschlossen, die noch Bildausgaben besitzt. Meshy lehnt eine Aufgabe eines anderen Typs, eine nicht erfolgreiche Aufgabe und eine Aufgabe ab, deren Bilder alle abgelaufen sind.
    • 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 haben eine Seite, die kürzer als 32 Pixel ist.
    • 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 Abonnement-Einstellungen und versuchen Sie es erneut.
    • Unzureichende Credits: Das Konto hat nicht 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 erneut.

  • Name
    404 - Not Found
    Description

    input_task_id entspricht keiner Aufgabe in Ihrem Konto. Eine nicht existierende Aufgabe und eine Aufgabe, die zu 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 generiert wurde. Es enthält den Status, den progress und die Bilder, sobald 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,
  "image_urls": [
    "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
  ],
  "task_error": null,

  "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 von der Aufgabe verwendete KI-Modell.

    Verfügbare Werte:

    • nano-banana
    • nano-banana-2
    • nano-banana-2-lite
    • nano-banana-2-1
    • nano-banana-pro
    • gpt-image-2
    • gpt-image-2-5-flare
    • gpt-image-2-5-sunburst
    • gpt-image-2-6-flare
    • gpt-image-2-6-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 von der Aufgabe erledigt ist, in Prozent. Der Wert ist 0, bis die Aufgabe beginnt, und 100, wenn sie erfolgreich abgeschlossen wird.

  • Name
    created_at
    Type
    timestamp
    Description

    Zeitpunkt, zu dem die Aufgabe erstellt wurde, in Unix-Millisekunden.

  • Name
    started_at
    Type
    timestamp
    Description

    Zeitpunkt, zu dem die Aufgabe gestartet wurde, in Unix-Millisekunden. Fehlt, bis die Aufgabe beginnt.

  • Name
    finished_at
    Type
    timestamp
    Description

    Zeitpunkt, zu dem die Aufgabe abgeschlossen wurde, in Unix-Millisekunden. Fehlt, bis die Aufgabe abgeschlossen ist.

  • Name
    expires_at
    Type
    timestamp
    Description

    Zeitpunkt, zu dem die Ergebnisse der Aufgabe ablaufen, in Unix-Millisekunden. Fehlt, bis die Aufgabe abgeschlossen ist.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Die Anzahl der Aufgaben, die dieser Aufgabe in der Warteschlange vorausgehen. Der Wert ist nur aussagekräftig, solange die Aufgabe PENDING ist. Das Feld wird weggelassen, wenn der Wert 0 ist.

  • Name
    image_urls
    Type
    array
    Description

    Download-URLs für die generierten Bilder. Mit generate_multi_view: true enthält es eine URL pro Ansicht, üblicherweise drei. Wenn Meshy nicht jede Ansicht trennen kann, gibt es weniger zurück, und die Aufgabe ist trotzdem erfolgreich. Andernfalls enthält es eine URL.

  • Name
    task_error
    Type
    object
    Description

    Die Fehlerdetails, wenn die Aufgabe fehlschlägt. Der Wert ist null, sofern der Status nicht FAILED ist. Siehe Fehler.

  • Name
    consumed_credits
    Type
    integer
    Description

    Die Anzahl der Credits, die die Aufgabe verbraucht hat. Vorhanden, wenn der Status PENDING, IN_PROGRESS oder SUCCEEDED ist. Bei einer FAILED-Aufgabe ist der Wert 0, da Meshy die Credits erstattet, wenn eine Aufgabe fehlschlägt.