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`. Uma rejeição explícita pela política de conteúdo do provedor pode omitir variantes individuais; veja Resultados parciais de variantes
`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
`lora_strength`	integer	Não	-	Intensidade (`0`-`100`) dos LoRAs adicionais que um modelo usa. Veja Intensidade de LoRA
`style_preset`	string	Não	-	Aplica um estilo predefinido de Image Styles
`style_references`	array	Não	-	Imagens de referência de estilo que guiam a estética da saída. Cada entrada é `{ "image": <url or base64>, "strength": <0.1-1> }`. Apenas modelos suportados; veja Referências de estilo
`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.

Intensidade de LoRA

Alguns modelos de imagem aplicam LoRAs adicionais. lora_strength (integer, de 0 a 100) define a intensidade com que eles são aplicados e só afeta os modelos que os utilizam. A API não aceita arquivos LoRA personalizados, e nenhum endpoint lista os LoRAs que um modelo usa. lora_strength é o único controle de LoRA.

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.

Referências de estilo

style_references vai um passo além de style_preset: em vez de um preset nomeado, ele condiciona a geração a uma ou mais imagens de referência. Cada entrada tem um image e um strength opcional:

{
  "model": "krea-v2-large",
  "prompt": "A quiet Venetian courtyard at golden hour",
  "style_references": [
    {
      "image": "https://example.com/reference-painting.png",
      "strength": 0.5
    }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`image`	string	Sim	Imagem de referência como URL `http://` ou `https://`, string base64 ou data URI base64. Deve ser uma imagem raster (JPEG, PNG, WebP, HEIF, HEIC ou AVIF), não pode ser SVG e deve ter menos de 8 MB
`strength`	number	Não	Com que intensidade a referência guia a saída, de `0.1` a `1`. O padrão é `0.5`. Ignorado por modelos em que `supportsStyleReferenceStrength` é `false`

O suporte varia por modelo. Verifique GET /models?type=image:

model_spec.supportsStyleReferences é true apenas nos modelos que aceitam o campo.
model_spec.constraints.maxStyleReferences é o número de entradas que o modelo aceita.
model_spec.constraints.supportsStyleReferenceStrength indica se strength tem algum efeito.

curl -s "https://api.venice.ai/api/v1/models?type=image" \
  | jq -r '.data[] | select(.model_spec.supportsStyleReferences == true) | "\(.id) max=\(.model_spec.constraints.maxStyleReferences)"'

Enviar style_references para um modelo sem suporte retorna 400, assim como exceder o limite desse modelo ou enviar uma referência corrompida, inacessível ou grande demais. Alguns modelos cobram uma taxa de referência de estilo por imagem retornada, além do preço base da imagem, por exemplo Krea v2 Large e Krea v2 Medium. A taxa só é cobrada pelas imagens efetivamente retornadas. Veja Modelos de imagem para os preços base por imagem.

Resultados parciais de variantes

Com variants maior que 1, variantes individuais podem ser rejeitadas pela política de conteúdo do provedor enquanto as demais são geradas com sucesso. Nesse caso, o endpoint ainda retorna 200 com menos imagens do que você solicitou:

Quando uma ou mais variantes são omitidas, o corpo JSON inclui content_policy_violation_count, o número de variantes omitidas.
O cabeçalho de resposta x-venice-content-violation-count traz a mesma contagem.
x-venice-is-content-violation e x-venice-is-blurred descrevem as imagens que foram retornadas.

Se todas as variantes solicitadas forem rejeitadas, nenhuma imagem é retornada e a requisição falha com 422. Não presuma que len(images) == variants; compare o tamanho do array com variants e, quando presente, verifique content_policy_violation_count.

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. Alguns parâmetros da OpenAI são aceitos por compatibilidade com SDKs, mas são ignorados (n é restrito a 1):

Parâmetro	Comportamento em `/images/generations`
`quality`	Aceito e ignorado. A cobrança usa o tier de qualidade padrão do modelo
`style`	Aceito e ignorado
`output_compression`	Aceito e ignorado
`user`	Aceito, descartado e não é um alias de `anon_user_id`
`n`	Apenas `1` é suportado; outros valores são rejeitados pela validação

Não há controle de tier nesta rota: não existe campo resolution ou aspect_ratio, e quality não pode aumentar nem reduzir a cobrança. Para modelos GPT Image com tiers, use o endpoint nativo /image/generate quando precisar escolher quality, resolution ou aspect_ratio. 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, style_references, 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`
`422`	Violação da política de conteúdo	O provedor rejeitou explicitamente o prompt ou a imagem. Ajuste o prompt ou troque de modelo. O corpo inclui `error` e um booleano `retryable`, e também pode incluir `suggested_prompt` e `recommended_model`
`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

Intensidade de LoRA

Conteúdo adulto e safe mode

Presets de estilo

Referências de estilo

Resultados parciais de variantes

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

​Intensidade de LoRA

​Conteúdo adulto e safe mode

​Presets de estilo

​Referências de estilo

​Resultados parciais de variantes

​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

Intensidade de LoRA

Conteúdo adulto e safe mode

Presets de estilo

Referências de estilo

Resultados parciais de variantes

Endpoint compatível com OpenAI

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

Dicas de prompting

Erros

Modelos disponíveis