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

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 (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 y guárdelo como respaldo.

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.

📘 Documentación completa: API de consulta de tareas Maestro →

Consultar una sola tarea

Sobre cómo crear una tarea de video, consulte el documento API de generación de videos Maestro. 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:

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:

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):

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

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:

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

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

Primeros pasos

Chat de IA

Imagen de IA

Video de IA

Audio de IA

Web y datos

CAPTCHA

Identidad

Coding

Más guías

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

Proceso de solicitud

Consultar una sola tarea

Configurar los encabezados y el cuerpo de la solicitud

Ejemplo de código

Ejemplo de respuesta

Consultar la lista de historial

Ejemplo de código

Ejemplo de respuesta

Recomendaciones de sondeo

Manejo de errores

Ejemplo de respuesta de error

Conclusión

Interfaces relacionadas

​Proceso de solicitud

​Consultar una sola tarea

​Configurar los encabezados y el cuerpo de la solicitud

​Ejemplo de código

​Ejemplo de respuesta

​Consultar la lista de historial

​Ejemplo de código

​Ejemplo de respuesta

​Recomendaciones de sondeo

​Manejo de errores

​Ejemplo de respuesta de error

​Conclusión

​Interfaces relacionadas

Proceso de solicitud

Consultar una sola tarea

Configurar los encabezados y el cuerpo de la solicitud

Ejemplo de código

Ejemplo de respuesta

Consultar la lista de historial

Ejemplo de código

Ejemplo de respuesta

Recomendaciones de sondeo

Manejo de errores

Ejemplo de respuesta de error

Conclusión

Interfaces relacionadas