Bild-zu-Bild-API

Die Bild-zu-Bild-API ist eine Funktion, mit der Sie die KI-Bildbearbeitungsfunktionen von Meshy 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

Create an Image to Image Task

Dieser Endpunkt ermöglicht es Ihnen, eine neue Bild zu Bild-Aufgabe zu erstellen. Siehe Das Bild-zu-Bild-Task-Objekt, um zu erfahren, welche Eigenschaften im Bild-zu-Bild-Task-Objekt 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ärkeren Fähigkeiten als das Standardmodell (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 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. Zudem muss sie über die API ausgeführt worden sein und den Status SUCCEEDED haben.

    Alle Ausgabebilder der Quellaufgabe werden verwendet. Eine Aufgabe mit einem einzelnen Bild 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 Aufbewahrungszeitraums für Assets befinden – sobald dieser abgelaufen ist, liefert ihre ID 404.

  • Name
    reference_image_urls
    Type
    array
    Erforderlich
    Description

    Ein Array von 1 bis 5 Referenzbildern, die für die Bildbearbeitungsaufgabe verwendet werden sollen. Wir unterstützen derzeit die Formate .jpg, .jpeg und .png.

    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

    Geben Sie das Seitenverhältnis des Ausgabebildes an. Die zulässigen Werte hängen vom gewä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, 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 auf beliebige Hintergründe montieren können.

Rückgabewerte

Die result-Eigenschaft 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 auf eine SUCCEEDED-Aufgabe vom Typ Text zu Bild oder Bild zu Bild (einschließlich Mehransicht) verweisen, die noch über Bildausgaben verfügt. Eine Aufgabe eines anderen Typs, eine nicht erfolgreiche Aufgabe oder eine, deren Bilder alle abgelaufen sind, wird abgelehnt.
    • 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.
    • Ungültiger Parameter: aspect_ratio ist keiner der zulässigen Werte für das gewählte ai_model.
    • 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 verweist nicht auf eine Aufgabe, die Ihrem Konto gehört. Eine nicht existierende Aufgabe und eine, 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 einer Text-Eingabeaufforderung 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. Bei 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-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 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 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Zeitstempel, wann der Task 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 der Task gestartet wurde, in Millisekunden. Wenn der Task noch nicht gestartet wurde, ist diese Eigenschaft 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Zeitstempel, wann der Task abgeschlossen wurde, in Millisekunden. Wenn der Task noch nicht abgeschlossen ist, ist diese Eigenschaft 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Zeitstempel, wann das Ergebnis des Tasks abläuft, in Millisekunden.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Die Anzahl der vorausgehenden Tasks.

    Der Wert dieses Feldes ist nur dann aussagekräftig, wenn der Task-Status 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 Blickwinkel repräsentieren. 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 Task-Status PENDING, IN_PROGRESS oder SUCCEEDED ist. Gibt bei FAILED-Tasks 0 zurück (Credits werden bei einem Fehlschlag zurückerstattet).

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
}