Nano Banana Images API Integração e Uso

Este documento apresenta a integração e uso da API Nano Banana Images. Esta interface suporta duas funcionalidades: geração de imagem (generate) e edição de imagem (edit).

Processo de Solicitação

Para usar a API Nano Banana Images, primeiro acesse o Painel de Controle da Ace Data Cloud para obter seu Token de API, que deve ser guardado para uso futuro.

Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e logar. Após a conclusão, você será redirecionado de volta para a página atual. Um Token de API é suficiente para acessar todos os serviços da plataforma, não sendo necessário solicitar um para cada serviço individualmente. A primeira solicitação oferece um crédito gratuito, permitindo uma experiência sem custo; quando o crédito estiver baixo, você pode recarregar o saldo geral no painel de controle.

📘 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, 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, receba notificações de conclusão de tarefa 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; em caso de falha parcial, apenas as imagens geradas com sucesso serão retornadas e cobradas

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

Parâmetros Mínimos Necessários: action, prompt Quando você deseja gerar uma imagem diretamente com base em um prompt, defina action como generate e forneça um prompt claro.

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. Em caso de falha parcial, data conterá apenas as imagens geradas com sucesso.
data[]: lista de resultados.
- prompt: texto de prompt utilizado 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`)

Quando você deseja editar uma imagem existente, defina action como edit e forneça uma lista de URLs de imagens a serem editadas através de image_urls (1 ou mais), juntamente com um prompt que descreva o objetivo da edição. Por exemplo, se fornecermos uma foto de uma pessoa e uma foto de uma roupa, podemos fazer com que a pessoa vista essa roupa, passando as URLs das imagens e definindo a ação como edit. As URLs podem ser links acessíveis publicamente via protocolo https ou http, ou podem ser imagens codificadas em Base64, como data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+gAAAVGCAMAAAA6u2FyAAADAFBMVEXq6uwdHCEeHyMdHS....

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 vestir esta camiseta",
    "image_urls": [
      "https://cdn.acedata.cloud/v8073y.png",
      "https://cdn.acedata.cloud/44xlah.png"
    ],
    "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": "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)

A geração ou edição pode levar algum tempo. Para evitar que conexões longas ocupem recursos, recomenda-se usar callback_url para Webhook Callback:

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

Exemplo de Carga de Callback (estrutura de campos igual ao retorno de sucesso síncrono):

{
  "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

Em caso de falha na chamada, será retornado um formato de erro padrão com o ID de rastreamento. Erros comuns incluem:

400 token_mismatched: solicitaçã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.
429 too_many_requests: limite de frequência de solicitaçõ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, pode ser nano-banana-2-lite, nano-banana-2, nano-banana-pro, ou a versão oficial correspondente :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 fornecer authorization: Bearer {token}; accept é recomendado como application/json
Acessibilidade da Imagem: 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 associação de resultados

Primeiros passos

Chat AI

Imagem AI

Vídeo AI

Áudio AI

Web e Dados

CAPTCHA

Identidade

Proxy

Avançado

Nano Banana Images API Integração e Uso

Processo de Solicitação

Visão Geral da Interface

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

Exemplo de Solicitação (cURL)

Exemplo de Solicitação (Python)

Exemplo de Retorno de Sucesso

Descrição dos Campos

Editar Imagem (`action=edit`)

Exemplo de Solicitação (cURL)

Exemplo de Solicitação (Python)

Exemplo de Retorno de Sucesso

Descrição dos Campos

Callback Assíncrono (opcional, recomendado)

Tratamento de Erros

Exemplo de Resposta de Erro

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

​Processo de Solicitação

​Visão Geral da Interface

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

​Exemplo de Solicitação (cURL)

​Exemplo de Solicitação (Python)

​Exemplo de Retorno de Sucesso

​Descrição dos Campos

​Editar Imagem (action=edit)

​Exemplo de Solicitação (cURL)

​Exemplo de Solicitação (Python)

​Exemplo de Retorno de Sucesso

​Descrição dos Campos

​Callback Assíncrono (opcional, recomendado)

​Tratamento de Erros

​Exemplo de Resposta de Erro

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

Processo de Solicitação

Visão Geral da Interface

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

Exemplo de Solicitação (cURL)

Exemplo de Solicitação (Python)

Exemplo de Retorno de Sucesso

Descrição dos Campos

Editar Imagem (`action=edit`)

Exemplo de Solicitação (cURL)

Exemplo de Solicitação (Python)

Exemplo de Retorno de Sucesso

Descrição dos Campos

Callback Assíncrono (opcional, recomendado)

Tratamento de Erros

Exemplo de Resposta de Erro

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