Saltar al contenido principal
Maestro es una interfaz de producción de video nativa de Agent: usas un prompt en lenguaje natural para describir el video que deseas (opcionalmente adjuntas imágenes / videos / audios de referencia con file_urls), y un «director de IA» sin interfaz completa automáticamente la selección de tema, escritura de guion, generación de imágenes, locución, música, composición y renderizado, para finalmente producir un video terminado con subtítulos y subirlo al CDN. Este documento presentará en detalle la guía de integración de la API de generación de video Maestro, para ayudarte a integrarla rápidamente y aprovechar plenamente las capacidades de esta API. Esta es una interfaz de tareas asíncronas: tras el envío devolverá inmediatamente un task_id, y posteriormente se obtendrán los resultados mediante sondeo a través de la API de consulta de tareas Maestro (POST /maestro/tasks) (el sondeo es gratuito y no se factura). Para continuar iterando sobre un video existente, puedes usar action: remix / edit / extend junto con ref_task_id.

Proceso de solicitud

Para utilizar la API de generación de video 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 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 solo API Token permite llamar a todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio. La primera solicitud incluirá créditos gratuitos, permitiendo una experiencia gratuita; cuando los créditos sean insuficientes, puedes recargar saldo general en la consola.
📘 Documentación completa: API de generación de video Maestro →

Uso básico

POST https://api.acedata.cloud/maestro/videos Para el uso más básico, solo necesitas proporcionar una prompt en lenguaje natural. El director de IA decidirá automáticamente el guion, las imágenes, la locución y la edición. Primero, veamos los encabezados y el cuerpo de la solicitud que debes configurar. Encabezados de la solicitud incluyen:
  • accept: el formato en el que deseas recibir la respuesta; aquí se establece como application/json, es decir, formato JSON.
  • authorization: la clave para llamar a la API; después de solicitarla, puedes seleccionarla directamente desde el menú desplegable.
  • content-type: el formato del cuerpo de la solicitud; aquí se establece como application/json.
Cuerpo de la solicitud incluye principalmente:
  • prompt: describe en lenguaje natural el vídeo que deseas crear (tema, qué mostrar, estilo y público objetivo).
  • langs: matriz de idiomas del vídeo final; envía solo uno cada vez, como ["zh-cn"]; el valor predeterminado es ["zh-cn"].
  • aspect: relación de aspecto, 9:16 (predeterminado) / 16:9 / 1:1.
  • duration: duración objetivo (segundos); el valor predeterminado es 30.
Todos los campos del cuerpo de la solicitud se muestran en la siguiente tabla: A continuación se muestra un ejemplo concreto. Supongamos que queremos generar un breve video divulgativo en chino, en formato vertical y de 20 segundos. El código CURL correspondiente es el siguiente:
El código Python correspondiente es el siguiente:
Haga clic en Ejecutar; verá que se obtiene un resultado de inmediato, como se muestra a continuación:
Los campos del resultado devuelto se describen a continuación:
  • success: indica si esta tarea se envió correctamente.
  • task_id: ID de esta tarea de generación de video. Úselo posteriormente para consultar el resultado mediante la API de consulta de tareas de Maestro.
  • trace_id: ID de seguimiento de esta solicitud. Si tiene algún problema, puede proporcionarlo al soporte técnico para facilitar el diagnóstico.
Dado que la producción de vídeo requiere bastante tiempo, la API devuelve task_id inmediatamente y no espera a que finalice el renderizado del vídeo. A continuación, debe usar task_id para consultar el resultado mediante sondeo. Consulte la sección «Obtener resultados» para más detalles.

Especificar tipo y estilo de video (scenario / style)

Cuando no se pasa scenario, la IA lo determina automáticamente (equivale a auto); si deseas fijar el video a cierto tipo, pásalo explícitamente. Por ejemplo, para crear un drama corto en formato vertical, puedes especificar lo siguiente:
  • scenario: tipo de video, aquí se establece como drama (drama corto con personajes + diálogos).
  • style: estilo visual, aquí se establece como cinematic (textura cinematográfica).
El código CURL de ejemplo es el siguiente:
Formas comunes de combinación:
  • Cortometraje narrado: scenario: "narrated".
  • Subtítulos automáticos: scenario: "captions", se debe usar file_urls para pasar el video fuente.
  • Avatar digital / locución a cámara: scenario: "avatar", se debe usar file_urls para pasar una imagen de retrato.
  • Drama corto: scenario: "drama" (personajes + diálogos).
  • style es un preajuste de estilo visual (como modern / neon / luxury), no cambia el tipo, solo afecta a la apariencia.
  • voice se utiliza para especificar el timbre de la narración (como warm-female / deep-male), no está relacionado con el idioma y es universal entre idiomas.
El resultado devuelto es consistente con «Uso básico»: también devuelve task_id inmediatamente.

Idioma del video final

Una tarea solo entrega un video final en un idioma. langs solo puede contener un código de idioma, como ["zh-cn"] o ["en"]; pasar varios idiomas devolverá 400. Si necesitas videos en distintos idiomas, crea tareas por separado. La selección de idioma no cambia el precio por segundo.

Iterar sobre un video existente (remix / edit / extend)

Pasa action y el ref_task_id de la tarea anterior para realizar modificaciones incrementales sobre el proyecto original (como «cambiar el título de la escena 2», «cambiar la locución», «oscurecer todo»). Los cambios pequeños son rápidos; los cambios grandes se volverán a realizar:
  • remix: reinterpretar sobre la estructura del video original (conserva el tema, ajusta la presentación).
  • edit: realizar un refinamiento detallado en una parte especificada (como cambiar el título, cambiar la locución o ajustar el color).
  • extend: extender el contenido sobre la base del video original.
El resultado devuelto también es un nuevo task_id inmediatamente; úsalo para consultar y obtener el video final iterado.

Obtener resultados

Dado que la producción de video tarda bastante tiempo, esta interfaz devuelve task_id inmediatamente después del envío; debes usarlo para consultar el resultado mediante la API de consulta de tareas de Maestro:
Cuando la tarea se complete, devolverá información de un video final (ubicada en el array variants). status pasará por pending → planning → producing → succeeded (o failed), la consulta es gratuita y no consume créditos. Para el formato completo de respuesta y la consulta de listas históricas, consulta las instrucciones de integración de la API de consulta de tareas de Maestro.

Facturación

Después de que la tarea se complete correctamente, se factura según la duración real del video final entregado; los fallos no se cobran. La duración facturada se calcula en segundos enteros y no supera la duración solicitada; cuando no se puede leer la duración del video final, se recurre a la duración solicitada. El envío de tareas no se factura por separado, y la consulta de /maestro/tasks es gratuita.
Todos los escenarios, acciones e idiomas utilizan el mismo precio, sin multiplicadores por escenario ni recargos por idioma. Cada tarea solo entrega un video final en un idioma. La duración objetivo solicitada admite de 5 a 300 segundos, con salida uniforme de 1080p / 30fps.

Manejo de errores

Al llamar a la API, si se produce un error, la API devolverá el código de error y la información correspondientes. Por ejemplo:
  • 400 invalid_request: Solicitud incorrecta, posiblemente debido a un prompt faltante o parámetros no válidos.
  • 401 invalid_token: No autorizado, token de autorización no válido o faltante.
  • 403 forbidden: Prohibido, saldo o acceso insuficiente.
  • 429 too_many_requests: Demasiadas solicitudes, has excedido el límite de frecuencia.
  • 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 has aprendido cómo usar la API de generación de video de Maestro: con solo un prompt en lenguaje natural, puedes completar automáticamente el guion, los materiales, la locución, la música, la edición, los subtítulos y el renderizado del video final, y también admite especificar el tipo de video, el estilo, el timbre, el idioma del video final e iterar sobre videos existentes. Esperamos que este documento pueda ayudarte a integrar y utilizar mejor esta API. Si tienes alguna pregunta, no dudes en contactar con nuestro equipo de soporte técnico.

Interfaces relacionadas