Instruções de integração da API Nano Banana Images

​

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：carregar authorization: Bearer {token} no HTTP Header
• Cabeçalhos da solicitação：
  • accept: application/json
  • content-type: application/json
• Ação (action)：
  • generate：gerar imagens com base em prompts de texto
  • edit：editar com base em imagens fornecidas
• Modelo (model)（opcional）：
  • nano-banana（padrão）：baseado no Gemini 2.5 Flash Image, rápido e de baixo custo
  • nano-banana-2-lite：baseado no Gemini 3.1 Flash Lite Image, suporta apenas 1K e possui velocidade de geração rápida
  • nano-banana-2：baseado no Gemini 3.1 Flash Image Preview, qualidade de nível Pro + velocidade Flash
  • nano-banana-2.1：modelo de imagem eficiente de nova geração, suporta geração e edição de imagens em 1K, 2K e 4K
  • nano-banana-pro：baseado no 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 de canal oficial dos modelos correspondentes, com melhor qualidade de imagem e estabilidade, e cobrança diferente
• Callback assíncrono：opcional, receba notificações de conclusão de tarefas e resultados por meio de callback_url
• Quantidade de imagens：opcional, especifique de 1 a 4 imagens por meio de count, sendo 1 o padrão; cada imagem é concluída por uma chamada de geração independente; 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 de acordo com a quantidade real de imagens bem-sucedidas

​

Início rápido: gerar imagens（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": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.",
    "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": (
        "A photorealistic close-up portrait of an elderly Japanese ceramicist "
        "with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully "
        "inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched "
        "workshop. The scene is illuminated by soft, golden hour light streaming through "
        "a window, highlighting the fine texture of the clay. Captured with an 85mm "
        "portrait lens, resulting in a soft, blurred background (bokeh). The overall mood "
        "is serene and masterful. Vertical portrait orientation."
    ),
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

​

Exemplo de retorno bem-sucedido

{
  "success": true,
  "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "data": [
    {
      "prompt": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.",
      "image_url": "https://cdn.acedata.cloud/assets/examples/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336-34b3dc2195e8.png"
    }
  ]
}

​

Descrição dos campos

• success：se esta solicitação foi bem-sucedida.
• task_id：ID da tarefa.
• trace_id：ID de rastreamento da cadeia, facilitando a investigação de problemas.
• count：quantidade de imagens solicitadas para geração ou edição, suporta de 1 a 4, com padrão de 1. data contém apenas as imagens geradas com sucesso, e a cobrança é feita de acordo com a quantidade efetivamente retornada. Cada chamada de geração usa obrigatoriamente as políticas de segurança nativas do provedor; a recusa de uma chamada não afeta outras chamadas bem-sucedidas, e retorna 403 quando todas as chamadas forem recusadas.
• data[]：lista de resultados.
  • prompt：prompt usado para a geração (ecoado).
  • image_url：URL direta da imagem gerada.

Observação: /nano-banana/images requer apenas action e prompt para gerar imagens

​

Editar imagens（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": "let this man wear on this T-shirt",
    "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": "let this man wear on this T-shirt",
    "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 bem-sucedido

{
  "success": true,
  "task_id": "93f11baf-347b-4bb4-9520-8653cb46d6a3",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "data": [
    {
      "prompt": "let this man wear on this T-shirt",
      "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 (deve ser acessível publicamente). É possível enviar várias imagens; 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».

​

Retorno de chamada assíncrono (opcional, recomendado)

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 contendo 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 por meio de task_id.

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

​

Tratamento de erros

• 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 na autenticação ou Token ausente.
• 403 forbidden: A política de segurança nativa do provedor recusou a solicitação ou o resultado gerado. Esta chamada não retornará imagem nem será cobrada; solicitações com várias imagens ainda podem retornar e cobrar por outras chamadas bem-sucedidas.
• 429 too_many_requests: Frequência de solicitações excedeu o limite.
• 500 api_error: Exceção no servidor.

​

Exemplo de resposta de erro

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "Internal server error."
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​

Comparação de parâmetros e observações

• Obrigatórios: action, prompt
• Exclusivo para edição: image_urls (array, pelo menos 1 item)
• Opcionais: model (o padrão é nano-banana, com opções nano-banana-2-lite, nano-banana-2, nano-banana-2.1, nano-banana-pro; exceto nano-banana-2.1, também há versões correspondentes do canal oficial :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 (usado para retorno de chamada assíncrono)
• Cabeçalhos: é obrigatório fornecer authorization: Bearer {token}; recomenda-se definir accept como application/json
• Acessibilidade das imagens: image_urls deve conter links diretos acessíveis publicamente (HTTP/HTTPS); recomenda-se usar HTTPS
• Idempotência e rastreamento: mantenha task_id e trace_id para facilitar a solução de problemas e a associação de resultados