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

# Integración y uso de la API de Tareas de Nano Banana

> Nano Banana Image Generation API guide - Ace Data Cloud

La API de Tareas de Nano Banana tiene como función principal consultar el estado de ejecución de una tarea mediante el ID de tarea generado por la API de Imágenes de Nano Banana.

Este documento detallará las instrucciones de integración de la API de Tareas de Nano Banana, ayudándole a integrar y aprovechar al máximo las potentes funcionalidades de esta API. A través de la API de Tareas de Nano Banana, puede consultar fácilmente el estado de ejecución de las tareas de la API de Imágenes de Nano Banana.

## Ejemplo de solicitud

La API de Tareas de Nano Banana se puede utilizar para consultar los resultados de la API de Imágenes de Nano Banana. Para saber cómo utilizar la API de Imágenes de Nano Banana, consulte el documento [API de Imágenes de Nano Banana](https://platform.acedata.cloud/documents/veo-videos).

Tomemos como ejemplo un ID de tarea devuelto por el servicio de la API de Imágenes de Nano Banana, y demostraremos cómo utilizar esta API. Supongamos que tenemos un ID de tarea: 4d320ead-4af4-4a55-8f3e-f2afebdf4fd0, a continuación se muestra cómo hacerlo pasando un ID de tarea.

### Ejemplo de tarea

<p>
  <img src="https://cdn.acedata.cloud/nuiuth.png" width="500" className="m-auto" />
</p>

### Configuración de encabezados de solicitud y cuerpo de solicitud

**Encabezados de solicitud** incluyen:

* `accept`: especifica que se aceptan respuestas en formato JSON, aquí se debe llenar como `application/json`.
* `authorization`: clave para llamar a la API, que puede seleccionarse directamente después de solicitarla.

**Cuerpo de solicitud** incluye:

* `id`: ID de la tarea subida.
* `action`: forma de operar sobre la tarea.

Configurado como se muestra en la siguiente imagen:

<p>
  <img src="https://cdn.acedata.cloud/nuiuth.png" width="500" className="m-auto" />
</p>

### Ejemplo de código

Se puede observar que en el lado derecho de la página se han generado automáticamente códigos en varios lenguajes, como se muestra en la imagen:

<p>
  <img src="https://cdn.acedata.cloud/r1u4vl.png" width="500" className="m-auto" />
</p>

Algunos ejemplos de código son los siguientes:

#### CURL

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

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

### Ejemplo de respuesta

Después de una solicitud exitosa, la API devolverá la información detallada de la tarea aquí. Por ejemplo:

```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,
  "started_at": 1757183036.847,
  "finished_at": 1757183048.147,
  "elapsed": 11.3,
  "credential_id": "097b2987-62f4-4ac0-b0cc-aed41e372a07",
  "request": {
    "action": "generate",
    "prompt": "un gato siamés blanco"
  },
  "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": "un gato siamés blanco",
        "image_url": "https://platform.cdn.acedata.cloud/nanobanana/7e7bd000-698a-4e14-bb2d-3db61237e4bb.png"
      }
    ]
  }
}
```

El resultado devuelto tiene varios campos, el campo request es el cuerpo de la solicitud al iniciar la tarea, mientras que el campo response es el cuerpo de respuesta devuelto después de completar la tarea. La descripción de los campos es la siguiente.

* `id`, ID que genera esta tarea, utilizado para identificar de manera única esta tarea generada.
* `request`, información de solicitud en la tarea consultada.
* `response`, información de respuesta en la tarea consultada.
* `created_at`, tiempo de creación de la tarea, marca de tiempo Unix (segundos, flotante).
* `started_at`, tiempo de inicio de ejecución de la tarea, marca de tiempo Unix (segundos, flotante).
* `finished_at`, tiempo de finalización de la tarea, marca de tiempo Unix (segundos, flotante). Este campo no se devuelve si la tarea no se ha completado.
* `elapsed`, tiempo de ejecución de la tarea, en segundos (flotante, con 3 decimales). Este campo no se devuelve si la tarea no se ha completado.

## Operación de consulta por lotes

Esto es para consultar los detalles de varias tareas ID, a diferencia de lo anterior, se debe seleccionar la acción como `retrieve_batch`.

**Cuerpo de solicitud** incluye:

* `ids`: matriz de IDs de tareas subidas.
* `action`: forma de operar sobre la tarea.

Ejemplo a continuación:

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

### Ejemplo de respuesta

Después de una solicitud exitosa, la API devolverá la información detallada de todas las tareas por lotes. Por ejemplo:

```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,
      "started_at": 1757183036.847,
      "finished_at": 1757183048.147,
      "elapsed": 11.3,
      "credential_id": "097b2987-62f4-4ac0-b0cc-aed41e372a07",
      "request": {
        "action": "generate",
        "prompt": "un gato siamés blanco"
      },
      "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": "un gato siamés blanco",
            "image_url": "https://platform.cdn.acedata.cloud/nanobanana/7e7bd000-698a-4e14-bb2d-3db61237e4bb.png"
          }
        ]
      }
    }
  ],
  "count": 1
}
```

返回结果一共有多个字段，其中 items 是包含了批量任务的具体详情信息，每个任务的具体信息与上文的字段一样，字段信息如下。

* `items`，批量任务的所有具体详情信息。它 es un array, cada elemento del array tiene el mismo formato que el resultado de la consulta de una sola tarea.
* `count`，此处批量查询任务的个数。

## 错误处理

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：

* `400 token_mismatched`：Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
* `400 api_not_implemented`：Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
* `401 invalid_token`：No autorizado, token de autorización inválido o faltante.
* `429 too_many_requests`：Demasiadas solicitudes, ha superado el límite de tasa.
* `500 api_error`：Error interno del servidor, algo salió mal en el servidor.

### 错误响应示例

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "la recuperación falló"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## 结论

通过本文档，您已经了解了如何使用 Nano Banana Tasks API 进行查询单个或批量任务的所有具体详情信息。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。