> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Geração de imagens
> Gere imagens a partir de texto com a API nativa da Venice ou o endpoint compatível com OpenAI, com controles de estilo e saída binária ou em base64.
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:**
```bash theme={"system"}
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:**
```bash theme={"system"}
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:**
```bash theme={"system"}
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:
```json theme={"system"}
{
"model": "nano-banana-pro",
"prompt": "A serene canal in Venice at sunset",
"aspect_ratio": "16:9",
"resolution": "2K"
}
```
Use [Modelos de imagem](/models/image) ou a [API de Models](/api-reference/endpoint/models/list) para confirmar quais campos de dimensionamento cada modelo aceita.
**Resposta (200):**
```json theme={"system"}
{
"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
```python Python theme={"system"}
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']}")
```
```javascript Node.js theme={"system"}
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.
```bash theme={"system"}
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`:
```bash theme={"system"}
curl https://api.venice.ai/api/v1/image/styles \
-H "Authorization: Bearer $VENICE_API_KEY"
```
**Resposta (200):**
```json theme={"system"}
[
"3D Model",
"Analog Film",
"Anime",
"Cinematic",
"Digital Art"
]
```
Depois, passe um desses valores na sua requisição de geração:
```json theme={"system"}
{
"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](/api-reference/endpoint/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](/models/image) e a [API de Models](/api-reference/endpoint/models/list) 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:
```json theme={"system"}
{
"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`:
```json theme={"system"}
{
"model": "gpt-image-2",
"prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting",
"aspect_ratio": "16:9",
"resolution": "4K"
}
```
```json theme={"system"}
{
"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](/models/image) 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](/api-reference/endpoint/image/styles):
```json theme={"system"}
{
"model": "qwen-image-2",
"prompt": "A futuristic Venice skyline at sunrise",
"style_preset": "3D Model"
}
```
Veja [Image Styles](/api-reference/endpoint/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:**
```json theme={"system"}
{
"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
| 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](https://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](/models/image) para a lista de modelos atual, preços e suporte a recursos.