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

# Maestro API de generación de videos - Instrucciones de integración

> Maestro AI Video Studio API guide - Ace Data Cloud

Maestro es una interfaz de producción de video **nativa de Agent**: describes el video que deseas con una frase en lenguaje natural `prompt` (opcionalmente puedes adjuntar imágenes / videos / audios de referencia con `file_urls`), y un "director de IA" sin cabeza completará automáticamente la selección de temas, escribirá el guion, generará las imágenes, la voz en off, la música, la composición y el renderizado, produciendo finalmente un video con subtítulos que se subirá a CDN.

Este documento detallará las instrucciones de integración de la API de generación de videos de Maestro, ayudándote a integrar rápidamente y aprovechar al máximo las capacidades de esta API.

Esta es una interfaz de **tarea asíncrona**: después de enviar, se devolverá inmediatamente un `task_id`, y luego podrás consultar los resultados mediante la [API de consulta de tareas de Maestro](/es/guides/maestro/maestro_tasks) (`POST /maestro/tasks`) (la consulta es gratuita y no se cobra). Para continuar iterando sobre un video existente, puedes usar `action: remix` / `edit` / `extend` junto con `ref_task_id`.

## Proceso de solicitud

Para usar la API de generación de videos de Maestro, primero ve a la [Consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obtener tu API Token, que debes guardar como respaldo.

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

Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión que te invitará a registrarte e iniciar sesión; una vez completado, serás redirigido de nuevo a la página actual.

**Un API Token es suficiente para acceder a todos los servicios de la plataforma, no es necesario solicitar uno por cada servicio.** La primera solicitud te otorgará un crédito gratuito para que puedas probarlo; si el crédito es insuficiente, puedes recargar el saldo general en la [consola](https://platform.acedata.cloud/console/coin).

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

## Uso básico

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

La forma más básica de uso solo requiere pasar un `prompt` en lenguaje natural, el director de IA decidirá automáticamente el guion, las imágenes, la voz en off y la edición. Aquí primero entenderemos los encabezados de solicitud y el cuerpo de la solicitud que se deben configurar.

**Request Headers** incluye:

* `accept`: el formato de respuesta que deseas recibir, aquí se debe llenar como `application/json`, es decir, formato JSON.
* `authorization`: la clave para llamar a la API, que puedes seleccionar directamente después de solicitarla.
* `content-type`: el formato del cuerpo de la solicitud, aquí se debe llenar como `application/json`.

**Request Body** incluye principalmente:

* `prompt`: describe en lenguaje natural el video que deseas hacer (tema, qué mostrar, estilo, audiencia).
* `langs`: array de idiomas de salida, como `["zh-cn", "en"]`, por defecto `["zh-cn"]`.
* `aspect`: proporción de la imagen, `9:16` (por defecto) / `16:9` / `1:1`.
* `duration`: duración objetivo (segundos), por defecto 30.

Todos los campos del cuerpo de la solicitud se muestran en la siguiente tabla:

| Campo | Tipo | Requerido | Descripción |
| - | - | - | - |
| `prompt` | string | Sí | Describe en lenguaje natural el video que deseas hacer (tema, qué mostrar, estilo, audiencia). El guion, las imágenes, la voz en off y la edición son decididos por la IA. |
| `action` | string | No | `generate` (por defecto, generar un nuevo video) / `remix` / `edit` / `extend` (iterar sobre un video existente, debe usarse con `ref_task_id`). |
| `ref_task_id` | string | No | Cuando `action` es remix / edit / extend, es obligatorio: el `task_id` de la tarea histórica que sirve como punto de partida. |
| `file_urls` | string\[] | No | Medios de referencia (URL de imágenes / videos / audios), por ejemplo, imágenes de productos que aparecerán, logotipos, o fragmentos de material que necesitan subtítulos. |
| `langs` | string\[] | No | Idiomas de salida, como `["zh-cn", "en"]`, por defecto `["zh-cn"]`. El primero es el idioma principal; por cada idioma adicional se reutiliza la imagen, solo se añade voz en off + renderizado, **cada uno adicional +6 puntos**. |
| `aspect` | string | No | `9:16` (por defecto) / `16:9` / `1:1`, salida unificada a 1080p/30fps. |
| `duration` | int | No | Duración objetivo (segundos), por defecto 30, soporta **5–300 segundos**. Se cobra según la duración real del video, pero no excederá la duración solicitada. |
| `scenario` | string | No | Tipo de video: `auto` / `narrated` / `captions` / `avatar` / `drama`. `captions` requiere el video fuente, `avatar` requiere una imagen de retrato. |
| `style` | string | No | Preset de estilo visual: `auto` (por defecto) / `cinematic` / `glass` / `luxury` / `swiss` / `modern` / `editorial` / `warm` / `vibrant` / `neon` / `mono` / `pastel` / `bold` / `industrial` / `futuristic` / `retro`, también acepta texto libre como sugerencia suave. No cambia la ruta. |
| `voice` | string | No | Tono de voz en off (independiente del idioma, aplicable a múltiples idiomas): `auto` (por defecto) / `warm-female` / `bright-female` / `anchor-female` / `clean-female` / `calm-male` / `deep-male` / `documentary-male` / `energetic-male` / `storyteller-male`. |

A continuación, se muestra un ejemplo concreto. Supongamos que queremos generar un video corto de divulgación científica en chino e inglés, en formato vertical, de 20 segundos; el código CURL correspondiente es el siguiente:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
  "langs": ["zh-cn", "en"],
  "aspect": "9:16",
  "duration": 20
}'
```

El código correspondiente en Python es el siguiente:

```python theme={null}
import requests

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

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

payload = {
    "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
    "langs": ["zh-cn", "en"],
    "aspect": "9:16",
    "duration": 20
}

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

Al hacer clic en ejecutar, se puede observar que se obtiene inmediatamente un resultado, como el siguiente:

```json theme={null}
{
  "success": true,
  "task_id": "f57e99c4f60f4373a15517742ce2357d",
  "trace_id": "70e1cb12-c619-4292-a416-90191205996b"
}
```

La descripción de los campos en el resultado devuelto es la siguiente:

* `success`：Si la tarea se ha enviado con éxito.
* `task_id`：El ID de la tarea de generación de video, que se utilizará posteriormente para consultar los resultados en la [API de consulta de tareas de Maestro](/es/guides/maestro/maestro_tasks).
* `trace_id`：El ID de seguimiento de esta solicitud, que se puede proporcionar al soporte técnico para localizar problemas.

Dado que la producción de video lleva mucho tiempo, la interfaz **devuelve inmediatamente `task_id`** y no esperará a que se complete el renderizado del video. A continuación, se necesita usar `task_id` para consultar los resultados, consulte la sección "Obtener resultados".

## Especificar tipo y estilo de video (scenario / style)

Si no se pasa `scenario`, la IA lo determinará automáticamente (equivalente a `auto`); si se desea fijar el video a un tipo específico, se debe pasar explícitamente. Por ejemplo, para hacer un **drama corto en vertical**, se puede 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` (calidad cinematográfica).

El código CURL de ejemplo es el siguiente:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "Dos compañeros de piso se pelean y se reconcilian por un gato, tres giros, final cálido",
  "scenario": "drama",
  "style": "cinematic",
  "aspect": "9:16",
  "duration": 40
}'
```

Formas comunes de combinación:

* Video narrado: `scenario: "narrated"`, soportado por Lite / Standard / Pro.
* Subtítulos automáticos: `scenario: "captions"`, se debe pasar el video fuente con `file_urls`, soportado por Lite / Standard / Pro.
* Avatar / voz en off: `scenario: "avatar"`, se debe pasar una imagen de retrato con `file_urls`, soportado por Standard / Pro.
* Drama: `scenario: "drama"` (personajes + diálogos), solo soportado por Pro.
* `style` es un preset de estilo visual (como `modern` / `neon` / `luxury`), no cambia el tipo, solo afecta la percepción.
* `voice` se utiliza para especificar el tono de la voz en off (como `warm-female` / `deep-male`), no está relacionado con el idioma, es universal entre idiomas.

El resultado devuelto es el mismo que en "Uso básico", también devuelve inmediatamente `task_id`.

## Salida multilingüe

Al pasar múltiples idiomas en `langs`, se puede generar una versión multilingüe a la vez. El primero es el idioma principal, y cada idioma adicional **reutilizará el mismo conjunto de imágenes**, solo se añadirá la voz en off + renderizado, por lo que **cada idioma adicional solo suma +6 puntos**. Ejemplo:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "Presentar nuestro producto de servicio al cliente inteligente, destacando 3 puntos clave",
  "langs": ["zh-cn", "en", "ja"],
  "aspect": "16:9",
  "duration": 30
}'
```

Una vez completada la tarea, cada idioma corresponderá a un `variant` en la información de resultados (ver [API de consulta de tareas de Maestro](/es/guides/maestro/maestro_tasks)).

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

Al pasar `action` y el `ref_task_id` de la última tarea, se pueden hacer modificaciones diferenciales sobre el proyecto original (como "cambiar el título del acto 2", "cambiar la voz en off", "oscurecer un poco"). Los pequeños cambios son rápidos, los cambios grandes se rehacen:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "remix",
  "ref_task_id": "f57e99c4f60f4373a15517742ce2357d",
  "prompt": "Cambiar el título de apertura por una frase más impactante, oscurecer un poco la paleta de colores"
}'
```

* `remix`：Reinterpretar sobre la estructura del video original (manteniendo el tema, ajustando la presentación).
* `edit`：Hacer ajustes finos en partes específicas (como cambiar títulos, cambiar voces en off, ajustar colores).
* `extend`：Ampliar el contenido sobre la base del video original.

El resultado devuelto también es un nuevo `task_id`, que se puede usar para consultar y obtener el producto final iterado.

## Obtener resultados

Dado que la producción de video lleva mucho tiempo, esta interfaz devuelve inmediatamente `task_id` después de la presentación, se necesita usarlo para consultar los resultados en la [API de consulta de tareas de Maestro](/es/guides/maestro/maestro_tasks):

```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"
}'
```

Cuando la tarea se completa, se devolverá la información del producto final (cada idioma corresponde a un `variant`). `status` pasará por `pending → planning → producing → succeeded` (o `failed`), **la consulta es gratuita y no consume puntos**. Para el formato completo de respuesta y la consulta de lista histórica, consulte la [Guía de integración de la API de consulta de tareas de Maestro](/es/guides/maestro/maestro_tasks).

## Facturación

**Se factura según el producto final real una vez completada la tarea, las tareas fallidas no se cobran.** La facturación se basa en la duración real del producto final entregado y el número de idiomas, y la duración facturada no excederá la duración solicitada. Si un idioma no se produce finalmente, no se cobrará el cargo adicional de +6 por ese idioma. La presentación de la tarea en sí no se factura por separado, la consulta de `/maestro/tasks` es gratuita.

Los puntos para un producto final individual se calculan de la siguiente manera:

```
puntos = duración del producto final en segundos × 0.60 × multiplicador de escenario + 6 × max(número de idiomas - 1, 0)
```

Maestro cobra uniformemente **0.60 puntos/segundo de producto final real**, soporta de 5 a 300 segundos, hasta 4 idiomas y salida de 1080p / 30fps; todas las acciones y escenarios son utilizables.

Multiplicador de escenario: `drama` 1.35× / `avatar` 1.15× / otros 1×.

| Ejemplo | Puntos |
| - | -: |
| Lite 30 segundos | 6 |
| Standard 30 segundos | 18 |
| Standard 60 segundos | 36 |
| Standard 120 segundos | 72 |
| Pro 30 segundos | 36 |
| Pro 300 segundos | 360 |
| Cada idioma adicional entregado | +6 |
| Consulta de `/maestro/tasks` | Gratis |

## Manejo de errores

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

* `400 invalid_request`：Solicitud incorrecta, posiblemente debido a un `prompt` faltante o parámetros inválidos.
* `401 invalid_token`：No autorizado, token de autorización inválido o faltante.
* `403 forbidden`：Prohibido, saldo insuficiente o acceso denegado.
* `429 too_many_requests`：Demasiadas solicitudes, ha superado el límite de tasa.
* `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": "la recuperación falló"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Conclusión

A través de este documento, usted ha aprendido cómo utilizar la API de generación de videos de Maestro: con solo un `prompt` en lenguaje natural, puede completar automáticamente el guion, los materiales, la locución, la música, la edición, los subtítulos y el renderizado del video, y admite la especificación del tipo de video, estilo, tono, salida multilingüe y la iteración sobre videos existentes. Esperamos que este documento le ayude 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 consulta de tareas de Maestro](/es/guides/maestro/maestro_tasks): utilice `POST /maestro/videos` para consultar el estado y los resultados de la tarea con el `task_id` devuelto, o para obtener una lista de tareas históricas (polling gratuito).


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