> ## 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.

# Development Dreamina Tasks

> Dreamina API guide - Ace Data Cloud

## Integración y uso de la API de Dreamina Tasks

La API de Dreamina Tasks se utiliza para consultar los resultados de ejecución de las tareas de video de personas digitales creadas por la [API de Generación de Video de Dreamina](https://platform.acedata.cloud/documents/dreamina-videos-integration). Cuando envías `callback_url` o `async: true` en la interfaz de generación, la API devuelve inmediatamente un `task_id`, que puedes usar para consultar el estado de la tarea y la dirección del video final a través de esta interfaz usando `task_id` o `trace_id`. **Esta interfaz es gratuita.**

## Proceso de solicitud

Para usar la serie de API de Dreamina, primero ve a la [Consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obtener tu API Token, que debes guardar como respaldo.

Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión que te invitará a registrarte e iniciar sesión, y después volverás automáticamente a la página actual.

**Un API Token es suficiente para acceder a todos los servicios de la plataforma, no es necesario solicitar uno por cada servicio.** La primera solicitud te otorgará un crédito gratuito para que lo pruebes; si el crédito es insuficiente, puedes recargar el saldo general en la [consola](https://platform.acedata.cloud/console/coin).

## Parámetros de solicitud

**Encabezados de solicitud**

* `accept`: especifica que se aceptan respuestas en formato JSON, escribe `application/json`.
* `authorization`: clave para llamar a la API, en el formato `Bearer {token}`.
* `content-type`: escribe `application/json`.

**Cuerpo de la solicitud**

| Parámetro | Tipo | Requerido | Descripción |
| - | - | - | - |
| `action` | string | No | Tipo de operación, `retrieve` (por defecto, consulta individual) o `retrieve_batch` (consulta por lotes) |
| `id` | string | No | ID de la tarea a consultar (el `task_id` devuelto al crear el video) |
| `trace_id` | string | No | ID de seguimiento de la tarea a consultar, puede usarse en lugar de `id` |
| `ids` | string\[] | No | Lista de IDs de tareas para consulta por lotes, se usa junto con `retrieve_batch` |

> Al consultar una tarea individual, se debe proporcionar al menos uno de `id` o `trace_id`.

## Consultar una tarea individual

### CURL

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/dreamina/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve",
  "id": "362b4fed-67bd-11f1-ad11-00163e57d510"
}'
```

### Python

```python theme={null}
import requests

url = "https://api.acedata.cloud/dreamina/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "retrieve",
    "id": "362b4fed-67bd-11f1-ad11-00163e57d510"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

### Ejemplo de respuesta

Si la solicitud es exitosa, la API devuelve los detalles de la tarea. `request` es el cuerpo de la solicitud al crear la tarea, `response` es el cuerpo de la respuesta después de que la tarea se completa, donde `data.video_url` es la dirección del video de la persona digital generada:

```json theme={null}
{
  "id": "362b4fed-67bd-11f1-ad11-00163e57d510",
  "started_at": 1769262721.823,
  "finished_at": 1769262769.123,
  "elapsed": 47.3,
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "request": {
    "model": "omnihuman-1.5",
    "image_url": "https://cdn.acedata.cloud/4hfydw.jpg",
    "audio_url": "https://cdn.acedata.cloud/6f7d62b18b.wav"
  },
  "response": {
    "success": true,
    "data": {
      "task_id": "362b4fed67bd11f1ad1100163e57d510",
      "status": "done",
      "video_url": "https://cdn.acedata.cloud/634d760216.mp4",
      "image_url": "https://cdn.acedata.cloud/4hfydw.jpg",
      "audio_url": "https://cdn.acedata.cloud/6f7d62b18b.wav"
    }
  }
}
```

Descripción de los campos:

* `id`: ID único de la tarea de generación de video.
* `trace_id`: ID de seguimiento de esta solicitud, utilizado para la resolución de problemas.
* `request`: contenido de la solicitud enviado al crear la tarea.
* `response`: contenido de la respuesta devuelta después de completar la tarea. Cuando `response.data.status` es `done`, `response.data.video_url` es la dirección final del video.
* `created_at`: hora de creación de la tarea, marca de tiempo Unix (segundos, flotante).
* `started_at`: hora de inicio de ejecución de la tarea, marca de tiempo Unix (segundos, flotante).
* `finished_at`: hora 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.

> Si la tarea aún no se ha completado, el `status` puede no ser `done`; si la tarea no existe o aún no se ha generado un resultado, la interfaz devolverá un objeto vacío `{}`, por favor intenta de nuevo más tarde.

## Consulta de tareas por lotes

Establece `action` como `retrieve_batch` y pasa un array `ids`:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/dreamina/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve_batch",
  "ids": [
    "362b4fed-67bd-11f1-ad11-00163e57d510",
    "0c0b4d3a-2f1e-4a6b-9c2d-2b3c4d5e6f70"
  ]
}'
```

En el resultado devuelto, `items` es un array de detalles de tareas por lotes (cada elemento tiene el mismo formato que el resultado de una consulta individual), `count` es la cantidad de tareas devueltas en esta ocasión.

## Manejo de errores

Cuando se encuentra un error al llamar a la API, se devolverá el código de error correspondiente y la información:

* `400 bad_request`: error en la solicitud, puede faltar `id` / `trace_id` u otros parámetros necesarios.
* `401 invalid_token`: no autorizado, el token de autorización es inválido o está ausente.
* `429 too_many_requests`: demasiadas solicitudes, se ha superado el límite de velocidad.
* `500 api_error`: error interno del servidor.

### Ejemplo de respuesta de error

```json theme={null}
{
  "error": {
    "code": "bad_request",
    "message": "id or trace_id is required to retrieve a task"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Conclusión

A través de este documento, has aprendido cómo usar la API de Dreamina Tasks para consultar los resultados de tareas de video de personas digitales, ya sea de forma individual o por lotes. Combinando con el `callback_url` / modo asíncrono `async` de la interfaz de generación, puedes lograr una consulta estable. Si tienes alguna pregunta, no dudes en contactar a nuestro equipo de soporte técnico.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.