Saltar para o conteúdo principal
Este documento apresenta a integração e uso da API Nano Banana Images. Esta interface suporta duas funcionalidades: geração de imagens (generate) e edição de imagens (edit).

​
Processo de Solicitação

Antes de usar, acesse a API Nano Banana Images na plataforma Ace Data Cloud e clique em Adquirir para solicitar a ativação. A primeira solicitação geralmente terá uma cota gratuita disponível. Após a ativação, você poderá obter o Bearer Token necessário para chamar a API na plataforma.

​
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: 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
  • Callback Assíncrono: opcional, receba notificações de conclusão de tarefa e resultados através de callback_url

​
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",
    "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",
    "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": "056f0589-a3dd-4ec2-8440-ad61f5038dfa",
  "trace_id": "c48de83f-0077-426e-b02b-ff1d58179064",
  "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://platform.cdn.acedata.cloud/nanobanana/69790adb-c85d-4362-ad9e-0c9ba4352cf4.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.
  • data[]: lista de resultados.
    • prompt: texto 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)

Quando você deseja editar uma imagem existente, defina action como edit e forneça uma lista de URLs de imagens a serem editadas (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 públicos acessíveis 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 vestir 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 vestir 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 imagens, e o serviço combinará esses materiais com o prompt para concluir a edição.
  • Os demais campos são os mesmos do retorno de “gerar imagem”.

​
Callback Assíncrono (opcional, recomendado)

Gerar ou editar pode levar algum tempo. Para evitar que conexões longas ocupem recursos, recomenda-se usar Webhook Callback através de callback_url:
  1. Adicione callback_url ao corpo da solicitação, por exemplo, o endereço Webhook do seu servidor (deve ser acessível publicamente e suportar POST JSON).
  2. A API retornará imediatamente uma resposta contendo task_id (ou resultados básicos).
  3. 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 de task_id.
Exemplo de carga de callback (estrutura de campos consistente com a resposta de sucesso síncrona): 
{
  "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

Quando a chamada falha, um formato de erro padrão e um ID de rastreamento serão retornados. 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, opções nano-banana-2 ou nano-banana-pro), aspect_ratio (proporção, como 1:1, 16:9), resolution (resolução, como 1K, 2K, 4K), callback_url (para callback assíncrono)
  • Headers: deve fornecer authorization: Bearer {token}; accept recomendado como application/json
  • Acessibilidade da imagem: image_urls deve ser um link direto acessível 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