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 comoapplication/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 comoapplication/json.
Ejemplo de código
El código CURL 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 arrayvariants contiene un vídeo final):
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 sonpending → planning → producing → succeeded(ofailed). Para determinar si la tarea ha finalizado, consulte estestatusde 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;stageymessagereflejan el evento de progreso más reciente del director de IA (por lo tanto, tras completarse correctamente,stageaún puede ser la última fase de ejecución, comoproducing) 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, incluidoslang,aspect,title,output_url(URL de descarga del vídeo final), etc.data.project: los resultados de todo el proyecto, incluidostarball_url(paquete del proyecto) youtputs(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 pasaraction: 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:count: El número total de tareas visibles para el ejecutor actualmente autenticado, sin verse afectado por las condiciones de tiempo ni porlimit.items: El arreglo de tareas filtradas según las condiciones de tiempo ylimit, 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
- Instrucciones de integración de la API de generación de video de Maestro: Produzca automáticamente un video final con subtítulos utilizando una indicación en lenguaje natural, devuelva
task_iddespués del envío y luego utilice esta interfaz para sondear los resultados.

