> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Edição de imagens

> Edite, faça inpainting, componha entradas em camadas e remova fundos com as APIs síncronas de edição, multi-edição e remoção de fundo da Venice.

A edição de imagens na Venice é síncrona. Envie sua imagem de origem para `/image/edit` ou `/image/multi-edit` e o resultado editado volta na mesma resposta como um arquivo PNG. Para recortes, `/image/background-remove` retorna um PNG transparente.

<Warning>
  Os endpoints de edição de imagem são experimentais e o comportamento específico de cada modelo pode mudar com o tempo.
</Warning>

## Endpoints

| Endpoint                        | Finalidade                           | Melhor para                                             |
| ------------------------------- | ------------------------------------ | ------------------------------------------------------- |
| `POST /image/edit`              | Edita uma única imagem com um prompt | Edições gerais e inpainting guiado por prompt           |
| `POST /image/multi-edit`        | Edita usando 1-3 imagens em camadas  | Edições mais controladas com máscaras ou overlays       |
| `POST /image/background-remove` | Remove o fundo de uma imagem         | Recortes transparentes para produtos, retratos e assets |

## Quando usar cada endpoint

* Use `/image/edit` quando tiver uma imagem de origem e quiser alterar, remover ou reestilizar parte dela com um prompt.
* Use `/image/multi-edit` quando precisar de controle extra a partir de máscaras, overlays ou camadas de referência.
* Use `/image/background-remove` quando só quiser um sujeito de primeiro plano limpo, com transparência.

<Note>
  Para inpainting, use `/image/edit` ou `/image/multi-edit`. O antigo parâmetro `inpaint` em `/image/generate` está obsoleto.
</Note>

## Passo 1: Edite uma única imagem

A edição de imagem única é o fluxo de inpainting mais simples. Envie uma imagem mais um prompt curto, como "remova a placa", "mude o céu para nascer do sol" ou "substitua o fundo por um cenário de estúdio".

**Requisição:**

```bash theme={"system"}
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"
}
```

**Resposta (200):**
O corpo da resposta são dados binários crus `image/png`. Salve-os diretamente em um arquivo.

<CodeGroup>
  ```python Python theme={"system"}
  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={"system"}
  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={"system"}
  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>

## Passo 2: Use multi-edit para máscaras ou inpainting em camadas

`/image/multi-edit` aceita até três imagens. A primeira imagem é a imagem base. As demais são tratadas como camadas de edição ou máscaras, o que dá mais controle do que edição apenas por prompt.

Essa é a melhor escolha quando você quer:

* mirar uma região específica com uma máscara
* combinar uma composição existente com um overlay
* restringir a edição mais do que um prompt de imagem única permite

**Requisição JSON:**

```json theme={"system"}
{
  "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"
  ]
}
```

**Requisição multipart:**

```bash theme={"system"}
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
```

Como `/image/edit`, o corpo da resposta são dados crus `image/png`.

<Note>
  `/image/multi-edit` atualmente usa o campo `modelId` em vez de `model` no schema de requisição.
</Note>

***

## Dicas de inpainting

O inpainting baseado em prompt funciona melhor quando a instrução é curta e local:

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

Para mudanças mais amplas de cena, descreva o que deve permanecer igual:

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

Se a edição continuar afetando a área errada, troque de `/image/edit` para `/image/multi-edit` e forneça uma máscara ou camada de overlay.

***

## Passo 3: Remova o fundo

Use `/image/background-remove` quando quiser o sujeito de primeiro plano isolado sobre um fundo transparente. Esse endpoint retorna um PNG com transparência alfa.

**Usando uma URL de imagem:**

```bash theme={"system"}
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"
  }'
```

**Usando upload de arquivo local:**

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

Use a remoção de fundo para:

* fotos de produtos para e-commerce
* fotos de perfil e retratos
* assets que você planeja colocar sobre um novo fundo

***

## Parâmetros da requisição

### `/image/edit`

| Parâmetro      | Tipo                          | Obrigatório | Padrão           | Descrição                                      |
| -------------- | ----------------------------- | ----------- | ---------------- | ---------------------------------------------- |
| `image`        | arquivo, string base64 ou URL | Sim         | -                | Imagem de origem a editar                      |
| `prompt`       | string                        | Sim         | -                | Instruções de texto para a edição              |
| `model`        | string                        | Não         | `qwen-edit`      | ID do modelo de edição                         |
| `aspect_ratio` | string                        | Não         | padrão do modelo | Proporção de saída para modelos que a suportam |
| `modelId`      | string                        | Obsoleto    | -                | Alias obsoleto para `model`                    |

### `/image/multi-edit`

| Parâmetro | Tipo                                          | Obrigatório | Padrão      | Descrição                                                                |
| --------- | --------------------------------------------- | ----------- | ----------- | ------------------------------------------------------------------------ |
| `images`  | array de 1-3 arquivos, strings base64 ou URLs | Sim         | -           | A primeira imagem é a base; o restante são camadas de edição ou máscaras |
| `prompt`  | string                                        | Sim         | -           | Instruções de texto sobre como combinar ou editar as camadas             |
| `modelId` | string                                        | Não         | `qwen-edit` | ID do modelo de edição                                                   |

### `/image/background-remove`

| Parâmetro   | Tipo                     | Obrigatório                  | Descrição                        |
| ----------- | ------------------------ | ---------------------------- | -------------------------------- |
| `image`     | arquivo ou string base64 | Um de `image` ou `image_url` | Imagem de origem a recortar      |
| `image_url` | string                   | Um de `image` ou `image_url` | URL pública da imagem a recortar |

***

## Formatos de entrada suportados

| Endpoint                   | Entrada JSON           | Entrada multipart  | Saída       |
| -------------------------- | ---------------------- | ------------------ | ----------- |
| `/image/edit`              | String base64 ou URL   | Upload de arquivo  | `image/png` |
| `/image/multi-edit`        | Strings base64 ou URLs | Uploads de arquivo | `image/png` |
| `/image/background-remove` | String base64 ou URL   | Upload de arquivo  | `image/png` |

Para endpoints de edição, as dimensões da imagem devem ser de no mínimo `65536` pixels e no máximo `33177600` pixels. Arquivos enviados devem ter menos de `25MB`.

***

## Modelos e preços

O modelo de edição padrão é `qwen-edit`, com preço de **\$0,04 por edição**. Outros modelos com capacidade de edição podem ter preços e restrições diferentes.

Veja:

* [Preços de imagens](/overview/pricing)
* [API de Models](/api-reference/endpoint/models/list) com `type=inpaint`

***

## Erros

| Status | Significado                                      | Ação                                                                          |
| ------ | ------------------------------------------------ | ----------------------------------------------------------------------------- |
| `400`  | Parâmetros de requisição inválidos               | Verifique a quantidade de imagens, nomes de campos e formato de entrada       |
| `401`  | Falha de autenticação                            | Verifique sua chave de API                                                    |
| `402`  | Saldo insuficiente                               | Adicione créditos em [venice.ai/settings/api](https://venice.ai/settings/api) |
| `415`  | Tipo de conteúdo inválido                        | Use JSON ou multipart form-data corretamente                                  |
| `429`  | Limite de taxa excedido ou modelo sobrecarregado | Tente novamente com backoff; verifique o cabeçalho `Retry-After`              |
| `500`  | Falha no processamento da inferência             | Tente novamente                                                               |
| `503`  | Modelo em capacidade máxima                      | Tente novamente após um pequeno atraso                                        |

<Note>
  Alguns modelos de edição têm políticas de conteúdo mais rigorosas do que modelos de geração de imagem. Por exemplo, `qwen-edit` bloqueia requisições envolvendo imagens sexuais explícitas, sexualização de menores ou violência do mundo real.
</Note>

***

## Workflows relacionados

* Use [Geração de imagens](/guides/media/image-generation) quando estiver partindo de texto em vez de uma imagem existente.
* Use [Modelos de imagem](/models/image) para comparar famílias de modelos de geração, edição e aprimoramento.
* Use a [API de Edição de imagem](/api-reference/endpoint/image/edit), [API de Multi-Edit](/api-reference/endpoint/image/multi-edit) e [API de Remoção de fundo](/api-reference/endpoint/image/background-remove) para detalhes completos do schema.