Imagens

Criar imagem

Cria uma imagem a partir de um prompt

POST
/v1/images/generations

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 async entre seus parâmetros suportados podem criar uma tarefa primeiro: envie async: true e, em seguida, faça polling em GET /v1/tasks/{id}.
  • Os links de imagens são salvos por 30 dias; consulte Retenção de dados.
  • Envie um cabeçalho Idempotency-Key para 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" e svg: {"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 em parameter_options (svg.model). Você também pode enviar svg.reasoning.effort. O SVG funciona apenas neste endpoint, com n: 1 e sem partial_images ou output_compression.
  • GIF: envie output_format: "gif". frame_count (2 a 16, padrão 9) define o número de quadros, e frame_duration_ms (20 a 2000, padrão 200) define o tempo de cada quadro. size é o tamanho de um quadro. O GIF não aceita partial_images ou output_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.1 e nano-banana-pro suportam aspect_ratio além de resolution (1k, 2k, 4k) para suas operações públicas de text-to-image, image-to-image e image-edit.
  • nano-banana-2 suporta aspect_ratio e resolution (1k, 2k, 4k) para geração text-to-image e image-to-image.
  • gemini-3.1-flash-lite-image e nano-banana-2-lite suportam text-to-image, image-to-image e image-edit apenas na resolução 1k.
  • nano-banana suporta aspect_ratio, mas não expõe a seleção pública de resolution.
  • Para image-to-image com gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3.1-flash-lite-image ou gemini-3-pro-image, use este endpoint com operation: "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-lite ou nano-banana-pro neste endpoint (/v1/images/generations) com operation: "image-to-image" e image_urls. Requisições de image-edit para nano-banana-2, nano-banana-2.1, nano-banana-2-lite e nano-banana-pro também usam este endpoint, com operation: "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 multipart image. images[] e file_id não são aceitos em /v1/images/generations; crie referências em /v1/files apenas para modelos de /v1/images/edits que documentem images[].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}.

modelstringobrigatório

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.

promptstringobrigatório

Descrição em texto da imagem desejada, de até 32.000 caracteres. Obrigatório para todos os modelos cujos detalhes listam prompt.

operationstring

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.

image_urlstring

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.

image_urlsstring[]

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.

reference_image_urlsstring[]

URLs adicionais de imagens de referência, até 16, para modelos que diferenciam entradas primárias de referências.

imagefile

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.

nintegerpadrão: 1

Número de imagens a serem geradas (1-10, dependendo do modelo).

sizestring

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.

aspect_ratiostring

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.

resolutionstring

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.

qualitystring

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.

output_formatstring

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.

svgobject

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.

frame_countintegerpadrão: 9

Número de quadros do GIF, de 2 a 16. Apenas com output_format: "gif".

frame_duration_msintegerpadrão: 200

Tempo de cada quadro do GIF em milissegundos, de 20 a 2000. Apenas com output_format: "gif".

response_formatstring

Como as imagens são retornadas: url ou b64_json.

  • Omitido: quando o modelo retorna bytes de imagem, cada imagem fica em data[].b64_json e também em data[].url quando armazenada pelo TokenLab. Quando o modelo retorna um link, cada imagem fica em data[].url.
  • url: cada imagem fica apenas em data[].url.
  • b64_json: cada imagem fica apenas em data[].b64_json como 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.

asyncbooleanpadrão: false

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

stylestring

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.

userstring

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

createdinteger

Timestamp Unix de criação.

dataarray

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 quando response_format for b64_json. Quando response_format for omitido, estará ausente se o TokenLab não tiver conseguido armazenar a imagem.
  • b64_json (string): Dados da imagem em Base64. Presente quando response_format for b64_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
usageobject

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.

svg_usageobject

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.

createdinteger

Timestamp Unix de criação.

task_idstring

Identificador exclusivo da tarefa para polling.

statusstring

Status inicial: pending.

poll_urlstring

URL relativa para fazer polling dos resultados, por exemplo /v1/tasks/{id}.

dataarray

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
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"
  }'
Python
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)
JavaScript
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
<?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ódigoCausa
unsupported_parameterO modelo não lista o campo, ou stream é true
unsupported_operationO modelo não possui essa operation
unsupported_endpointA operação para este modelo está em outro endpoint, como /v1/images/edits
unsupported_async_modeO modelo não suporta async: true
invalid_resolution, invalid_aspect_ratio, invalid_parameter_value, too_many_itemsUm valor está fora do que o modelo aceita. O erro especifica os valores aceitos
invalid_image_size_contractUm size ou nível não suportado pelo modelo, ou que conflita com resolution
prompt_too_longO prompt é mais longo do que o modelo aceita
request_too_large, file_too_largeUm 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
AuthorizationBearer <token>

Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.

Local: header

Cabeçalhos

X-TokenLab-Delivery-Policy?string

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"
Idempotency-Key?string

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.

Comprimento1 <= length <= 255

Corpo da requisição

Resposta

application/json

application/json

application/json

application/json

application/json

application/json

application/json