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. 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 \
  -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â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` e `qwen-image`
`height`	integer	Não	`1024`	Altura de saída em pixels para modelos baseados em pixels, como `venice-sd35` e `qwen-image`
`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

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

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

Guides

Getting Started

Text & Chat

Image & Video

Agents & Integrations

Agent Tooling

Coding Tools

SDKs & Frameworks

Projects

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

Presets de estilo

Endpoint compatível com OpenAI

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

​Presets de estilo

​Endpoint compatível com OpenAI

​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

Presets de estilo

Endpoint compatível com OpenAI

Dicas de prompting

Erros

Modelos disponíveis