Imagens
Criar imagem
Cria uma imagem a partir de um prompt
Visão geral
Use GET /v1/models?recommended_for=image para obter os modelos de imagem atuais e, em seguida, envie o model selecionado explicitamente.
Cada modelo aceita suas próprias operações e campos. GET /v1/models/{model} (Obter modelo) fornece o endpoint para cada operação em tokenlab.request_format_summary.request_endpoint_by_operation, e os campos, valores e limites aceitos para cada operação em tokenlab.request_format_details.operation_constraints. Um campo que o modelo não lista pode retornar 400 unsupported_parameter. Uma operação enviada para o endpoint incorreto retorna 400 unsupported_endpoint.
Tarefas e resultados de imagem:
- Modelos que listam
asyncentre seus parâmetros suportados podem criar uma tarefa primeiro: envieasync: truee, em seguida, faça polling emGET /v1/tasks/{id}. - Os links de imagens são salvos por 30 dias; consulte Retenção de dados.
- Envie um cabeçalho
Idempotency-Keypara tentar novamente uma requisição de criação com segurança após um timeout; consulte Repetir com segurança usando uma chave de idempotência.
O gpt-image-2 é um modelo GPT Image tarifado por token. O TokenLab segue o detalhamento oficial de uso da OpenAI para tokens de entrada de texto, entrada de imagem, entrada em cache informada e saída de imagem; ele não é cobrado como um modelo de preço fixo por imagem.
Para a geração de imagens com o gpt-image-2, os parâmetros públicos suportados são prompt, n, size, quality, response_format, async, background, output_format, output_compression ou compression, moderation e user. background aceita auto ou opaque; transparent não é suportado. Omita size ou quality para permitir que o TokenLab use auto; valores personalizados de size devem usar o contrato flexível WIDTHxHEIGHT documentado abaixo.
input_fidelity não faz parte dos campos atualmente suportados pelo TokenLab para o gpt-image-2; omita-o ou a requisição retornará 400 unsupported_parameter.
Saída em SVG e GIF
gpt-image-2.6-flare e gpt-image-2.6-sunburst podem retornar um SVG ou um GIF animado em vez de uma imagem rasterizada. Outros modelos rejeitam esses formatos.
- SVG: envie
output_format: "svg"esvg: {"model": "..."}. O modelo de imagem primeiro desenha uma imagem de referência, então o modelo autor escreve o SVG a partir dela.svg.modelé obrigatório; a lista de detalhes do modelo apresenta seus valores aceitos emparameter_options(svg.model). Você também pode enviarsvg.reasoning.effort. O SVG funciona apenas neste endpoint, comn: 1e sempartial_imagesououtput_compression. - GIF: envie
output_format: "gif".frame_count(2 a 16, padrão 9) define o número de quadros, eframe_duration_ms(20 a 2000, padrão 200) define o tempo de cada quadro.sizeé o tamanho de um quadro. O GIF não aceitapartial_imagesououtput_compression.
O resultado está em data[].b64_json ou data[].url, da mesma forma que outras imagens. Decodifique um SVG como texto XML UTF-8 e salve-o como .svg; salve um GIF como .gif.
Faturamento: os tokens de imagem são cobrados de acordo com os preços de token do modelo, e os quadros do GIF são tokens de saída de imagem. Uma solicitação de SVG também cobra os tokens do modelo autor, que a resposta reporta em svg_usage, conforme os preços de criação de SVG mostrados na página do modelo.
Observações sobre o comportamento dos modelos
Os modelos da família de imagem Google Gemini não compartilham o mesmo contrato de seletores:
gemini-3.1-flash-image,gemini-nano-banana-2.1,gemini-3-pro-image,nano-banana-2.1enano-banana-prosuportamaspect_ratioalém deresolution(1k,2k,4k) para suas operações públicas de text-to-image, image-to-image e image-edit.nano-banana-2suportaaspect_ratioeresolution(1k,2k,4k) para geração text-to-image e image-to-image.gemini-3.1-flash-lite-imageenano-banana-2-litesuportam text-to-image, image-to-image e image-edit apenas na resolução1k.nano-bananasuportaaspect_ratio, mas não expõe a seleção pública deresolution.- Para image-to-image com
gemini-3.1-flash-image,gemini-nano-banana-2.1,gemini-3.1-flash-lite-imageougemini-3-pro-image, use este endpoint comoperation: "image-to-image"e imagens de referência. Envie requisições de image-edit para estes modelos para/v1/images/edits. - Para requisições com imagens de referência do Nano Banana, use
nano-banana-2,nano-banana-2.1,nano-banana-2-liteounano-banana-proneste endpoint (/v1/images/generations) comoperation: "image-to-image"eimage_urls. Requisições de image-edit paranano-banana-2,nano-banana-2.1,nano-banana-2-liteenano-banana-protambém usam este endpoint, comoperation: "image-edit". Não envie requisições com imagem de referência do Nano Banana para/v1/images/edits. - Imagens de referência neste endpoint podem ser fornecidas como JSON
image_url/image_urls, ou como um arquivo multipartimage.images[]efile_idnão são aceitos em/v1/images/generations; crie referências em/v1/filesapenas para modelos de/v1/images/editsque documentemimages[].file_id.
Para famílias de imagem do Google, prefira aspect_ratio e envie resolution apenas quando o modelo suportar isso explicitamente.
Os modelos de imagem xAI Grok Imagine (grok-imagine-image e grok-imagine-image-2.0) suportam aspect_ratio além de resolution (1k, 2k). Text-to-image usa este endpoint. Suas requisições de image-to-image e image-edit usam /v1/images/edits.
O hy-image-v3.5-preview cria uma imagem de 1024x1024 por requisição a partir de texto neste endpoint e suporta apenas response_format: "url". Ele edita imagens de referência em /v1/images/edits.
Corpo da requisição
Timeout para requisições síncronas: Algumas requisições de imagem retornam a imagem final em linha (inline) e aguardam a conclusão da geração. Requisições de alta resolução ou alta qualidade podem levar cerca de um minuto ou mais; portanto, defina o timeout do seu cliente HTTP para pelo menos 120s. Se a resposta de criação incluir status: "pending", task_id ou poll_url, faça polling em GET /v1/tasks/{task_id}.
Modelo a ser usado (por exemplo, gpt-image-2, flux-pro-1.1 ou nano-banana-pro). Consulte GET /v1/models?recommended_for=image para obter a lista recomendada atual.
Descrição em texto da imagem desejada, de até 32.000 caracteres. Obrigatório para todos os modelos cujos detalhes listam prompt.
text-to-image, image-to-image ou image-edit. Quando omitido, será image-to-image se a requisição contiver uma imagem de referência; caso contrário, text-to-image. Defina image-edit para modelos cuja operação de edição esteja neste endpoint, como o nano-banana-pro. Enviar text-to-image com uma imagem de referência retorna 400 invalid_parameter.
URL pública da imagem para geração image-to-image. Para requisições com imagens de referência do Nano Banana, defina operation como image-to-image; o nano-banana-pro pode incluir resolution.
URLs públicas de imagens de referência, até 16. Use isso para uma ou mais imagens de referência em requisições JSON. file_id e images[] não são suportados neste endpoint.
URLs adicionais de imagens de referência, até 16, para modelos que diferenciam entradas primárias de referências.
Arquivo de imagem de referência multipart para geração image-to-image. Use isso quando a imagem de origem for privada ou protegida por cabeçalhos. Isso é diferente de um file_id do /v1/files, que não é aceito neste endpoint.
1Número de imagens a serem geradas (1-10, dependendo do modelo).
Tamanho da imagem. Use para famílias de imagens no estilo OpenAI e outros modelos que aceitam tamanhos exatos em pixels.
Para o gpt-image-2, size aceita auto ou WIDTHxHEIGHT. Ambas as dimensões personalizadas devem ser múltiplos de 16, a borda mais longa deve ter no máximo 3840px, a proporção entre o lado maior e o menor deve ser de no máximo 3:1, e o total de pixels deve estar entre 655.360 e 8.294.400. aspect_ratio e resolution não fazem parte dos detalhes atuais do modelo no TokenLab para o gpt-image-2.
Para modelos de imagem do Google com níveis de resolução (gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image, gemini-3.1-flash-lite-image, nano-banana-2, nano-banana-2.1 e nano-banana-pro), size aceita um tamanho de saída da tabela de tamanhos do modelo, como 1376x768 (16:9 a 1K), ou um nível de resolução: 1K, 2K ou 4K. O TokenLab envia um nível como resolution, portanto a requisição e seu preço são os mesmos que ao usar resolution. Um nível não suportado pelo modelo (por exemplo, 2K no gemini-3.1-flash-lite-image), ou um nível diferente de resolution, retorna 400 com o código invalid_image_size_contract e os allowed_resolutions do modelo. Para esses modelos, o formato recomendado é aspect_ratio com resolution.
Seletor de proporção de tela (aspect ratio) dependente do modelo.
Valores comuns para a família de imagens do Google incluem 1:1, 16:9, 9:16, 3:2 e 2:3.
Resolução de saída dependente do modelo. gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image, nano-banana-2, nano-banana-2.1 e nano-banana-pro suportam 1k, 2k e 4k; modelos de imagem Grok Imagine suportam 1k e 2k. Omita este campo, a menos que o modelo e a operação selecionados o suportem explicitamente.
Qualidade da imagem. Modelos GPT Image como o gpt-image-2 usam auto, low, medium ou high. Outros modelos podem usar valores diferentes; verifique os detalhes do modelo antes de enviar um valor diferente do padrão.
Formato de arquivo da imagem: png, jpeg ou webp. gpt-image-2.6-flare e gpt-image-2.6-sunburst também aceitam svg e gif; veja Saída SVG e GIF.
Configurações de SVG, apenas com output_format: "svg". model (obrigatório) seleciona o modelo autor que escreve o SVG. reasoning.effort define opcionalmente seu esforço de raciocínio.
9Número de quadros do GIF, de 2 a 16. Apenas com output_format: "gif".
200Tempo de cada quadro do GIF em milissegundos, de 20 a 2000. Apenas com output_format: "gif".
Como as imagens são retornadas: url ou b64_json.
- Omitido: quando o modelo retorna bytes de imagem, cada imagem fica em
data[].b64_jsone também emdata[].urlquando armazenada pelo TokenLab. Quando o modelo retorna um link, cada imagem fica emdata[].url. url: cada imagem fica apenas emdata[].url.b64_json: cada imagem fica apenas emdata[].b64_jsoncomo dados em Base64.
Os links são URLs de resultados de mídia do TokenLab. Eles permanecem válidos por 30 dias. Consulte Retenção de dados.
falseDefina como true para criar uma tarefa primeiro. Apenas modelos que listam async entre seus parâmetros suportados aceitam isso, por exemplo gpt-image-2, flux-pro-1.1, nano-banana-pro e seedream-5.0-lite; para qualquer outro modelo, a requisição retorna 400 unsupported_async_mode. Tarefas de imagem assíncronas concluídas retornam URLs independentemente do response_format solicitado; use requisições síncronas quando precisar de b64_json.
Seletor de estilo opcional. Envie apenas quando o modelo selecionado o documentar explicitamente; omita-o para o gpt-image-2, a menos que os metadados do modelo indiquem o contrário.
Um identificador exclusivo para o usuário final.
Alguns modelos também aceitam campos como negative_prompt, seed, width, height, steps, guidance_scale ou mask_url. Envie-os somente quando os detalhes do modelo os listarem. stream: true não é suportado e retorna 400 unsupported_parameter.
Resposta
Resposta inline
Timestamp Unix de criação.
Array de imagens geradas.
Cada objeto contém:
url(string): URL do resultado de mídia do TokenLab da imagem, válida por 30 dias. Não está presente quandoresponse_formatforb64_json. Quandoresponse_formatfor omitido, estará ausente se o TokenLab não tiver conseguido armazenar a imagem.b64_json(string): Dados da imagem em Base64. Presente quandoresponse_formatforb64_json, ou quando for omitido e o modelo retornar bytes de imagem.revised_prompt(string): Revisão opcional do prompt, quando o modelo selecionado retornar uma
Contagem de tokens (input_tokens, output_tokens, total_tokens e seus detalhes) para modelos tarifados por token como o gpt-image-2, quando disponível.
Contagens de tokens do modelo de criação de SVG (model, input_tokens, output_tokens, reasoning_tokens, total_tokens). Presente apenas para saída SVG. Esses tokens não estão em usage e são cobrados de acordo com os preços de criação de SVG.
Resposta de tarefa assíncrona
Defina async: true em um modelo compatível para criar uma tarefa em vez de esperar pela imagem final na requisição de criação. A resposta inclui status: "pending", task_id e poll_url. Faça polling em /v1/tasks/{task_id} até que a tarefa alcance completed ou failed.
Tarefas assíncronas de imagem retornam apenas URLs finais de imagens. Se você precisar dos dados brutos da imagem em b64_json, use uma requisição síncrona.
O faturamento pode reservar o valor estimado quando a tarefa for criada. Tarefas concluídas são cobradas pelo uso real, e tarefas com falha ou que atingiram timeout são liberadas ou reembolsadas.
Timestamp Unix de criação.
Identificador exclusivo 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 das imagens geradas em data[].url.
Quando você receber status: "pending", chame GET /v1/tasks/{task_id} para recuperar o resultado.
Requisição
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"
}'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",
extra_body={"aspect_ratio": "16:9", "resolution": "2k"}
)
print(response.data[0].url)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'
});
console.log(response.data[0].url);<?php
$ch = curl_init('https://api.tokenlab.sh/v1/images/generations');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => 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'
])
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
echo $data['data'][0]['url'];Exemplo de família de imagens apenas com proporção: para nano-banana, envie aspect_ratio, mas omita resolution:
{
"model": "nano-banana",
"prompt": "A clean editorial product shot of a citrus soda can",
"aspect_ratio": "16:9"
}Exemplo com imagem de referência para o Nano Banana Pro: envie a requisição para /v1/images/generations, não para /v1/images/edits. resolution é opcional e pode ser definida como 1k, 2k ou 4k:
{
"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"
}Exemplo de upload multipart direto para imagens de origem privadas ou locais. Não passe um file_id para /v1/images/generations:
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"Resposta
{
"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..."
}
]
}Erros
Erros de requisição retornam 400 (413 para uploads muito grandes) com um error.code. Códigos comuns para requisições de imagem:
| Código | Causa |
|---|---|
unsupported_parameter | O modelo não lista o campo, ou stream é true |
unsupported_operation | O modelo não possui essa operation |
unsupported_endpoint | A operação para este modelo está em outro endpoint, como /v1/images/edits |
unsupported_async_mode | O modelo não suporta async: true |
invalid_resolution, invalid_aspect_ratio, invalid_parameter_value, too_many_items | Um valor está fora do que o modelo aceita. O erro especifica os valores aceitos |
invalid_image_size_contract | Um size ou nível não suportado pelo modelo, ou que conflita com resolution |
prompt_too_long | O prompt é mais longo do que o modelo aceita |
request_too_large, file_too_large | Um upload ultrapassa o limite de tamanho (50 MiB por arquivo, 200 MiB para todas as entradas) |
Para saldo (402), limite de taxa (429) e regras de novas tentativas, consulte Tratamento de erros.
Escolher um modelo
Consulte GET /v1/models?recommended_for=image ou use a página de modelos para conferir disponibilidade atual, recursos e preços.
Não defina um modelo no código como sendo sempre síncrono ou sempre assíncrono. Uma requisição sem async: true ainda pode retornar status: "pending"; sempre que a resposta de criação trouxer status: "pending" ou status: "processing", faça polling em GET /v1/tasks/{task_id} até a conclusão.
Como lidar com respostas baseadas em tarefas
Para modelos de imagem, sempre verifique se a resposta contém status: "pending" / status: "processing":
import requests
import time
def generate_image(prompt, model="gpt-image-2"):
# Create image request
response = requests.post(
"https://api.tokenlab.sh/v1/images/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={"model": model, "prompt": prompt, "async": True},
timeout=120
)
response.raise_for_status()
data = response.json()
# Check if task-based
if data.get("status") in ("pending", "processing"):
task_id = data["task_id"]
print(f"Image task started: {task_id}")
# Poll for result
deadline = time.time() + 600
while time.time() < deadline:
status_resp = requests.get(
f"https://api.tokenlab.sh/v1/tasks/{task_id}",
headers={"Authorization": "Bearer sk-your-api-key"},
timeout=30
)
status_resp.raise_for_status()
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", "Generation failed"))
time.sleep(3)
raise TimeoutError(f"Image task {task_id} did not finish in time")
else:
# Inline response
return data["data"][0]["url"]
# Usage
url = generate_image("a beautiful sunset over mountains", model="gpt-image-2")
print(f"Generated image: {url}")Exemplo do Hy Image 3.5 Preview. Ele aceita apenas size 1024x1024 e n 1:
{
"model": "hy-image-v3.5-preview",
"prompt": "A yellow lemon on a white table",
"size": "1024x1024",
"n": 1,
"response_format": "url"
}Autorização
BearerAuth Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.
Local: header
Cabeçalhos
Política de entrega por solicitação. Substitui os padrões da API key e do Workspace. Tenta automaticamente o TokenLab Verified primeiro e pode alternar uma vez para Official apenas antes da saída, aceitação da solicitação ou criação de recurso persistente.
Valores permitidos
- "auto"
- "verified"
- "official"
Chave opcional que torna uma requisição de imagem segura para novas tentativas se a requisição criou uma tarefa. Envie um novo valor único, como um UUID, para cada requisição. Uma nova tentativa com a mesma chave e o mesmo corpo retorna essa tarefa e não cria, despacha ou cobra uma segunda tarefa. Para uma requisição que retorna a imagem diretamente, uma nova tentativa com a mesma chave pode retornar um status de tarefa em vez da imagem, ou 409 com idempotent_response_not_replayable. Um corpo diferente com uma chave que já foi aceita é rejeitado; o código de status e o código de erro para esse caso não são garantidos. Uma chave com mais de 255 caracteres é ignorada e a requisição não terá proteção de idempotência. Veja Tente novamente com segurança usando uma chave de idempotência.
1 <= length <= 255Resposta
application/json
application/json
application/json
application/json
application/json
application/json
application/json