> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Criar imagem
> Cria uma imagem a partir de um prompt
## Visão geral
Para agentes de código, descubra primeiro a lista de imagens recomendadas atuais com `GET /v1/models?recommended_for=image` e, em seguida, envie o `model` selecionado explicitamente para este endpoint.
`gpt-image-2` é um modelo GPT Image com cobrança por token. A TokenLab segue o detalhamento oficial de `usage` da OpenAI para liquidar tokens de entrada de texto, entrada de imagem, entrada em cache quando informada, e saída de imagem; ele não é cobrado como preço fixo por imagem.
Para geração de imagens com `gpt-image-2`, os parâmetros públicos aceitos são `prompt`, `n`, `size`, `quality`, `response_format`, `async`, `background`, `output_format`, `output_compression` ou `compression`, `moderation` e `user`. Se `size` ou `quality` for omitido, a TokenLab usa `auto`; valores personalizados de `size` devem seguir o contrato flexível `WIDTHxHEIGHT` documentado abaixo.
`input_fidelity` não faz parte do campos admitidos atual da TokenLab para `gpt-image-2`; omita esse campo ou a solicitação retornará `400 unsupported_parameter`.
### Observações sobre comportamento dos modelos
Google Gemini não usam exatamente o mesmo contrato de seleção:
* `gemini-3.1-flash-image`, `gemini-3-pro-image` e `nano-banana-pro` aceitam `aspect_ratio` mais `resolution` (`1k`, `2k`, `4k`) para suas operações públicas text-to-image e image-edit/image-to-image.
* `nano-banana-2` aceita `aspect_ratio` mais `resolution` (`1k`, `2k`, `4k`) apenas para text-to-image no contrato atual da TokenLab.
* `gemini-2.5-flash-image`, `nano-banana` e `nano-banana-edit` aceitam `aspect_ratio`, mas não expõem seleção pública de `resolution`.
* Para solicitações Nano Banana com imagem de referência, use `nano-banana-edit` ou `nano-banana-pro` neste endpoint (`/v1/images/generations`) com `operation: "image-to-image"` e `image_urls`. Não envie solicitações de referência Nano Banana para `/v1/images/edits`.
* Em solicitações Nano Banana image-to-image, `nano-banana-pro` pode incluir `resolution` (`1k`, `2k`, `4k`); `nano-banana-edit` deve omiti-lo. `nano-banana` e `nano-banana-2` são modelos text-to-image no detalles del modelo atual.
* Imagens de referência neste endpoint podem ser enviadas como JSON `image_url` / `image_urls` ou como arquivo multipart `image`. `/v1/images/generations` não aceita `images[]` nem `file_id`; referências de `/v1/files` só valem para modelos de `/v1/images/edits` que documentam `images[].file_id`.
Para as famílias de imagem do Google, prefira `aspect_ratio` e envie `resolution` apenas quando o modelo suportar explicitamente.
Os modelos de imagem xAI Grok Imagine (`grok-imagine-image`, `grok-imagine-image-quality` e o legacy `grok-imagine-image-pro`) aceitam `aspect_ratio` mais `resolution` (`1k`, `2k`). `grok-imagine-image-pro` é mantido como ID de compatibilidade para `grok-imagine-image-quality`.
## Corpo da requisição
**Timeout de solicitações síncronas:** algumas solicitações de imagem retornam a imagem final inline e aguardam a geração terminar. Solicitações de alta resolução ou alta qualidade podem levar perto de um minuto ou mais, então configure o timeout do seu cliente HTTP para pelo menos `120s`. Se a resposta de criação incluir `status: "pending"`, `task_id` ou `poll_url`, siga o `poll_url` retornado.
Modelo a usar (por exemplo, `gpt-image-2`, `flux-pro`, `qwen-image-plus` ou `nano-banana-pro`). Consulte `GET /v1/models?recommended_for=image` para a lista recomendada atual.
Descrição em texto da imagem desejada.
URL HTTPS pública de imagem de referência para geração image-to-image. Em solicitações Nano Banana com imagem de referência, defina `operation` como `image-to-image`; `nano-banana-pro` pode incluir `resolution`, enquanto `nano-banana-edit` deve omiti-lo.
URLs HTTPS públicas de imagens de referência. Use para uma ou mais imagens de referência em requests JSON. `file_id` e `images[]` não são suportados neste endpoint.
URLs adicionais de imagens de referência específicas do modelo para provedores que distinguem imagens principais de referências.
Arquivo multipart de imagem de referência para geração image-to-image. Use quando a imagem de origem for privada ou exigir headers. Isso não é um `file_id` de /v1/files; este endpoint não aceita `file_id`.
Número de imagens a gerar (1-10, dependendo do modelo).
Tamanho da imagem. Use isto para famílias de imagem no estilo OpenAI e outros modelos que aceitam tamanhos exatos em pixels.
Para `gpt-image-2`, `size` aceita `auto` ou `WIDTHxHEIGHT`. Dimensões personalizadas devem ter ambos os lados como múltiplos de 16, a maior aresta deve ter no máximo `3840px`, a razão maior/menor lado deve ser no máximo `3:1`, e o total de pixels deve ficar entre `655,360` e `8,294,400`. `aspect_ratio` e `resolution` não fazem parte do detalles del modelo atual da TokenLab para `gpt-image-2`.
Para famílias de imagem Google Gemini, `size` é tratado como um alias de compatibilidade que mapeia para o detalles del modelo de `aspect_ratio` do modelo e, quando suportado, para `resolution`. Para esses modelos, prefira enviar `aspect_ratio` diretamente.
Seletor de proporção dependente do modelo.
Valores comuns para as famílias de imagem do Google incluem `1:1`, `16:9`, `9:16`, `3:2` e `2:3`.
Seletor de resolução de saída dependente do modelo.
Suportado em `gemini-3.1-flash-image` e `gemini-3-pro-image` para text-to-image e image-edit, em `nano-banana-pro` para text-to-image e image-to-image, e em `nano-banana-2` apenas para text-to-image. Os valores típicos são `1k`, `2k` e `4k`. Não envie esse parâmetro para famílias de imagem Gemini que só aceitam proporção, a menos que o modelo documente isso explicitamente. Para modelos de imagem xAI Grok Imagine, use `1k` ou `2k`.
Qualidade da imagem. Modelos GPT Image como `gpt-image-2` usam `auto`, `low`, `medium` ou `high`. Outras famílias de imagem podem usar valores específicos do provedor; verifique os metadados do modelo antes de enviar valores não padrão.
Formato da resposta: `url` ou `b64_json`. O padrão é `url`.
Para solicitações `gpt-image-2` Azure Official ou compatíveis com Azure, a TokenLab recebe os dados de imagem como `b64_json`. Para solicitações `url`, a TokenLab envia cada imagem ao CDN e retorna `data[].url`. Se o armazenamento CDN estiver indisponível ou o upload falhar, a solicitação falha em vez de ser convertida em uma resposta Base64. Para `b64_json`, o Base64 bruto é retornado.
Defina como `true` com `gpt-image-2` ou modelos de imagem oficiais FLUX/BFL para criar uma tarefa primeiro. Tarefas assíncronas concluídas retornam URLs independentemente do `response_format` solicitado; use solicitações síncronas se precisar de `b64_json`.
Seletor de estilo opcional. Envie apenas quando o modelo selecionado documentar explicitamente esse parâmetro; omita para `gpt-image-2` a menos que os metadados do modelo indiquem o contrário.
Um identificador único para o usuário final.
## Resposta
### Resposta em linha
Timestamp Unix da criação.
Array de imagens geradas.
Cada objeto contém:
* `url` (string): URL da imagem gerada
* `b64_json` (string): Imagem codificada em Base64 (se solicitada)
* `revised_prompt` (string): Revisão opcional do prompt quando o modelo selecionado a retorna
### Resposta de tarefa assíncrona
Defina `async: true` com `gpt-image-2` ou modelos de imagem oficiais FLUX/BFL para criar uma tarefa em vez de esperar pela imagem final na solicitação de criação. A resposta inclui `status: "pending"`, `task_id` e `poll_url`. Consulte `/v1/tasks/{task_id}` até a tarefa chegar a `completed` ou `failed`.
Tarefas assíncronas de imagem retornam apenas URLs das imagens finais. Se precisar dos dados brutos `b64_json`, use uma solicitação síncrona.
A criação da tarefa pode reservar o valor estimado. Tarefas concluídas são cobradas pelo uso real; tarefas com falha ou timeout liberam ou reembolsam a reserva.
Timestamp Unix de criação.
Identificador único da tarefa para polling.
Status inicial: `pending`.
URL relativa para fazer polling dos resultados, por exemplo `/v1/tasks/{id}`.
Vazio enquanto a tarefa estiver pendente. Tarefas de imagem concluídas retornam URLs de imagens geradas em `data[].url`.
Quando você receber `status: "pending"`, use `poll_url` ou `GET /v1/tasks/{task_id}` para recuperar o resultado.
```bash cURL theme={null}
curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-pro-image",
"prompt": "A cinematic portrait of a white cat sitting on a rainy windowsill",
"aspect_ratio": "16:9",
"resolution": "2k",
"n": 1
}'
```
```python Python theme={null}
from openai import OpenAI
client = OpenAI(
api_key="sk-your-api-key",
base_url="https://api.tokenlab.sh/v1"
)
response = client.images.generate(
model="gemini-3-pro-image",
prompt="A cinematic portrait of a white cat sitting on a rainy windowsill",
aspect_ratio="16:9",
resolution="2k",
n=1
)
print(response.data[0].url)
```
```javascript JavaScript theme={null}
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: 'sk-your-api-key',
baseURL: 'https://api.tokenlab.sh/v1'
});
const response = await client.images.generate({
model: 'gemini-3-pro-image',
prompt: 'A cinematic portrait of a white cat sitting on a rainy windowsill',
aspect_ratio: '16:9',
resolution: '2k',
n: 1
});
console.log(response.data[0].url);
```
```php PHP theme={null}
true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Authorization: Bearer sk-your-api-key'
],
CURLOPT_POSTFIELDS => json_encode([
'model' => 'gemini-3-pro-image',
'prompt' => 'A cinematic portrait of a white cat sitting on a rainy windowsill',
'aspect_ratio' => '16:9',
'resolution' => '2k',
'n' => 1
])
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
echo $data['data'][0]['url'];
```
Exemplo de família de imagem que só aceita proporção: para `gemini-2.5-flash-image`, `nano-banana` ou `nano-banana-edit`, envie `aspect_ratio` mas omita `resolution`:
```json theme={null}
{
"model": "gemini-2.5-flash-image",
"prompt": "A clean editorial product shot of a citrus soda can",
"aspect_ratio": "16:9"
}
```
Exemplo Nano Banana Pro com imagem de referência: envie a solicitação para `/v1/images/generations`, não para `/v1/images/edits`. `resolution` é opcional e pode ser `1k`, `2k` ou `4k`:
```json theme={null}
{
"model": "nano-banana-pro",
"prompt": "Create a clean cinematic character image based on the reference images",
"operation": "image-to-image",
"image_urls": ["https://example.com/reference-1.png"],
"aspect_ratio": "1:1",
"resolution": "2k"
}
```
Para imagens de origem privadas ou locais, faça upload multipart direto. Não envie `file_id` para `/v1/images/generations`:
```bash theme={null}
curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-F "model=nano-banana-pro" \
-F "prompt=Create a clean cinematic character image based on this reference" \
-F "operation=image-to-image" \
-F "image=@reference.png" \
-F "aspect_ratio=1:1" \
-F "resolution=2k"
```
```json Inline Response theme={null}
{
"created": 1706000000,
"data": [
{
"url": "https://...",
"revised_prompt": "A fluffy white cat with bright eyes sitting peacefully on a wooden windowsill, watching raindrops stream down the glass window..."
}
]
}
```
```json Async Task Response theme={null}
{
"created": 1706000000,
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"data": []
}
```
## Modelos disponíveis
Estes são exemplos atuais, não um catálogo fixo. Consulte `GET /v1/models?recommended_for=image` ou a página Models para disponibilidade e preços atualizados.
| Modelo | Tipo | Recursos |
| -------------------- | -------------------------------- | ------------------------------------------------------------ |
| `gpt-image-2` | Em linha ou baseado em tarefa | Modelo GPT Image com preço por token e tamanhos flexíveis |
| `flux-pro` | Frequentemente baseado em tarefa | Fotorrealista, alta qualidade |
| `qwen-image-plus` | Frequentemente baseado em tarefa | Bom render de texto e aderência ao prompt |
| `nano-banana-pro` | Frequentemente baseado em tarefa | Workflows com imagem de referência e saída em alta resolução |
| `grok-imagine-image` | Frequentemente baseado em tarefa | Geração de imagem xAI com seleção de aspecto e resolução |
| `ideogram-v3` | Frequentemente baseado em tarefa | Bom render de texto |
Não assuma que um modelo é sempre síncrono ou sempre assíncrono. Se a resposta de criação retornar `status: "pending"`, siga `poll_url` e faça polling até a conclusão.
## Lidando com respostas baseadas em tarefa
Para modelos de imagem, sempre verifique se a resposta contém `status: "pending"`:
```python theme={null}
import requests
import time
def generate_image(prompt, model="flux-pro"):
# Criar solicitação de imagem
response = requests.post(
"https://api.tokenlab.sh/v1/images/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={"model": model, "prompt": prompt}
)
data = response.json()
# Verifica se é baseada em tarefa
if data.get("status") == "pending":
task_id = data["task_id"]
poll_url = data.get("poll_url")
print(f"Tarefa de imagem iniciada: {task_id}")
# Fazer polling do resultado
while True:
status_resp = requests.get(
f"https://api.tokenlab.sh{poll_url}" if poll_url else f"https://api.tokenlab.sh/v1/tasks/{task_id}",
headers={"Authorization": "Bearer sk-your-api-key"}
)
status_data = status_resp.json()
if status_data["status"] == "completed":
return status_data["data"][0]["url"]
elif status_data["status"] == "failed":
raise Exception(status_data.get("error", "Falha na geração"))
time.sleep(3)
else:
# Resposta em linha
return data["data"][0]["url"]
# Uso
url = generate_image("a beautiful sunset over mountains", model="flux-pro")
print(f"Imagem gerada: {url}")
```