> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-ce69695c.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Bildbearbeitung

> Bilder mit Venices /image/edit- und /image/multi-edit-Endpunkten bearbeiten, inpainten und komponieren oder Hintergründe für transparente PNGs entfernen.

Die Bildbearbeitung auf Venice ist synchron. Sende dein Quellbild an `/image/edit` oder `/image/multi-edit`, und das bearbeitete Ergebnis kommt in derselben Antwort als PNG-Datei zurück. Für Freisteller liefert `/image/background-remove` ein transparentes PNG.

<Warning>
  Die Image-Edit-Endpoints sind experimentell, und modellspezifisches Verhalten kann sich im Laufe der Zeit ändern.
</Warning>

## Endpoints

| Endpoint | Zweck | Geeignet für |
| - | - | - |
| `POST /image/edit` | Ein Bild mit einem Prompt bearbeiten | Allgemeine Edits und Prompt-getriebenes Inpainting |
| `POST /image/multi-edit` | Bearbeitung mit mehreren Referenzbildern (3, oder bis zu 6 bei höherstufigen Modellen) | Compositing und Edits mit mehreren Referenzen |
| `POST /image/background-remove` | Hintergrund eines Bildes entfernen | Transparente Freisteller für Produkte, Porträts und Assets |

## Wann welcher Endpoint?

* `/image/edit` verwenden, wenn du ein Quellbild hast und einen Teil davon per Prompt verändern, entfernen oder umstilen willst.
* `/image/multi-edit` verwenden, wenn du zusätzliche Kontrolle durch Masken, Overlays oder Referenz-Layer brauchst.
* `/image/background-remove` verwenden, wenn du nur ein sauberes Vordergrundmotiv mit Transparenz brauchst.

<Note>
  Für Inpainting `/image/edit` oder `/image/multi-edit` verwenden. Der alte `inpaint`-Parameter auf `/image/generate` ist deprecated.
</Note>

<Tip>
  Setze `enhance_prompt: true` auf einem der Edit-Endpoints, damit ein Vision-fähiger Enhancer das Eingabebild oder die Eingabebilder analysiert und deine Anweisung vor der Bearbeitung umschreibt. Siehe [Prompt-Enhancement](/guides/media/prompt-enhancement) für Verhalten, Preise und Details zu Response-Headern.
</Tip>

## Schritt 1: Ein einzelnes Bild bearbeiten

Single-Image-Edit ist der einfachste Inpainting-Flow. Sende ein Bild plus einen kurzen Prompt wie „remove the sign", „change the sky to sunrise" oder „replace the background with a studio backdrop".

**Request:**

```bash theme={null}
POST https://api.venice.ai/api/v1/image/edit
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "qwen-edit",
  "prompt": "Replace the cloudy sky with a warm sunrise while preserving the buildings and canal",
  "image": "https://example.com/venice-canal.jpg"
}
```

**Antwort (200):**
Der Response-Body sind rohe `image/png`-Binärdaten. Speichere sie direkt in eine Datei.

<CodeGroup>
  ```python Python theme={null}
  import base64
  import os
  import requests

  with open("input.jpg", "rb") as f:
      image_base64 = base64.b64encode(f.read()).decode("utf-8")

  response = requests.post(
      "https://api.venice.ai/api/v1/image/edit",
      headers={
          "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={
          "model": "qwen-edit",
          "prompt": "Remove the tourist crowd from the square and keep the architecture intact",
          "image": image_base64,
      },
  )

  with open("edited.png", "wb") as f:
      f.write(response.content)
  ```

  ```javascript Node.js theme={null}
  import fs from "fs";

  const imageBase64 = fs.readFileSync("input.jpg").toString("base64");

  const response = await fetch("https://api.venice.ai/api/v1/image/edit", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VENICE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "qwen-edit",
      prompt: "Remove the tourist crowd from the square and keep the architecture intact",
      image: imageBase64,
    }),
  });

  const editedImage = Buffer.from(await response.arrayBuffer());
  fs.writeFileSync("edited.png", editedImage);
  ```

  ```bash cURL theme={null}
  curl https://api.venice.ai/api/v1/image/edit \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -o edited.png \
    -d '{
      "model": "qwen-edit",
      "prompt": "Colorize this black and white portrait naturally",
      "image": "https://example.com/portrait-bw.jpg"
    }'
  ```
</CodeGroup>

## Schritt 2: Multi-Edit für Masken oder mehrschichtiges Inpainting nutzen

`/image/multi-edit` akzeptiert mehrere Bilder, und die Obergrenze ist modellspezifisch: Die meisten Edit-Modelle erlauben 3, während die höherstufigen — darunter `gpt-image-2-edit`, `nano-banana-pro-edit`, `seedream-v5-pro-edit`, `flux-2-max-edit` und `wan-2-7-pro-edit` — bis zu 6 erlauben. Lies `model_spec.constraints.maxInputImages` aus `GET /models?type=inpaint`, um die Obergrenze für ein bestimmtes Modell zu erhalten; fehlt das Feld, liegt die Obergrenze bei 3.

Das erste Bild ist das Basis-Bild. Die weiteren Bilder sind zusätzliche Referenzen, die den Edit konditionieren.

<Note>
  Der öffentliche Endpoint hat keinen Masken-Kanal. Zusätzliche Bilder wirken als Referenzen über das gesamte Bild, nicht als Regionsmasken – es gibt keinen `mask`-Parameter, und das Senden eines solchen gibt einen `400` zurück. Prompte präzise, um einzugrenzen, wo der Edit landet.
</Note>

Das ist die bessere Wahl, wenn du:

* eine bestimmte Region per Maske gezielt ansprechen willst
* eine bestehende Komposition mit einem Overlay kombinieren willst
* den Edit enger einschränken willst, als es ein Single-Image-Prompt erlaubt

**JSON-Request:**

```json theme={null}
{
  "modelId": "qwen-edit",
  "prompt": "Replace the blank billboard area with a glowing Venice film festival poster while preserving lighting and perspective",
  "images": [
    "https://example.com/street-scene.png",
    "https://example.com/billboard-mask.png"
  ]
}
```

**Multipart-Request:**

```bash theme={null}
curl https://api.venice.ai/api/v1/image/multi-edit \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "modelId=qwen-edit" \
  -F "prompt=Replace the blank billboard area with a glowing Venice film festival poster while preserving lighting and perspective" \
  -F "images=@street-scene.png" \
  -F "images=@billboard-mask.png" \
  -o multi-edited.png
```

Wie bei `/image/edit` sind die Response-Body rohe `image/png`-Daten.

<Note>
  `/image/multi-edit` verwendet im Request-Schema derzeit das Feld `modelId` statt `model`.
</Note>

***

## Inpainting-Tipps

Prompt-basiertes Inpainting funktioniert am besten, wenn die Anweisung kurz und lokal ist:

* `remove the tree`
* `change the sky to sunset`
* `replace the logo with a blank sign`
* `restore the torn corner of the photo`

Für umfangreichere Szenenänderungen beschreibe, was unverändert bleiben soll:

```text theme={null}
Replace the background with a modern photo studio backdrop while preserving the subject pose, facial features, and clothing.
```

Wenn der Edit ständig den falschen Bereich trifft, wechsle von `/image/edit` zu `/image/multi-edit` und übergib einen Masken- oder Overlay-Layer.

***

## Schritt 3: Hintergrund entfernen

Verwende `/image/background-remove`, wenn du das Vordergrundmotiv auf transparentem Hintergrund isoliert haben willst. Dieser Endpoint liefert ein PNG mit Alpha-Transparenz.

**Per Bild-URL:**

```bash theme={null}
curl https://api.venice.ai/api/v1/image/background-remove \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -o cutout.png \
  -d '{
    "image_url": "https://example.com/product-photo.jpg"
  }'
```

**Per lokalem Datei-Upload:**

```bash theme={null}
curl https://api.venice.ai/api/v1/image/background-remove \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "image=@product-photo.jpg" \
  -o cutout.png
```

Hintergrundentfernung eignet sich für:

* E-Commerce-Produktfotos
* Profilbilder und Porträts
* Assets, die du auf einen neuen Hintergrund legen willst

***

## Request-Parameter

### `/image/edit`

| Parameter | Typ | Pflicht | Default | Beschreibung |
| - | - | - | - | - |
| `image` | Datei, Base64-String oder URL | Ja | - | Zu bearbeitendes Quellbild |
| `prompt` | string | Ja | - | Text-Anweisungen für den Edit |
| `model` | string | Nein | `qwen-edit` | Edit-Modell-ID |
| `aspect_ratio` | string | Nein | Modell-Default | Output-Ratio bei Modellen, die das unterstützen |
| `enhance_prompt` | boolean | Nein | `false` | Eingabebild analysieren und die Edit-Anweisung vor der Inferenz umschreiben |
| `safe_mode` | boolean | Nein | `true` | Anstößige Inhalte im bearbeiteten Ergebnis unscharf machen. Auf `false` setzen, um die Unschärfe zu deaktivieren. |
| `modelId` | string | Deprecated | - | Deprecated-Alias für `model` |

### `/image/multi-edit`

| Parameter | Typ | Pflicht | Default | Beschreibung |
| - | - | - | - | - |
| `images` | Array aus Dateien, Base64-Strings oder URLs | Ja | - | Erstes Bild ist das Basis-Bild; weitere sind zusätzliche Referenzen. Maximum ist modellspezifisch – standardmäßig 3, bis zu 6 bei höherstufigen Modellen |
| `prompt` | string | Ja | - | Text-Anweisungen, wie die Layer kombiniert oder bearbeitet werden |
| `modelId` | string | Nein | `qwen-edit` | Edit-Modell-ID |
| `enhance_prompt` | boolean | Nein | `false` | Eingabebilder analysieren und die Edit-Anweisung vor der Inferenz umschreiben |
| `safe_mode` | boolean | Nein | `true` | Anstößige Inhalte im bearbeiteten Ergebnis unscharf machen. Auf `false` setzen, um die Unschärfe zu deaktivieren. |

### `/image/background-remove`

| Parameter | Typ | Pflicht | Beschreibung |
| - | - | - | - |
| `image` | Datei oder Base64-String | Eines von `image` oder `image_url` | Quellbild zum Freistellen |
| `image_url` | string | Eines von `image` oder `image_url` | Öffentliche Bild-URL zum Freistellen |

<Note>
  `/image/background-remove` verwendet ein festes internes Modell. Es akzeptiert kein `model`-Feld. Wird eines gesendet (zum Beispiel `"model": "bria-bg-remover"`), gibt es `400 invalid model id` zurück.
</Note>

### Adult-Inhalte und Safe Mode

Sowohl `/image/edit` als auch `/image/multi-edit` akzeptieren `safe_mode` (Default: `true`). Wenn aktiviert, werden Adult-Inhalte in der bearbeiteten Ausgabe unscharf gemacht. Setze `safe_mode: false`, um die Ausgabe ohne Unschärfe zu erhalten:

```json theme={null}
{
  "model": "qwen-edit-uncensored",
  "prompt": "…",
  "image": "…",
  "safe_mode": false
}
```

Das Default-Modell `qwen-edit` blockiert weiterhin explizite sexuelle Bilder und reale Gewalt – unabhängig von `safe_mode`. Für unzensiertes Editing nutze `qwen-edit-uncensored`.

Der Unterschied im Namen des Moderations-Feldes zwischen den Endpoints stiftet oft Verwirrung:

| Endpoint | Feld zum Deaktivieren der Unschärfe |
| - | - |
| `POST /image/edit`, `POST /image/multi-edit` | `safe_mode: false` |
| `POST /image/generate` (native Generierung) | `safe_mode: false` |
| `POST /images/generations` (OpenAI-kompatible Generierung) | `moderation: "low"` |

Wird `safe_mode` an `/images/generations` übergeben, gibt es einen `400` mit `Unrecognized key(s) in object: 'safe_mode'`.

***

## Unterstützte Eingabeformate

| Endpoint | JSON-Input | Multipart-Input | Output |
| - | - | - | - |
| `/image/edit` | Base64-String oder URL | Datei-Upload | `image/png` |
| `/image/multi-edit` | Base64-Strings oder URLs | Datei-Uploads | `image/png` |
| `/image/background-remove` | Base64-String oder URL | Datei-Upload | `image/png` |

Für Edit-Endpoints müssen die Bilddimensionen mindestens `65536` Pixel und höchstens `33177600` Pixel betragen. Uploaded files müssen unter `25MB` sein.

***

## Modelle und Preise

Das Default-Edit-Modell ist `qwen-edit`, **\$0,04 pro Edit**. Andere edit-fähige Modelle können andere Preise und Einschränkungen haben. Prompt-Enhancement erhöht den Edit-Preis um **\$0,04 pro angewendetem Rewrite**.

Siehe:

* [Image-Preise](/overview/pricing)
* [Models-API](/api-reference/endpoint/models/list) mit `type=inpaint`

***

## Fehler

| Status | Bedeutung | Aktion |
| - | - | - |
| `400` | Ungültige Request-Parameter | Bildanzahl, Feldnamen und Input-Format prüfen |
| `401` | Authentifizierung fehlgeschlagen | API-Schlüssel prüfen |
| `402` | Unzureichendes Guthaben | Credits unter [venice.ai/settings/api](https://venice.ai/settings/api?utm_source=venice-api-documentation) aufladen |
| `415` | Ungültiger Content-Type | JSON oder Multipart-Form-Data korrekt nutzen |
| `429` | Rate-Limit überschritten oder Modell überlastet | Mit Backoff erneut versuchen; `Retry-After`-Header beachten |
| `500` | Inferenz-Verarbeitung fehlgeschlagen | Request wiederholen |
| `503` | Modell ausgelastet | Nach kurzer Verzögerung erneut versuchen |

<Note>
  Einige Edit-Modelle haben strengere Content-Policies als Image-Generation-Modelle. Zum Beispiel blockiert `qwen-edit` Anfragen, die explizite sexuelle Inhalte, sexualisierte Minderjährige oder reale Gewalt betreffen.
</Note>

***

## Verwandte Workflows

* Nutze [Bildgenerierung](/guides/media/image-generation), wenn du nicht von einem Bild, sondern von Text startest.
* Nutze [Prompt-Enhancement](/guides/media/prompt-enhancement), um zu lernen, wie Vision-fähiges Umschreiben von Edits funktioniert.
* Nutze [Image-Modelle](/models/image), um Generations-, Edit- und Enhancement-Modellfamilien zu vergleichen.
* Nutze [Image-Edit-API](/api-reference/endpoint/image/edit), [Multi-Edit-API](/api-reference/endpoint/image/multi-edit) und [Background-Remove-API](/api-reference/endpoint/image/background-remove) für vollständige Schema-Details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.