Saltar para o conteúdo principal
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. 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

curl -X POST 'https://api.acedata.cloud/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

import requests

url = "https://api.acedata.cloud/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: 
{
  "_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.acedata.cloud/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: 
curl -X POST 'https://api.acedata.cloud/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: 
{
  "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.acedata.cloud/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

{
  "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.