Nano Banana API

Recursos

Preços e créditos

Each image costs 2 credits, including all supported resolutions and formats. Credits are reserved on acceptance, settled on success and refunded on failure. Generation times out after 30 minutes; refund_failed means refund recovery is pending.

Request idempotency is not supported. Each valid POST creates a new billable task. If a submission outcome is uncertain, query the returned taskId; retrying POST can create another task.

Autenticação

Crie uma chave de API no painel. A chave completa é exibida apenas uma vez. Guarde-a com segurança no seu servidor e envie-a como um token Bearer em cada requisição.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Defina a variável de ambiente SEEVIO_API_KEY antes de rodar os exemplos. Os exemplos em JavaScript rodam no servidor com Node.js; os de Python utilizam a biblioteca requests.

Corpo da requisição

Parâmetros de entrada

Aspect ratio defaults to auto. Unknown fields, including output quantity, are rejected. Each request generates exactly one image.

Início rápido

Envie esta requisição simplificada, salve o taskId retornado e use o exemplo de consulta abaixo. O valor de créditos indicado na resposta de criação é o montante reservado.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

Exemplo de resposta de criação de tarefa

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 2
}

Texto para imagem

Generate one image asynchronously per request. Supports text-to-image and image-to-image generation with your Seevio API key.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

Imagem para imagem

For image editing, set generation_type to image-to-image and provide image_urls. All other parameters use the same contract.

Substitua as URLs de exemplo de media.com pelos seus próprios arquivos HTTPS públicos. Os links de exemplo servem apenas para ilustrar a estrutura da requisição e não representam arquivos reais para download.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana",
  "input": {
    "prompt": "Change the teapot to matte sage green. Preserve its shape and the studio lighting.",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "generation_type": "image-to-image",
    "image_urls": [
      "https://example.com/teapot.png"
    ]
  }
}'

Consultar tarefa

Substitua o ID de exemplo pelo taskId recebido no retorno da criação. As consultas só retornam tarefas de propriedade do usuário associado à chave de API; IDs inexistentes ou de terceiros retornam HTTP 404.

Recomendamos consultar a cada 10 ou 20 segundos inicialmente, aplicar recuo (backoff) caso receba HTTP 429 e parar assim que o status for completed ou failed. Para produção, prefira webhooks. Cada exemplo abaixo executa uma consulta única.

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

Na fila

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana",
  "credits": 2,
  "status": "queued",
  "billing_status": "reserved",
  "failed_reason": null,
  "data": {
    "results": [],
    "image_expires_at": null,
    "processing_time": null
  }
}

Concluído

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana",
  "credits": 2,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

Falhou

Quando a consulta retornar status=failed, significa que a geração falhou. Verifique o motivo em failed_reason e o resultado do estorno em billing_status. Neste exemplo, refunded indica que os créditos foram devolvidos. O campo credits mantém o valor original reservado, e a resposta não inclui data.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana",
  "credits": 2,
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "Image generation failed."
}

Result links are provided for 30 days after storage. After expiry, results is empty.

Webhooks

Defina o callback_url na requisição de criação para receber um POST em JSON assim que a tarefa for concluída ou falhar. Responda com status 2xx em até 15 segundos. Envios malsucedidos serão reentados; trate as requisições de forma idempotente utilizando o ID da tarefa.

O seu endpoint de callback deve aceitar requisições POST com um corpo no formato JSON (Content-Type: application/json).

Criar tarefa contendo callback

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "generation_type": "text-to-image"
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

Callbacks use the task query response structure; refunded failure notifications also include top-level credits_refunded. Use id to identify the task and status to distinguish completed from failed. Notifications may repeat: process them idempotently by id and status. Callbacks are unsigned; verify the task with the authenticated query endpoint. Delivery failure does not refund a successful task.

Tarefa concluída: payload de callback de sucesso

created_at indica a criação do evento; task_created_at indica a criação da tarefa, em segundos Unix. Os exemplos mostram os campos recomendados; as respostas podem incluir campos adicionais.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "nano-banana",
  "credits": 2,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  },
  "task_created_at": 1789171200
}

Falha na tarefa: payload de callback de erro

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "nano-banana",
  "credits": 2,
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "Image generation failed.",
  "task_created_at": 1789171200,
  "credits_refunded": 2
}

Exemplo de código receptor

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const imageUrls = callbackData.data.results;
    // Save the image URLs and mark this task as completed in your application.
    console.log(callbackData.id, imageUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

  return new Response(null, { status: 200 });
}

Este exemplo em Next.js lê o corpo do callback em JSON e trata diretamente as tarefas concluídas e com falha. Recomendamos implementar persistência e eliminação de duplicidades por ID de tarefa na sua aplicação, além de enfileirar processos demorados antes de responder ao callback.

Erros

Erros de requisição retornam um objeto contendo code e message. Uma tarefa aceita com sucesso ainda pode falhar posteriormente durante o processamento; monitore seu status por consulta ou configure um callback de falha.

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}

Errors use error.code and error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. Insufficient provider balance is not a customer 402 error.

Limites de requisição

Criação de tarefas: por padrão, cada chave de API permite até 100 requisições por minuto. No momento, limites personalizados não estão disponíveis.

Consulta de tarefas: por padrão, cada chave de API permite até 120 requisições por minuto. As requisições de consulta e de criação de tarefas são contabilizadas separadamente.

Image and video creation requests share the same API key rate limit.

Respostas com HTTP 429 incluem o cabeçalho Retry-After: 60 para criação e Retry-After: 5 para consultas. Implemente recuo gradual (backoff) e evite consultas mais frequentes do que o recomendado.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded."
  }
}