> ## 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.
# Integração e Uso da API Nano Banana Tasks
> Nano Banana Image Generation 集成指南 - XHuoAPI
A principal função da API Nano Banana Tasks é consultar o status de execução de uma tarefa através do ID da tarefa gerado pela API Nano Banana Images.
Este documento irá detalhar as instruções de integração da API Nano Banana Tasks, ajudando você a integrar facilmente e aproveitar ao máximo o poderoso recurso dessa API. Com a API Nano Banana Tasks, você pode consultar facilmente o status de execução das tarefas da API Nano Banana Images.
## Exemplo de Requisição
A API Nano Banana Tasks pode ser usada para consultar os resultados da API Nano Banana Images. Para saber como usar a API Nano Banana Images, consulte o documento [API Nano Banana Images](https://api.xhuoapi.ai/documents/63e01dc3-eb21-499e-8049-3025c460058f).
Usaremos um exemplo de ID de tarefa retornado pelo serviço da API Nano Banana Images. Suponha que temos um ID de tarefa: 4d320ead-4af4-4a55-8f3e-f2afebdf4fd0, a seguir, demonstraremos como passar um ID de tarefa.
### Exemplo de Tarefa
### Configurando Cabeçalhos e Corpo da Requisição
**Cabeçalhos da Requisição** incluem:
* `accept`: especifica que a resposta deve ser no formato JSON, preenchido como `application/json`.
* `authorization`: a chave para chamar a API, que pode ser selecionada diretamente após a solicitação.
**Corpo da Requisição** inclui:
* `id`: o ID da tarefa enviada.
* `action`: a forma de operação na tarefa.
Configuração conforme mostrado na imagem abaixo:
### Exemplo de Código
Pode-se notar que, no lado direito da página, já foram gerados automaticamente códigos em várias linguagens, conforme mostrado na imagem:
Alguns exemplos de código são os seguintes:
#### CURL
```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/nano-banana/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0",
"action": "retrieve"
}'
```
#### Python
```python theme={null}
import requests
url = "https://api.xhuoapi.ai/v1/nano-banana/tasks"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0",
"action": "retrieve"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
### Exemplo de Resposta
Após uma requisição bem-sucedida, a API retornará as informações detalhadas da tarefa aqui. Por exemplo:
```json theme={null}
{
"_id": "68bc7c3c550a4144a53d0e24",
"id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0",
"api_id": "9d8a117e-31ca-4322-a0fd-1771296ec610",
"application_id": "8afd681a-2a4e-4265-aecb-43970094c019",
"created_at": 1757183036.787,
"credential_id": "097b2987-62f4-4ac0-b0cc-aed41e372a07",
"request": {
"action": "generate",
"prompt": "a white siamese cat"
},
"trace_id": "7ba1f1e8-0ef8-450d-8bb2-b5c3bf1ea319",
"type": "images",
"user_id": "b87f67c1-b04f-4332-99a1-7a5e651331c6",
"response": {
"success": true,
"task_id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0",
"trace_id": "7ba1f1e8-0ef8-450d-8bb2-b5c3bf1ea319",
"data": [
{
"prompt": "a white siamese cat",
"image_url": "https://platform.cdn.xhuoapi.ai/nanobanana/7e7bd000-698a-4e14-bb2d-3db61237e4bb.png"
}
]
}
}
```
O resultado retornado contém vários campos, onde o campo request é o corpo da requisição ao iniciar a tarefa, enquanto o campo response é o corpo da resposta retornada após a conclusão da tarefa. A descrição dos campos é a seguinte.
* `id`: o ID gerado para esta tarefa, usado para identificar exclusivamente esta tarefa gerada.
* `request`: informações da requisição na tarefa consultada.
* `response`: informações da resposta na tarefa consultada.
## Operação de Consulta em Lote
Esta operação é para consultar detalhes de várias IDs de tarefa, diferentemente do anterior, onde a ação deve ser selecionada como `retrieve_batch`.
**Corpo da Requisição** inclui:
* `ids`: um array de IDs de tarefa enviados.
* `action`: a forma de operação na tarefa.
Exemplo abaixo:
```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/nano-banana/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"ids": ["1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed","1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed"],
"action": "retrieve_batch"
}'
```
### Exemplo de Resposta
Após uma requisição bem-sucedida, a API retornará as informações detalhadas de todas as tarefas em lote. Por exemplo:
```json theme={null}
{
"items": [
{
"_id": "68bc7c3c550a4144a53d0e24",
"id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0",
"api_id": "9d8a117e-31ca-4322-a0fd-1771296ec610",
"application_id": "8afd681a-2a4e-4265-aecb-43970094c019",
"created_at": 1757183036.787,
"credential_id": "097b2987-62f4-4ac0-b0cc-aed41e372a07",
"request": {
"action": "generate",
"prompt": "a white siamese cat"
},
"trace_id": "7ba1f1e8-0ef8-450d-8bb2-b5c3bf1ea319",
"type": "images",
"user_id": "b87f67c1-b04f-4332-99a1-7a5e651331c6",
"response": {
"success": true,
"task_id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0",
"trace_id": "7ba1f1e8-0ef8-450d-8bb2-b5c3bf1ea319",
"data": [
{
"prompt": "a white siamese cat",
"image_url": "https://platform.cdn.xhuoapi.ai/nanobanana/7e7bd000-698a-4e14-bb2d-3db61237e4bb.png"
}
]
}
}
],
"count": 1
}
```
O resultado retornado contém vários campos, onde items inclui as informações detalhadas das tarefas em lote, e cada informação de tarefa é igual à estrutura de retorno da consulta de uma única tarefa. As informações dos campos são as seguintes.
* `items`: todas as informações detalhadas das tarefas em lote. É um array, onde cada elemento do array tem o mesmo formato do resultado retornado da consulta de uma única tarefa.
* `count`: o número de tarefas consultadas em lote.
## Tratamento de Erros
Ao chamar a API, se ocorrer um erro, a API retornará o código de erro e a mensagem correspondentes. Por exemplo:
* `400 token_mismatched`: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
* `400 api_not_implemented`: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
* `401 invalid_token`: Não autorizado, token de autorização inválido ou ausente.
* `429 too_many_requests`: Muitas solicitações, você excedeu o limite de taxa.
* `500 api_error`: Erro interno do servidor, algo deu errado no servidor.
### Exemplo de Resposta de Erro
```json theme={null}
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## Conclusão
Através deste documento, você já entendeu como usar a API Nano Banana Tasks para consultar informações detalhadas sobre tarefas individuais ou em lote. Esperamos que este documento possa ajudá-lo a integrar e usar melhor essa API. Se tiver alguma dúvida, sinta-se à vontade para entrar em contato com nossa equipe de suporte técnico.