Bild zu Bild API

Die Bild zu Bild API ist eine Funktion, die es Ihnen ermöglicht, die KI-Bildbearbeitungsfähigkeiten von Meshy in Ihre eigene Anwendung zu integrieren. Transformieren und bearbeiten Sie vorhandene Bilder mithilfe von Referenzbildern und Texteingaben mit unseren leistungsstarken KI-Modellen.

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 Aufgabenobjekt, um zu sehen, welche Eigenschaften im Bild zu Bild 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 Fähigkeit 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 hochauflösendes 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.

  • Name
    reference_image_urls
    Type
    array
    Erforderlich
    Description

    Ein Array von 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 aus dem öffentlichen Internet zugänglich ist.
    • Data URI: Eine base64-kodierte 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 Mehransicht-Bild generiert, das das Motiv aus mehreren Blickwinkeln zeigt.

    Wenn generate_multi_view auf true gesetzt ist, kann der aspect_ratio Parameter nicht gesetzt werden.

  • Name
    aspect_ratio
    Type
    string
    Standard 1:1
    Description

    Geben Sie das Seitenverhältnis des Ausgabebildes an. Erlaubte Werte hängen vom ausgewä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: 1:1, 16:9, 9:16, 3:2, 2:3

    Verfügbare Werte:

    • 1:1: Quadratformat
    • 16:9: Breitbild-Landschaft
    • 9:16: Breitbild-Porträt
    • 4:3: Standard-Landschaft (nicht unterstützt von gpt-image-2)
    • 3:4: Standard-Porträt (nicht unterstützt von gpt-image-2)
    • 3:2: Landschaft (nur unterstützt von gpt-image-2)
    • 2:3: Porträt (nur unterstützt von gpt-image-2)
  • 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 jeden beliebigen Hintergrund setzen können.

Rückgaben

Die result Eigenschaft der Antwort enthält die Aufgaben-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, reference_image_urls) fehlt.
    • Ungültiges Bildformat: Eines oder mehrere Referenzbilder sind nicht unterstützte Formate.
    • Nicht erreichbare URL: Eine oder mehrere reference_image_urls konnten nicht heruntergeladen werden.
    • Ungültiger Parameter: aspect_ratio ist nicht einer der erlaubten Werte für das ausgewählte ai_model.
    • Konflikt: generate_multi_view und aspect_ratio können nicht gleichzeitig verwendet werden.
  • Name
    401 - Unauthorized
    Description

    Authentifizierung fehlgeschlagen. Bitte überprüfen Sie Ihren API-Schlüssel.

  • Name
    402 - Payment Required
    Description

    Unzureichende Credits, um diese Aufgabe auszuführen.

  • 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}"
    ]
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
GET/openapi/v1/image-to-image/:id

Abrufen einer Bild zu Bild Aufgabe

Dieser Endpunkt ermöglicht es Ihnen, eine Bild zu Bild Aufgabe mit einer gültigen Aufgaben-id abzurufen. Siehe Das Bild zu Bild Aufgabenobjekt, um zu sehen, welche Eigenschaften im Bild zu Bild Aufgabenobjekt enthalten sind.

Parameter

  • Name
    id
    Type
    path
    Description

    Eindeutiger Bezeichner für die abzurufende Bild zu Bild Aufgabe.

Rückgaben

Die Antwort enthält das Bild zu Bild Aufgabenobjekt. Überprüfen Sie den Abschnitt Das Bild zu Bild Aufgabenobjekt für Details.

Anfrage

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

Antwort

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

Löschen einer Bild zu Bild Aufgabe

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

Rückgaben

Gibt 200 OK bei Erfolg zurück.

Anfrage

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

Antwort

// Returns 200 Ok on success.
GET/openapi/v1/image-to-image

Liste Bild zu Bild Aufgaben

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 und standardmäßig auf 1.

  • Name
    page_size
    Type
    integer
    Description

    Begrenzung der Seitengröße. Standardmäßig 10 Elemente. Maximal erlaubt sind 50 Elemente.

  • Name
    sort_by
    Type
    string
    Description

    Feld, nach dem sortiert werden soll. Verfügbare Werte:

    • +created_at: Sortieren nach Erstellungszeit in aufsteigender Reihenfolge.
    • -created_at: Sortieren nach Erstellungszeit in absteigender Reihenfolge.

Rückgaben

Gibt eine paginierte Liste von Die Bild zu Bild Aufgaben Objekte zurück.

Anfrage

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

Antwort

[
  {
    "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 unter Verwendung von Server-Sent Events (SSE).

Parameter

  • Name
    id
    Type
    path
    Description

    Eindeutiger Bezeichner für die Bild zu Bild Aufgabe, die gestreamt werden soll.

Rückgaben

Gibt einen Stream von The Image to Image Task Objects als Server-Sent Events zurück.

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

Anfrage

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

Antwortstream

// 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 Bild zu Bild Aufgabenobjekt

Das Bild zu Bild Aufgabenobjekt ist eine Arbeitseinheit, die Meshy verfolgt, um ein Bild aus Referenzbildern und einem Text-prompt zu generieren. Das Objekt hat die folgenden Eigenschaften:

Eigenschaften

  • Name
    id
    Type
    string
    Description

    Eindeutiger Bezeichner für die Aufgabe. Während wir eine k-sortierbare UUID für Aufgaben-IDs als Implementierungsdetail verwenden, sollten Sie keine Annahmen über das Format der ID machen.

  • Name
    type
    Type
    string
    Description

    Der Typ der Bildgenerierungsaufgabe. Für Bild zu Bild Aufgaben wird dies immer image-to-image sein.

  • Name
    ai_model
    Type
    string
    Description

    Das AI-Modell, das für diese Aufgabe verwendet wird. 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 verwendet wurde, um die Bildtransformation zu leiten.

  • 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 begonnen hat, wird diese Eigenschaft 0 sein. Sobald die Aufgabe erfolgreich abgeschlossen ist, wird dies 100 sein.

  • Name
    created_at
    Type
    timestamp
    Description

    Zeitstempel, wann die Aufgabe 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 die Aufgabe gestartet wurde, in Millisekunden. Wenn die Aufgabe noch nicht gestartet ist, wird diese Eigenschaft 0 sein.

  • Name
    finished_at
    Type
    timestamp
    Description

    Zeitstempel, wann die Aufgabe abgeschlossen wurde, in Millisekunden. Wenn die Aufgabe noch nicht abgeschlossen ist, wird diese Eigenschaft 0 sein.

  • Name
    expires_at
    Type
    timestamp
    Description

    Zeitstempel, wann das Aufgabenergebnis abläuft, in Millisekunden.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Die Anzahl der vorhergehenden Aufgaben.

    Der Wert dieses Feldes ist nur sinnvoll, wenn der Aufgabenstatus PENDING ist.

  • Name
    image_urls
    Type
    array
    Description

    Ein Array von herunterladbaren 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 task_error Objektreferenz.

  • Name
    consumed_credits
    Type
    integer
    Description

    Die Anzahl der Credits, die von dieser Aufgabe verbraucht wurden. Vorhanden, wenn der Aufgabenstatus PENDING, IN_PROGRESS oder SUCCEEDED ist. Gibt 0 für FAILED Aufgaben zurück (Credits werden bei einem Fehler zurückerstattet).

Beispiel Bild zu Bild Aufgabenobjekt

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