Edição de imagens | Documentação da API 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.

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

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.

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

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:

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.

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)

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:

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

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 "[email protected]" \
  -F "[email protected]" \
  -o multi-edited.png

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

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

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:

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:

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:

curl https://api.venice.ai/api/v1/image/background-remove \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "[email protected]" \
  -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
API de Models 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
`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

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.

Workflows relacionados

Use Geração de imagens quando estiver partindo de texto em vez de uma imagem existente.
Use Modelos de imagem para comparar famílias de modelos de geração, edição e aprimoramento.
Use a API de Edição de imagem, API de Multi-Edit e API de Remoção de fundo para detalhes completos do schema.

​Endpoints

​Quando usar cada endpoint

​Passo 1: Edite uma única imagem

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

​Dicas de inpainting

​Passo 3: Remova o fundo

​Parâmetros da requisição

​/image/edit

​/image/multi-edit

​/image/background-remove

​Formatos de entrada suportados

​Modelos e preços

​Erros

​Workflows relacionados

Endpoints

Quando usar cada endpoint

Passo 1: Edite uma única imagem

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

Dicas de inpainting

Passo 3: Remova o fundo

Parâmetros da requisição

`/image/edit`

`/image/multi-edit`

`/image/background-remove`

Formatos de entrada suportados

Modelos e preços

Erros

Workflows relacionados