Edição de imagens

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 de imagem. 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 múltiplas imagens de referência (o limite varia por modelo)	Composição e edições com múltiplas referências
`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.

Defina enhance_prompt: true em qualquer um dos endpoints de edição para que um aprimorador com percepção visual analise a imagem ou imagens de entrada e reescreva sua instrução antes da edição. Veja Aprimoramento de prompt para detalhes de comportamento, preços e cabeçalhos de resposta.

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": "firered-image-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 de imagem. Salve-os diretamente em um arquivo. O formato é PNG para edições 1K e JPEG para edições 2K e 4K, ou PNG em qualquer resolução quando transparent_background é true. Defina output_format como jpeg, png ou webp para escolhê-lo explicitamente.

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": "firered-image-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)

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: "firered-image-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);

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": "firered-image-edit",
    "prompt": "Colorize this black and white portrait naturally",
    "image": "https://example.com/portrait-bw.jpg"
  }'

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

/image/multi-edit aceita múltiplas imagens, e o teto é específico de cada modelo. Leia model_spec.constraints.maxInputImages de GET /models?type=inpaint para obter o teto de um determinado modelo. Quando o campo está ausente, o teto é 3, ou 1 quando combineImages é false. A primeira imagem é a imagem base. As demais são referências adicionais que condicionam a edição.

O endpoint público não tem canal de máscara. Imagens adicionais atuam como referências na imagem inteira, não como mapas de região — não existe parâmetro mask, e enviá-lo retorna um 400. Faça prompts precisos para restringir onde a edição se aplica.

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": "firered-image-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=firered-image-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 de imagem, e o formato de saída segue as mesmas regras.

/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

Se você vai gerar ou editar a imagem de qualquer forma, pode pular esta segunda chamada: /image/generate, /image/edit e /image/multi-edit aceitam transparent_background: true em modelos suportados e retornam o canal alfa diretamente. Veja Imagens com fundo transparente para a comparação.

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	`firered-image-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
`resolution`	string	Não	`1K`	Nível de resolução da imagem de saída, como `1K`, `2K` ou `4K`. Os valores suportados variam por modelo
`output_format`	string	Não	inferido	`jpeg`, `png` ou `webp`. Quando omitido, PNG para edições 1K e JPEG para edições 2K e 4K, ou PNG em qualquer resolução quando `transparent_background` é `true`
`enhance_prompt`	boolean	Não	`false`	Analisa a imagem de entrada e reescreve a instrução de edição antes da inferência
`disable_prompt_optimization_thinking`	boolean	Não	padrão do modelo	Pula a etapa de raciocínio de otimização de prompt do modelo para uma geração mais rápida. Suportado apenas por modelos com `supportsOptimizePromptThinking`; ignorado pelos demais
`safe_mode`	boolean	Não	`true`	Embaça conteúdo adulto no resultado editado. Defina como `false` para desabilitar o embaçamento.
`transparent_background`	boolean	Não	`false`	Retorna a edição com um canal alfa real. Requer um modelo com `supportsTransparentBackground: true` e `output_format` `png` ou `webp` (inferido como PNG quando omitido). Veja Imagens com fundo transparente
`modelId`	string	Obsoleto	-	Alias obsoleto para `model`

`/image/multi-edit`

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`images`	array de arquivos, strings base64 ou URLs	Sim	-	A primeira imagem é a base; o restante são referências adicionais. O máximo é específico de cada modelo — veja `model_spec.constraints.maxInputImages`
`prompt`	string	Sim	-	Instruções de texto sobre como combinar ou editar as camadas
`modelId`	string	Não	`firered-image-edit`	ID do modelo de edição
`resolution`	string	Não	`1K`	Nível de resolução da imagem de saída, como `1K`, `2K` ou `4K`. Os valores suportados variam por modelo
`quality`	string	Não	padrão do modelo	`low`, `medium` ou `high` em modelos que listam `qualities` em `model_spec.constraints`. Valores mais altos podem aumentar o custo da requisição
`output_format`	string	Não	inferido	`jpeg`, `png` ou `webp`. Mesmas regras de inferência que `/image/edit`
`enhance_prompt`	boolean	Não	`false`	Analisa as imagens de entrada e reescreve a instrução de edição antes da inferência
`disable_prompt_optimization_thinking`	boolean	Não	padrão do modelo	Pula a etapa de raciocínio de otimização de prompt do modelo para uma geração mais rápida. Suportado apenas por modelos com `supportsOptimizePromptThinking`; ignorado pelos demais
`safe_mode`	boolean	Não	`true`	Embaça conteúdo adulto no resultado editado. Defina como `false` para desabilitar o embaçamento.
`transparent_background`	boolean	Não	`false`	Retorna o resultado composto com um canal alfa real. Mesmas regras de modelo e formato que `/image/edit`

`/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

/image/background-remove usa um modelo interno fixo. Ele não aceita um campo model. Enviar um (por exemplo "model": "bria-bg-remover") retorna 400 porque model não é um campo reconhecido.

Conteúdo adulto e safe mode

Tanto /image/edit quanto /image/multi-edit aceitam safe_mode (padrão: true). Quando habilitado, o conteúdo adulto na saída editada é embaçado, então envie safe_mode: false para receber a saída sem embaçamento:

{
  "model": "qwen-edit-uncensored",
  "prompt": "…",
  "image": "…",
  "safe_mode": false
}

A saída adulta (NSFW) sem desfoque está disponível para todos os usuários da API. Você não precisa de uma assinatura Pro, e a configuração de filtro adulto no app Venice não afeta as solicitações de imagem feitas pela API. As políticas de conteúdo variam conforme o modelo de edição e se aplicam independentemente de safe_mode. Para edição sem censura, use qwen-edit-uncensored. A diferença no nome de moderação entre endpoints confunde muita gente:

Endpoint	Campo para desabilitar o embaçamento
`POST /image/edit`, `POST /image/multi-edit`	`safe_mode: false`
`POST /image/generate` (geração nativa)	`safe_mode: false`
`POST /images/generations` (geração compatível com OpenAI)	`moderation: "low"`

Passar safe_mode para /images/generations retorna 400 com Unrecognized key(s) in object: 'safe_mode'.

Formatos de entrada suportados

Endpoint	Entrada JSON	Entrada multipart	Saída
`/image/edit`	String base64 ou URL	Upload de arquivo	`image/png`, `image/jpeg` ou `image/webp`
`/image/multi-edit`	Strings base64 ou URLs	Uploads de arquivo	`image/png`, `image/jpeg` ou `image/webp`
`/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 é firered-image-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. O aprimoramento de prompt adiciona **$ 0,04 por reescrita aplicada ao preço da edição. 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
`413`	Arquivo muito grande	Mantenha os arquivos enviados abaixo de 25 MB
`415`	Tipo de conteúdo inválido (somente `/image/multi-edit`; os outros endpoints retornam `400`)	Use JSON ou multipart form-data corretamente
`422`	Violação da política de conteúdo ou imagem de entrada grande demais	Ajuste o prompt ou reduza as dimensões da imagem
`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. Requisições que violam a política do modelo selecionado são rejeitadas com 422.

Workflows relacionados

Use Geração de imagens quando estiver partindo de texto em vez de uma imagem existente.
Use Aprimoramento de prompt para aprender como funciona a reescrita de edições com percepção visual.
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.

Documentação

Primeiros passos

Texto e chat

Imagem

Vídeo

Áudio

Pesquisa e RAG

Agentes e integrações

Ferramentas de código

Ferramentas para agentes

SDKs e frameworks

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`

Conteúdo adulto e safe mode

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

​Conteúdo adulto e safe mode

​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`

Conteúdo adulto e safe mode

Formatos de entrada suportados

Modelos e preços

Erros

Workflows relacionados