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 imagens (generate) e edição de imagens (edit).

Processo de Solicitação

Antes de usar, acesse a API Nano Banana Images na plataforma XHuoAPI 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.xhuoapi.ai/v1
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.xhuoapi.ai/v1/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.xhuoapi.ai/v1/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.xhuoapi.ai/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.xhuoapi.ai/v1/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.xhuoapi.ai/v8073y.png",
      "https://cdn.xhuoapi.ai/44xlah.png"
    ],
    "count": 1
  }'

Exemplo de Solicitação (Python)

import requests

url = "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/v8073y.png",
        "https://cdn.xhuoapi.ai/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.xhuoapi.ai/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:

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).
A API retornará imediatamente uma resposta contendo 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 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.xhuoapi.ai/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

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