> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Nano Banana Images API Integração e Uso

> Nano Banana Image Generation 集成指南 - XHuoAPI

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](https://api.xhuoapi.ai/documents/23985a11-d713-41d1-ad84-24b021805b3d) 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)

```bash theme={null}
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)

```python theme={null}
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

```json theme={null}
{
  "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)

```bash theme={null}
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)

```python theme={null}
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

```json theme={null}
{
  "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`:

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):

```json theme={null}
{
  "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

```json theme={null}
{
  "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

***