Saltar al contenido principal
La función principal de la API de consulta de tareas de Maestro es consultar el estado de ejecución y el resultado final de una tarea mediante el ID de tarea devuelto por la API de generación de videos de Maestro (POST /maestro/videos). Este documento presentará en detalle las instrucciones de integración de la API de consulta de tareas de Maestro. Debido a que la generación de video es una tarea asíncrona, después del envío se debe usar esta API para consultar periódicamente el progreso y el video finalizado, las consultas periódicas son gratuitas y no consumen créditos. POST https://api.acedata.cloud/maestro/tasks

Proceso de solicitud

Para utilizar la API de consulta de tareas de Maestro, primero obtén tu API Token en la consola de Ace Data Cloud y guárdalo para su uso posterior. Si aún no has iniciado sesión o no te has registrado, serás redirigido automáticamente a la página de inicio de sesión para invitarte a registrarte e iniciar sesión; al completarlo, volverás automáticamente a la página actual. Un API Token puede invocar todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio. La primera solicitud incluirá créditos gratuitos, que permiten una experiencia gratuita; cuando los créditos sean insuficientes, puedes recargar el saldo general en la consola.
📘 Documentación completa: API de consulta de tareas de Maestro →

Consultar una sola tarea

Para saber cómo crear una tarea de video, consulta la documentación API de generación de videos de Maestro. Usaremos como ejemplo uno de los ID de tarea que devuelve: f57e99c4f60f4373a15517742ce2357d, para demostrar cómo consultar su estado y resultado.

Configurar encabezados y cuerpo de la solicitud

Los Request Headers incluyen:
  • accept: especifica que se reciban resultados de respuesta en formato JSON; aquí se establece como application/json.
  • authorization: la clave para invocar la API, que se puede seleccionar directamente en el menú desplegable después de solicitarla.
  • content-type: el formato del cuerpo de la solicitud; aquí se establece como application/json.
El Request Body incluye:

Ejemplo de código

El código CURL correspondiente es el siguiente:
El código Python correspondiente es el siguiente:

Ejemplo de respuesta

Tras procesarse correctamente la solicitud, la API devolverá el estado y el resultado de esta tarea de vídeo. Un ejemplo de la respuesta al completarse la tarea es el siguiente (el array variants contiene un vídeo final):
Los campos del resultado devuelto se describen a continuación:
  • id: el ID de esta tarea de vídeo, utilizado para identificar de forma única esta tarea de generación de vídeo.
  • status: el estado de la tarea; los valores posibles son pending → planning → producing → succeeded (o failed). Para determinar si la tarea ha finalizado, consulte este status de nivel superior.
  • elapsed: el tiempo transcurrido de la tarea (segundos).
  • progress: objeto de progreso de nivel superior. percent (0–100) será 100 cuando la tarea se complete correctamente; stage y message reflejan el evento de progreso más reciente del director de IA (por lo tanto, tras completarse correctamente, stage aún puede ser la última fase de ejecución, como producing) y se pueden utilizar 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: indica si la tarea se realizó correctamente.
    • data.variants: contiene un objeto de vídeo final en el idioma seleccionado, incluidos lang, aspect, title, output_url (URL de descarga del vídeo final), etc.
    • data.project: los resultados de todo el proyecto, incluidos tarball_url (paquete del proyecto) y outputs (enlace del vídeo final).
    • data.progress: array de eventos de progreso añadidos por fase (registro de solo anexado), 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 de inicio de ejecución de la tarea, marca de tiempo Unix (segundos). Es null si 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 se ha completado.

Consultar lista histórica

Al pasar action: retrieve_batch, se pueden obtener las tareas recientes del ejecutor actualmente conectado (en orden descendente por hora de creación), y se puede utilizar para la página de lista de «Mis videos». La lista histórica está aislada según la identidad de inicio de sesión. El Request Body incluye:

Ejemplo de código

El código CURL correspondiente es el siguiente:

Ejemplo de respuesta

Después de que la solicitud se realice correctamente, la API devolverá la lista de tareas históricas del usuario actual:
Los campos del resultado devuelto se describen a continuación:
  • count: El número total de tareas visibles para el ejecutor actualmente autenticado, sin verse afectado por las condiciones de tiempo ni por limit.
  • items: El arreglo de tareas filtradas según 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 por «consultar una sola tarea».

Recomendaciones de sondeo

Dado que la producción de video tarda más 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 API 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 inválido o faltante.
  • 404 not_found: Tarea no encontrada, el task_id proporcionado no existe.
  • 429 too_many_requests: Demasiadas solicitudes, ha excedido el límite de velocidad.
  • 500 api_error: Error interno del servidor, algo salió mal en el servidor.

Ejemplo de respuesta de error

Conclusión

A través de este documento, ya ha comprendido cómo utilizar la API de consulta de tareas de Maestro para consultar el estado y los resultados de una sola tarea, así como 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