Pular para o conteúdo principal
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

EndpointFinalidadeQuando usar
POST /image/generateAPI nativa Venice de geração de imagensUse este para suporte completo aos recursos
GET /image/stylesLista os presets de estilo disponíveisUse antes de enviar style_preset
POST /images/generationsAPI de geração de imagens compatível com OpenAIUse 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. 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']}")

​
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 \
  -H "Authorization: Bearer $VENICE_API_KEY"
Resposta (200): 
[
  "3D Model",
  "Analog Film",
  "Anime",
  "Cinematic",
  "Digital Art"
]
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âmetroTipoObrigatórioPadrãoDescrição
modelstringSim-ID do modelo a usar na geração
promptstringSim-O que gerar
negative_promptstringNão-O que evitar na imagem
widthintegerNão1024Largura de saída em pixels para modelos baseados em pixels, como venice-sd35 e qwen-image
heightintegerNão1024Altura de saída em pixels para modelos baseados em pixels, como venice-sd35 e qwen-image
formatstringNãowebpFormato de saída: jpeg, png ou webp
variantsintegerNão1Número de imagens a gerar (1-4), apenas quando return_binary é false
return_binarybooleanNãofalseRetorna bytes de imagem crus em vez de JSON base64
safe_modebooleanNãotrueEmbaça conteúdo adulto quando habilitado
seedintegerNãoaleatórioReutilize o mesmo seed para iterações mais consistentes
cfg_scalenumberNãodependente do modeloValores mais altos fazem o modelo seguir o prompt mais de perto
style_presetstringNão-Aplica um estilo predefinido de Image Styles
aspect_ratiostringCondicional-Usado por modelos que suportam dimensionamento por proporção, como qwen-image-2, gpt-image-2, nano-banana-2 e nano-banana-pro
resolutionstringCondicional-Usado por modelos que suportam tiers de resolução como 1K, 2K ou 4K
enable_web_searchbooleanCondicionalfalsePermite que modelos suportados usem informações atuais da web; adiciona custo extra
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.

​
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": "qwen-image-2",
  "prompt": "A clean isometric illustration of an AI control room",
  "size": "1024x1024",
  "response_format": "b64_json"
}
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.

​
Dicas de prompting

  1. Comece com o sujeito, depois adicione meio, iluminação, composição e atmosfera.
  2. Coloque detalhes a evitar em negative_prompt em vez de sobrecarregar o prompt principal.
  3. Reutilize seed ao iterar para comparar mudanças de prompt sem alterar totalmente a composição.
  4. 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.
  5. Use variants durante a exploração e depois volte para uma única saída quando tiver travado a direção.

​
Erros

StatusSignificadoAção
400Parâmetros de requisição inválidosVerifique nomes de campos, tipos e restrições específicas do modelo
401Falha de autenticação ou modelo requer tier de acesso mais altoVerifique sua chave de API e acesso ao modelo
402Saldo insuficienteAdicione créditos em venice.ai/settings/api
415Tipo de conteúdo inválidoEnvie JSON com Content-Type: application/json
429Limite de taxa excedido ou modelo sobrecarregadoTente novamente com backoff; verifique o cabeçalho Retry-After
500Falha no processamento da inferênciaTente novamente
503Modelo em capacidade máximaTente novamente após um pequeno atraso
Quando o Safe Venice está habilitado, 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.