Geração de imagens

A geração de imagens na Venice é síncrona. Envie um prompt para /image/generate e receba sua imagem na mesma resposta, seja como base64 dentro de JSON ou como binário cru quando return_binary for true.

Endpoints

Endpoint	Finalidade	Quando usar
`POST /image/generate`	API nativa Venice de geração de imagens	Use este para suporte completo aos recursos
`GET /image/styles`	Lista os presets de estilo disponíveis	Use antes de enviar `style_preset`
`POST /images/generations`	API de geração de imagens compatível com OpenAI	Use ao migrar clientes existentes de imagens OpenAI

Passo 1: Envie uma requisição de geração

O dimensionamento é específico do modelo. Alguns modelos aceitam width e height explícitos; alguns expõem aspect_ratio; e modelos com tiers de resolução expõem aspect_ratio mais valores de resolution como 1K, 2K ou 4K.

qwen-image, qwen-image-3, qwen-image-3-pro, qwen-image-2-1-turbo e qwen-image-2-1-pro não aceitam mais width ou height. Enviar qualquer um deles retorna 400 com “width and height are no longer supported for this model. Use aspect_ratio instead.” Verifique model_spec.constraints em GET /models?type=image antes de escolher os campos de dimensionamento.

Exemplo de dimensionamento por pixels:

POST https://api.venice.ai/api/v1/image/generate
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "venice-sd35",
  "prompt": "A cinematic photo of a gondola passing through a narrow Venice canal at blue hour, warm window lights reflecting on the water",
  "negative_prompt": "blurry, low quality, distorted anatomy, text, watermark",
  "width": 1024,
  "height": 1024,
  "format": "webp"
}

Exemplo de dimensionamento por aspect ratio:

POST https://api.venice.ai/api/v1/image/generate
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "qwen-image-2",
  "prompt": "A cinematic photo of a gondola passing through a narrow Venice canal at blue hour",
  "aspect_ratio": "16:9",
  "format": "webp"
}

Exemplo de dimensionamento por tier de resolução:

POST https://api.venice.ai/api/v1/image/generate
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "gpt-image-2",
  "prompt": "A cinematic wide shot of a gondola passing through a narrow Venice canal at blue hour",
  "aspect_ratio": "16:9",
  "resolution": "4K",
  "format": "png"
}

O mesmo padrão se aplica a outros modelos com tier de resolução:

{
  "model": "nano-banana-pro",
  "prompt": "A serene canal in Venice at sunset",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}

Use Modelos de imagem ou a API de Models para confirmar quais campos de dimensionamento cada modelo aceita. Resposta (200):

{
  "id": "generate-image-1234567890",
  "images": [
    "UklGRiIAAABXRUJQVlA4IBYAAAAwAQCdASoQABAAPm..."
  ],
  "timing": {
    "inferenceDuration": 1840,
    "inferencePreprocessingTime": 22,
    "inferenceQueueTime": 31,
    "total": 1893
  }
}

O array images contém dados de imagem codificados em base64. Decodifique o primeiro item para salvá-lo ou exibi-lo. timing.total é a duração total da requisição em milissegundos.

Passo 2: Decodifique e salve a imagem

import base64
import os
import requests

response = requests.post(
    "https://api.venice.ai/api/v1/image/generate",
    headers={
        "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "venice-sd35",
        "prompt": "A cinematic photo of a gondola passing through a narrow Venice canal at blue hour, warm window lights reflecting on the water",
        "width": 1024,
        "height": 1024,
        "format": "webp",
    },
)

data = response.json()
image_bytes = base64.b64decode(data["images"][0])

with open("output.webp", "wb") as f:
    f.write(image_bytes)

print(f"Saved image from request {data['id']}")

import fs from "fs";

const response = await fetch("https://api.venice.ai/api/v1/image/generate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VENICE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "venice-sd35",
    prompt: "A cinematic photo of a gondola passing through a narrow Venice canal at blue hour, warm window lights reflecting on the water",
    width: 1024,
    height: 1024,
    format: "webp",
  }),
});

const data = await response.json();
const imageBuffer = Buffer.from(data.images[0], "base64");
fs.writeFileSync("output.webp", imageBuffer);

console.log(`Saved image from request ${data.id}`);

Passo 3: Retorne binário em vez de JSON (opcional)

Se você quer que o corpo da resposta seja o próprio arquivo de imagem, defina return_binary: true. Isso é útil quando você quer fazer streaming ou salvar a imagem diretamente sem decodificação de base64.

curl https://api.venice.ai/api/v1/image/generate \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -o output.png \
  -d '{
    "model": "qwen-image-2",
    "prompt": "Minimalist poster of a moonlit Venetian bridge in deep blue tones",
    "format": "png",
    "return_binary": true
  }'

Quando return_binary é true, o corpo da resposta é dado bruto image/jpeg, image/png ou image/webp com base no format que você solicitou.

variants é suportado apenas quando return_binary é false.

Passo 4: Liste estilos de imagem disponíveis (opcional)

Se quiser usar style_preset, primeiro busque os estilos disponíveis em /image/styles:

curl https://api.venice.ai/api/v1/image/styles

Este endpoint é público e não requer uma chave de API. Resposta (200):

{
  "object": "list",
  "data": [
    "3D Model",
    "Analog Film",
    "Anime",
    "Cinematic",
    "Digital Art"
  ]
}

Os nomes dos estilos ficam dentro de data, não no nível superior — leia response.data em vez de iterar diretamente sobre o objeto da resposta. Depois, passe um desses valores na sua requisição de geração:

{
  "model": "qwen-image-2",
  "prompt": "A futuristic Venice skyline at sunrise",
  "style_preset": "Cinematic"
}

Use o endpoint de estilos quando quiser nomes exatos de presets em vez de adivinhá-los.

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`model`	string	Sim	-	ID do modelo a usar na geração
`prompt`	string	Sim	-	O que gerar
`negative_prompt`	string	Não	-	O que evitar na imagem
`width`	integer	Não	`1024`	Largura de saída em pixels para modelos baseados em pixels, como `venice-sd35`. Rejeitado pela família Qwen Image — veja a nota abaixo
`height`	integer	Não	`1024`	Altura de saída em pixels para modelos baseados em pixels, como `venice-sd35`. Rejeitado pela família Qwen Image — veja a nota abaixo
`format`	string	Não	`webp`	Formato de saída: `jpeg`, `png` ou `webp`
`variants`	integer	Não	`1`	Número de imagens a gerar (`1`-`4`), apenas quando `return_binary` é `false`
`return_binary`	boolean	Não	`false`	Retorna bytes de imagem crus em vez de JSON base64
`safe_mode`	boolean	Não	`true`	Embaça conteúdo adulto quando habilitado
`seed`	integer	Não	aleatório	Reutilize o mesmo seed para iterações mais consistentes
`cfg_scale`	number	Não	dependente do modelo	Valores mais altos fazem o modelo seguir o prompt mais de perto
`style_preset`	string	Não	-	Aplica um estilo predefinido de Image Styles
`aspect_ratio`	string	Condicional	-	Usado por modelos que suportam dimensionamento por proporção, como `qwen-image-2`, `gpt-image-2`, `nano-banana-2` e `nano-banana-pro`
`resolution`	string	Condicional	-	Usado por modelos que suportam tiers de resolução como `1K`, `2K` ou `4K`
`enable_web_search`	boolean	Condicional	`false`	Permite que modelos suportados usem informações atuais da web; adiciona custo extra
`transparent_background`	boolean	Não	`false`	Retorna um PNG ou WebP com um canal alfa real. Requer um modelo com `supportsTransparentBackground: true` e `format` `png` ou `webp`. Veja Imagens com fundo transparente

A validação é específica do modelo. Verifique Modelos de imagem e a API de Models antes de depender de um parâmetro em vários modelos.

Opções específicas de modelo

Geração em alta resolução

Alguns modelos de imagem suportam aspect_ratio sem um tier resolution selecionável. Por exemplo, qwen-image-2 aceita aspect ratio e mapeia para dimensões de saída específicas do modelo:

{
  "model": "qwen-image-2",
  "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting",
  "aspect_ratio": "16:9"
}

Outros modelos de imagem suportam aspect_ratio mais um tier resolution. Por exemplo, gpt-image-2, nano-banana-2 e nano-banana-pro suportam 1K, 2K e 4K:

{
  "model": "gpt-image-2",
  "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting",
  "aspect_ratio": "16:9",
  "resolution": "4K"
}

{
  "model": "nano-banana-2",
  "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}

Use Modelos de imagem para ver quais modelos suportam resoluções maiores e como são precificados.

Conteúdo adulto e safe mode

safe_mode controla se o conteúdo adulto na saída da geração é borrado. O padrão é true, então imagens classificadas como adultas voltam borradas, a menos que você envie safe_mode: false:

{
  "model": "lustify-v8",
  "prompt": "…",
  "safe_mode": false
}

Imagens adultas (NSFW) sem desfoque estão disponíveis 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. Alguns modelos de imagem são projetados especificamente para geração adulta / sem censura e combinam bem com safe_mode: false. Exemplos na página de preços incluem lustify-sdxl, lustify-v7 e lustify-v8. Veja Modelos de imagem e Preços para a lista atual e os custos por modelo. Para edição de imagens existentes, o modelo de edição padrão é firered-image-edit. As políticas de conteúdo variam conforme o modelo de edição; se você precisa de edição sem censura, use qwen-edit-uncensored via Edição de imagem. Quando safe_mode está habilitado e o modelo retorna saída borrada ou moderada, inspecione os cabeçalhos de resposta x-venice-is-blurred e x-venice-is-content-violation se precisar detectar isso programaticamente.

Usando um app de terceiros? Imagens adultas permanecem borradas, a menos que o app envie safe_mode: false, ou moderation: "low" no endpoint compatível com OpenAI (veja abaixo).

Presets de estilo

Se o modelo selecionado suportar, style_preset permite guiar a saída sem reescrever todo o prompt. Você pode buscar nomes de preset válidos em Image Styles:

{
  "model": "qwen-image-2",
  "prompt": "A futuristic Venice skyline at sunrise",
  "style_preset": "3D Model"
}

Veja Image Styles para a lista de estilos atual.

Endpoint compatível com OpenAI

Se você já está usando SDKs de imagem da OpenAI ou integrações DALL-E existentes, a Venice também suporta POST /images/generations. Ele oferece um formato de requisição mais simples, mas com menos recursos do que o endpoint nativo da Venice. Requisição:

{
  "model": "z-image-turbo",
  "prompt": "A clean isometric illustration of an AI control room",
  "size": "1024x1024",
  "response_format": "b64_json"
}

size se aplica apenas a modelos dimensionados por pixels, que têm um widthHeightDivisor acima de 1 em model_spec.constraints de GET /models?type=image. A maioria dos modelos, incluindo qwen-image-2, dimensiona a saída por proporção e resolução e ignora size. Use a rota compatível com OpenAI para migrações mais rápidas. Use /image/generate quando precisar de opções específicas da Venice, como cfg_scale, style_preset, variants ou respostas binárias.

Controlando o embaçamento de conteúdo adulto em `/images/generations`

O endpoint compatível com OpenAI não aceita safe_mode. Enviá-lo retorna 400 com Unrecognized key(s) in object: 'safe_mode'. Use o parâmetro moderation no estilo OpenAI:

Valor	Comportamento
`auto` (padrão)	Embaça conteúdo adulto, igual a `safe_mode: true`
`low`	Retorna a saída sem embaçamento, igual a `safe_mode: false`

{
  "model": "lustify-v8",
  "prompt": "…",
  "size": "1024x1024",
  "response_format": "b64_json",
  "moderation": "low"
}

safe_mode funciona apenas no endpoint nativo POST /image/generate. moderation funciona apenas no endpoint compatível com OpenAI POST /images/generations. A mesma divisão se aplica à transparência: /image/generate usa transparent_background: true, enquanto /images/generations usa o parâmetro no estilo OpenAI background: "transparent". Ambos exigem um formato de saída png ou webp e um modelo com supportsTransparentBackground: true. Veja Imagens com fundo transparente.

Dicas de prompting

Comece com o sujeito, depois adicione meio, iluminação, composição e atmosfera.
Coloque detalhes a evitar em negative_prompt em vez de sobrecarregar o prompt principal.
Reutilize seed ao iterar para comparar mudanças de prompt sem alterar totalmente a composição.
Mantenha o dimensionamento ciente do modelo. Alguns modelos usam width/height, alguns usam aspect_ratio e modelos com tier de resolução usam aspect_ratio mais resolution.
Use variants durante a exploração e depois volte para uma única saída quando tiver travado a direção.

Erros

Status	Significado	Ação
`400`	Parâmetros de requisição inválidos	Verifique nomes de campos, tipos e restrições específicas do modelo
`401`	Falha de autenticação ou modelo requer tier de acesso mais alto	Verifique sua chave de API e acesso ao modelo
`402`	Saldo insuficiente	Adicione créditos em venice.ai/settings/api
`404`	Modelo desconhecido	Verifique o ID do modelo em `GET /models?type=image`
`415`	Tipo de conteúdo inválido	Envie JSON com `Content-Type: application/json`
`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

Quando safe_mode está habilitado (ou moderation é auto), inspecione cabeçalhos de resposta como x-venice-is-blurred e x-venice-is-content-violation se precisar detectar resultados de moderação programaticamente.

Modelos disponíveis

Veja Modelos de imagem para a lista de modelos atual, preços e suporte a recursos.

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

Passo 1: Envie uma requisição de geração

Passo 2: Decodifique e salve a imagem

Passo 3: Retorne binário em vez de JSON (opcional)

Passo 4: Liste estilos de imagem disponíveis (opcional)

Parâmetros da requisição

Opções específicas de modelo

Geração em alta resolução

Conteúdo adulto e safe mode

Presets de estilo

Endpoint compatível com OpenAI

Controlando o embaçamento de conteúdo adulto em `/images/generations`

Dicas de prompting

Erros

Modelos disponíveis

​Endpoints

​Passo 1: Envie uma requisição de geração

​Passo 2: Decodifique e salve a imagem

​Passo 3: Retorne binário em vez de JSON (opcional)

​Passo 4: Liste estilos de imagem disponíveis (opcional)

​Parâmetros da requisição

​Opções específicas de modelo

​Geração em alta resolução

​Conteúdo adulto e safe mode

​Presets de estilo

​Endpoint compatível com OpenAI

​Controlando o embaçamento de conteúdo adulto em /images/generations

​Dicas de prompting

​Erros

​Modelos disponíveis

Endpoints

Passo 1: Envie uma requisição de geração

Passo 2: Decodifique e salve a imagem

Passo 3: Retorne binário em vez de JSON (opcional)

Passo 4: Liste estilos de imagem disponíveis (opcional)

Parâmetros da requisição

Opções específicas de modelo

Geração em alta resolução

Conteúdo adulto e safe mode

Presets de estilo

Endpoint compatível com OpenAI

Controlando o embaçamento de conteúdo adulto em `/images/generations`

Dicas de prompting

Erros

Modelos disponíveis