Nano Banana Images API Integração e Uso

​

Processo de Solicitação

📘 Documentação Completa: Nano Banana Images API →

​

Visão Geral da Interface

• Base URL: https://api.acedata.cloud
• Endpoint: POST /nano-banana/images
• Método de Autenticação: Inclua authorization: Bearer {token} no cabeçalho HTTP
• Cabeçalhos da Solicitação:
  • accept: application/json
  • content-type: application/json
• Ação (action):
  • generate: gera uma imagem com base em um texto de prompt
  • edit: edita uma imagem existente
• Modelo (model) (opcional):
  • nano-banana (padrão): baseado na Gemini 2.5 Flash Image, rápido e de baixo custo
  • nano-banana-2-lite: baseado na Gemini 3.1 Flash Lite Image, suporta apenas 1K, velocidade de geração rápida
  • nano-banana-2: baseado na Gemini 3.1 Flash Image Preview, qualidade Pro + velocidade Flash
  • nano-banana-pro: baseado na Gemini 3 Pro Image Preview, qualidade máxima
  • nano-banana:official, nano-banana-2-lite:official, nano-banana-2:official, nano-banana-pro:official: versões oficiais dos modelos correspondentes, com melhor qualidade de imagem e estabilidade, com cobrança diferente
• Callback Assíncrono: opcional, para receber notificações de conclusão de tarefas e resultados através de callback_url
• Número de Imagens: opcional, especifique de 1 a 4 imagens através de count, padrão é 1; cada imagem é gerada por chamadas independentes; falhas técnicas comuns ou recusas de segurança do provedor afetam apenas a chamada correspondente, as demais imagens bem-sucedidas são retornadas normalmente e a cobrança é feita com base no número real de imagens bem-sucedidas

​

Começo Rápido: Gerar Imagem (action=generate)

​

Exemplo de Solicitação (cURL)

curl -X POST 'https://api.acedata.cloud/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "generate",
    "model": "nano-banana-pro",
    "prompt": "Um retrato fotorealista em close de um ceramista japonês idoso com rugas profundas, marcadas pelo sol, e um sorriso caloroso e conhecedor. Ele está inspecionando cuidadosamente uma tigela de chá recém-esmalte. O cenário é sua oficina rústica, banhada pelo sol. A cena é iluminada por uma luz suave do final da tarde que entra pela janela, destacando a fina textura do barro. Capturado com uma lente de retrato de 85mm, resultando em um fundo suave e desfocado (bokeh). O clima geral é sereno e magistral. Orientação vertical do retrato.",
    "count": 1
  }'

​

Exemplo de Solicitação (Python)

import requests

url = "https://api.acedata.cloud/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "generate",
    "model": "nano-banana-pro",
    "prompt": (
        "Um retrato fotorealista em close de um ceramista japonês idoso "
        "com rugas profundas, marcadas pelo sol, e um sorriso caloroso e conhecedor. Ele está inspecionando "
        "cuidadosamente uma tigela de chá recém-esmalte. O cenário é sua oficina rústica, banhada pelo sol. "
        "A cena é iluminada por uma luz suave do final da tarde que entra pela janela, destacando a fina textura "
        "do barro. Capturado com uma lente de retrato de 85mm, resultando em um fundo suave e desfocado (bokeh). "
        "O clima geral é sereno e magistral. Orientação vertical do retrato."
    ),
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

​

Exemplo de Retorno de Sucesso

{
  "success": true,
  "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "data": [
    {
      "prompt": "Um retrato fotorealista em close de um ceramista japonês idoso com rugas profundas, marcadas pelo sol, e um sorriso caloroso e conhecedor. Ele está inspecionando cuidadosamente uma tigela de chá recém-esmalte. O cenário é sua oficina rústica, banhada pelo sol. A cena é iluminada por uma luz suave do final da tarde que entra pela janela, destacando a fina textura do barro. Capturado com uma lente de retrato de 85mm, resultando em um fundo suave e desfocado (bokeh). O clima geral é sereno e magistral. Orientação vertical do retrato.",
      "image_url": "https://platform2.cdn.acedata.cloud/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336.png"
    }
  ]
}

​

Descrição dos Campos

• success: indica se a solicitação foi bem-sucedida.
• task_id: ID da tarefa.
• trace_id: ID de rastreamento, útil para solucionar problemas.
• count: número de imagens solicitadas para geração ou edição, suporta de 1 a 4, padrão é 1. data contém apenas as imagens geradas com sucesso e a cobrança é feita com base no número real de imagens retornadas. Cada chamada de geração deve seguir a política de segurança nativa do provedor; se uma chamada for recusada, não afetará outras chamadas bem-sucedidas, e se todas as chamadas forem recusadas, retornará 403.
• data[]: lista de resultados.
  • prompt: o texto de prompt usado para a geração (eco).
  • image_url: URL direta da imagem gerada.

Nota: /nano-banana/images requer apenas action e prompt para gerar uma imagem

​

Editar Imagem (action=edit)

​

Exemplo de Solicitação (cURL)

curl -X POST 'https://api.acedata.cloud/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "edit",
    "prompt": "deixe este homem usar esta camiseta",
    "image_urls": [
      "https://cdn.acedata.cloud/v8073y.png",
      "https://cdn.acedata.cloud/44xlah.png"
    ],
    "count": 1
  }'

​

Exemplo de Requisição (Python)

import requests

url = "https://api.acedata.cloud/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "edit",
    "prompt": "deixe este homem usar esta camiseta",
    "image_urls": [
        "https://cdn.acedata.cloud/v8073y.png",
        "https://cdn.acedata.cloud/44xlah.png"
    ],
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

​

Exemplo de Retorno de Sucesso

{
  "success": true,
  "task_id": "93f11baf-347b-4bb4-9520-8653cb46d6a3",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "data": [
    {
      "prompt": "deixe este homem usar esta camiseta",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/8e9e0253-26f4-45b9-b3f8-ac1aed1c284b.png"
    }
  ]
}

​

Descrição dos Campos

• image_urls[]: lista de URLs das imagens a serem editadas (devem ser acessíveis publicamente). É possível enviar várias, o serviço combinará esses materiais com o prompt para completar a edição.
• Os demais campos são os mesmos do retorno de “gerar imagem”.

​

Callback Assíncrono (opcional, recomendado)

1. Adicione callback_url ao corpo da requisição, por exemplo, o endereço do seu Webhook no servidor (deve ser acessível publicamente, suportando POST JSON).
2. A API retornará imediatamente uma resposta contendo o task_id (ou um resultado básico).
3. Quando a tarefa for concluída, a plataforma enviará o JSON completo para o callback_url via POST. Você pode associar a requisição ao resultado através do task_id.

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "um gato siames branco",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png"
    }
  ]
}

​

Tratamento de Erros

• 400 token_mismatched: requisição inválida ou erro de parâmetro.
• 400 api_not_implemented: interface não implementada (entre em contato com o suporte).
• 401 invalid_token: falha de autenticação ou falta de Token.
• 403 forbidden: a política de segurança nativa do provedor rejeitou a requisição ou o resultado gerado. Essa chamada não retornará imagens e não será cobrada; requisições com várias imagens ainda podem retornar e cobrar outras chamadas bem-sucedidas.
• 429 too_many_requests: limite de frequência de requisições excedido.
• 500 api_error: exceção no servidor.

​

Exemplo de Resposta de Erro

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "Erro interno do servidor."
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​

Correspondência de Parâmetros e Considerações

• Obrigatório: action, prompt
• Edição exclusiva: image_urls (array, pelo menos 1 item)
• Opcional: model (padrão nano-banana, opções nano-banana-2-lite, nano-banana-2, nano-banana-pro, ou versões oficiais correspondentes :official), aspect_ratio (proporção, como 1:1, 16:9), resolution (resolução, como 1K, 2K, 4K; nano-banana-2-lite suporta apenas 1K), callback_url (para callback assíncrono)
• Headers: deve-se fornecer authorization: Bearer {token}; accept é recomendado como application/json
• Acessibilidade das imagens: image_urls devem ser links diretos acessíveis publicamente (HTTP/HTTPS), recomenda-se usar HTTPS
• Idempotência e rastreamento: mantenha task_id e trace_id para facilitar a resolução de problemas e a associação de resultados