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

# Guía de integración de la API de consulta de tareas Maestro

> Maestro AI Video Studio API guide - Ace Data Cloud

La función principal de la API de consulta de tareas Maestro es consultar el estado de ejecución y el resultado final de esa tarea mediante el ID de tarea devuelto por la [API de generación de videos Maestro](/es/guides/maestro/maestro_videos) (`POST /maestro/videos`).

Este documento presentará en detalle la guía de integración de la API de consulta de tareas Maestro. Dado que la generación de videos es una tarea asíncrona, después de enviarla es necesario usar esta API para sondear el progreso y el video final, **el sondeo es gratuito y no consume créditos.**

`POST https://api.acedata.cloud/maestro/tasks`

## Proceso de solicitud

Para utilizar la API de consulta de tareas Maestro, primero obtenga su API Token en la [Consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) y guárdelo como respaldo.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

Si aún no ha iniciado sesión o no se ha registrado, será redirigido automáticamente a la página de inicio de sesión para invitarle a registrarse e iniciar sesión; al completarlo, volverá automáticamente a la página actual.

**Un API Token puede llamar a todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio.** La primera solicitud incluirá cuota gratuita para una experiencia sin costo; cuando la cuota sea insuficiente, puede recargar saldo general en la [Consola](https://platform.acedata.cloud/console/coin).

> 📘 Documentación completa: [API de consulta de tareas Maestro →](https://platform.acedata.cloud/documents/maestro-tasks)

## Consultar una sola tarea

Sobre cómo crear una tarea de video, consulte el documento [API de generación de videos Maestro](/es/guides/maestro/maestro_videos). Tomamos como ejemplo uno de los IDs de tarea que devuelve: `f57e99c4f60f4373a15517742ce2357d`, para demostrar cómo consultar su estado y resultado.

### Configurar los encabezados y el cuerpo de la solicitud

Los **Request Headers** incluyen:

* `accept`: especifica que se reciben resultados de respuesta en formato JSON; aquí se completa como `application/json`.
* `authorization`: la clave para llamar a la API, que puede seleccionarse directamente en el menú desplegable después de solicitarla.
* `content-type`: el formato del cuerpo de la solicitud; aquí se completa como `application/json`.

El **Request Body** incluye:

| Campo | Tipo | Obligatorio al consultar una sola tarea | Descripción |
| - | - | - | - |
| `id` | string | Obligatorio al consultar una sola tarea | El `task_id` devuelto por `POST /maestro/videos` |
| `action` | string | No | `retrieve` (predeterminado, consulta una sola tarea); al consultar la lista de historial se fija como `retrieve_batch` |

### Ejemplo de código

El código CURL correspondiente es el siguiente:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "action": "retrieve"
}'
```

El código Python correspondiente es el siguiente:

```python theme={null}
import requests

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

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

payload = {
    "id": "f57e99c4f60f4373a15517742ce2357d",
    "action": "retrieve"
}

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

### Ejemplo de respuesta

Después de que la solicitud sea exitosa, la API devolverá el estado y el resultado de esa tarea de video. El ejemplo de respuesta cuando la tarea está completada es el siguiente (cada idioma corresponde a un `variant`):

```json theme={null}
{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "started_at": 1769262721.823,
  "finished_at": 1769264698.3,
  "elapsed": 1976.477,
  "status": "succeeded",
  "progress": {
    "percent": 100,
    "stage": "producing",
    "message": "rendering scene 2"
  },
  "request": {
    "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
    "langs": [
      "zh-cn",
      "en"
    ],
    "aspect": "9:16",
    "duration": 20
  },
  "response": {
    "success": true,
    "data": {
      "variants": [
        {
          "lang": "zh-cn",
          "aspect": "9:16",
          "kind": "video",
          "title": "什么是向量数据库",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-001"
        },
        {
          "lang": "en",
          "aspect": "9:16",
          "kind": "video",
          "title": "What is a vector database",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-002"
        }
      ],
      "project": {
        "tarball_url": null,
        "outputs": [
          "https://…/zh.mp4",
          "https://…/en.mp4"
        ]
      },
      "percent": 100,
      "stage": "producing",
      "progress": [
        {
          "stage": "producing",
          "message": "rendering scene 2",
          "pct": 60,
          "t": 1750000000
        }
      ]
    }
  }
}
```

La introducción de los campos del resultado devuelto es la siguiente:

* `id`: el ID de esta tarea de video, utilizado para identificar de forma única esta tarea de generación de video.
* `status`: estado de la tarea, con valores `pending → planning → producing → succeeded` (o `failed`). Para determinar si la tarea está completada, prevalece este `status` de nivel superior.
* `elapsed`: tiempo transcurrido de la tarea (segundos).
* `progress`: objeto de progreso de nivel superior; `percent` (0–100) se establecerá como mínimo en 100 después de que la tarea tenga éxito; `stage` y `message` reflejan el evento de progreso más reciente del director de IA (por lo tanto, después del éxito, `stage` puede seguir siendo la última etapa de ejecución, como `producing`), y puede utilizarse directamente para mostrar una barra de progreso.
* `request`: el cuerpo de la solicitud al iniciar la tarea.
* `response`: la información de respuesta de la tarea.
  * `success`: si la tarea tuvo éxito.
  * `data.variants`: cada idioma corresponde a un objeto de video final, que incluye `lang`, `aspect`, `title`, `output_url` (dirección de descarga del video final), etc.
  * `data.project`: el producto de todo el proyecto, que incluye `tarball_url` (paquete del proyecto) y `outputs` (todos los enlaces de los videos finales).
  * `data.progress`: un arreglo de eventos de progreso añadidos por etapa (registro append-only), que puede utilizarse para mostrar el progreso detallado en tiempo real.
* `created_at`: hora de creación de la tarea, marca de tiempo Unix (segundos).
* `started_at`: hora en que la tarea comenzó a ejecutarse, marca de tiempo Unix (segundos). Es null cuando la tarea aún no ha comenzado.
* `finished_at`: hora de finalización de la tarea, marca de tiempo Unix (segundos). Es null cuando la tarea no está completada.

## Consultar la lista de historial

Al pasar `action: retrieve_batch`, puede obtener las tareas recientes del ejecutor que inició sesión actualmente (en orden descendente por hora de creación), lo que puede utilizarse para la página de lista «Mis videos». La lista de historial está aislada por identidad de inicio de sesión.

El **Request Body** incluye:

| Campo | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `action` | string | Sí | Fijo como `retrieve_batch` |
| `limit` | int | No | Número de resultados devueltos, 20 por defecto; el rango válido es 1–100 |
| `created_at_max` | int | No | Solo devuelve tareas estrictamente anteriores a esta marca de tiempo Unix (sin incluir el valor límite, para paginación) |
| `created_at_min` | int | No | Solo devuelve tareas estrictamente posteriores a esta marca de tiempo Unix (sin incluir el valor límite) |

### Ejemplo de código

El código CURL correspondiente es el siguiente:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve_batch",
  "limit": 20
}'
```

### Ejemplo de respuesta

Después de que la solicitud se realice correctamente, la API devolverá la lista de tareas históricas del usuario actual:

```json theme={null}
{
  "count": 2,
  "items": [
    {
      "id": "f57e99c4f60f4373a15517742ce2357d",
      "started_at": 1769262721.823,
      "finished_at": 1769264698.3,
      "elapsed": 1976.477,
      "status": "succeeded",
      "progress": {
        "percent": 100,
        "stage": "producing",
        "message": "rendering scene 2"
      },
      "request": {
        "prompt": "…",
        "langs": [
          "zh-cn",
          "en"
        ],
        "aspect": "9:16",
        "duration": 20
      },
      "response": {
        "success": true,
        "data": {
          "variants": [
            {
              "lang": "zh-cn",
              "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-003"
            }
          ]
        }
      }
    }
  ]
}
```

La introducción de los campos del resultado devuelto es la siguiente:

* `count`: El número total de tareas visibles para el ejecutor actualmente conectado, no afectado por las condiciones de tiempo ni por `limit`.
* `items`: El array de tareas filtrado por las condiciones de tiempo y `limit`, ordenado en orden descendente por hora de creación; el formato de cada elemento es consistente con el resultado devuelto de «consultar una sola tarea».

## Recomendaciones de sondeo

Dado que la producción de vídeo tarda bastante tiempo, `status` pasará por `pending → planning → producing → succeeded` (o `failed`). Se recomienda realizar un sondeo cada 5–10 segundos, hasta que `status` cambie a `succeeded` o `failed`. Puede utilizar `progress.percent` de nivel superior para mostrar una barra de progreso en tiempo real. **El sondeo de esta interfaz es gratuito y no consume créditos.**

## Manejo de errores

Al llamar a la API, si se produce un error, la API devolverá el código y la información de error correspondientes. Por ejemplo:

* `401 invalid_token`: No autorizado, token de autorización no válido o ausente.
* `404 not_found`: Tarea no encontrada, el task\_id proporcionado no existe.
* `429 too_many_requests`: Demasiadas solicitudes, ha excedido el límite de frecuencia.
* `500 api_error`: Error interno del servidor, algo salió mal en el servidor.

### Ejemplo de respuesta de error

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Conclusión

A través de este documento, ya ha aprendido a utilizar la API de consulta de tareas de Maestro para consultar el estado y los resultados de una sola tarea, así como para obtener la lista de tareas históricas del usuario actual. Esperamos que este documento pueda ayudarle a integrar y utilizar mejor esta API. Si tiene alguna pregunta, no dude en ponerse en contacto con nuestro equipo de soporte técnico.

## Interfaces relacionadas

* [Instrucciones de integración de la API de generación de vídeo Maestro](/es/guides/maestro/maestro_videos): Utilice una indicación en lenguaje natural para producir automáticamente un vídeo terminado con subtítulos; después del envío se devuelve `task_id`, y luego utilice esta interfaz para sondear los resultados.


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