> ## 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. # Guía de integración de la API de generación de video MiniMax H3 > Minimax API guide - Ace Data Cloud Este artículo presenta la integración y el uso de la API de generación de video MiniMax H3. Esta interfaz admite generación de video a partir de texto, control de fotograma inicial y final, y generación de video con referencias multimodales, utilizando una estructura V2 multimodal `content` unificada para crear tareas. ## Proceso de solicitud Para usar la API de generación de video MiniMax H3, primero ve a la [consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obtener tu API Token y guardarlo como respaldo. ![](https://cdn.acedata.cloud/dvc3cg.jpg) Si aún no has iniciado sesión o te has registrado, se te redirigirá automáticamente a la página de inicio de sesión para invitarte a registrarte e iniciar sesión; al finalizar, volverás automáticamente a la página actual. **Un único 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 para que puedas probarlo sin costo; cuando los créditos sean insuficientes, puedes recargar saldo general en la [consola](https://platform.acedata.cloud/console/coin). > 📘 Documentación completa: [API de generación de video MiniMax H3 →](https://platform.acedata.cloud/documents/minimax-videos-integration) Se recomienda guardar el Token como una variable de entorno, no escribirlo en el código fuente ni confirmarlo en el repositorio de versiones: ```bash theme={null} export ACEDATACLOUD_API_KEY="YOUR_API_KEY" ``` ## Resumen de la interfaz * **Base URL**：`https://api.acedata.cloud` * **Endpoint**：`POST /minimax/videos` * **Método de autenticación**：llevar `authorization: Bearer {token}` en el HTTP Header * **Encabezados de solicitud**： * `accept: application/json` * `content-type: application/json` * **Modelo (model)**：`MiniMax-H3` * **Estructura de entrada**：texto, imágenes, videos y audio se pasan de forma unificada mediante `content` * **Modo de salida**：por defecto espera de forma síncrona a que finalice la generación y devuelve el `task` completo; al pasar `async: true` o `callback_url`, devuelve inmediatamente `task_id` y `trace_id` * **Consulta de resultados**：obtén el estado y el video final mediante la [API de consulta de tareas MiniMax H3](https://platform.acedata.cloud/documents/minimax-tasks-integration) * **Callback asíncrono**：opcional, recibe el resultado final de la tarea mediante `callback_url` No necesitas pasar `action` para seleccionar el modo de generación; la interfaz determinará automáticamente el uso según los tipos de materiales y `role` en `content`. ## Escenarios adecuados | Escenario | Combinación de entrada | Usos habituales | | - | - | - | | Generación de video a partir de texto | Texto | Creatividad publicitaria, previsualización de guiones gráficos, videos cortos, tomas de ambiente | | Generación de video a partir de imagen de fotograma inicial | Texto + imagen de fotograma inicial | Hacer que imágenes de productos, carteles, fotos de personas o ilustraciones cobren vida de forma natural | | Video de fotograma final / inicial y final | Texto + fotograma final, o texto + fotograma inicial + fotograma final | Controlar inicio y final, transiciones, cambios de crecimiento y comparaciones de antes y después | | Generación de video con referencias multimodales | Texto + imágenes / videos / audio de referencia | Mantener la coherencia de personajes y productos, reproducir movimientos, movimientos de cámara, timbre o ritmo de edición | ## Flujo de llamada Cuando no se pasa `async` por defecto, `/minimax/videos` esperará a que finalice la generación y devolverá directamente el `task` completo. Cuando necesites liberar la conexión inmediatamente, pasa `async: true` o `callback_url`: 1. Guarda `task_id` y `trace_id` de la respuesta inmediata. 2. Cuando no haya callback configurado, llama a `/minimax/tasks` aproximadamente cada 10 segundos para consultar. 3. Cuando `task.status` cambie a `succeeded`, obtén el video desde `task.content.url`. 4. Cuando el estado sea `failed` o `cancelled`, detén el sondeo y lee `task.error`. ## Parámetros de solicitud de nivel superior | Parámetro | Tipo | Obligatorio | Valor predeterminado | Descripción | | - | - | - | - | - | | `model` | string | Sí | - | Fijado como `MiniMax-H3` | | `content` | object\[] | Sí | - | Arreglo de contenido multimodal, debe contener un elemento `text` no vacío | | `resolution` | string | Sí | - | `768P` o `2K` | | `duration` | integer | Sí | - | Duración de generación, entero de 4-15 segundos | | `ratio` | string | Obligatorio condicionalmente | `adaptive` | `adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` | | `async` | boolean | No | `false` | Cuando es `true`, devuelve inmediatamente el identificador de tarea y obtiene el resultado mediante la interfaz de tareas | | `callback_url` | string | No | - | URL pública de callback para recibir el resultado final de la tarea; tras proporcionarla se activa automáticamente el modo asíncrono | Las reglas de `ratio` dependen del flujo de trabajo: * **Generación de video a partir de texto**：obligatorio y no puede ser `adaptive`. * **Video de fotograma inicial, fotograma final o inicial y final**：la relación de aspecto la determina la imagen de entrada; se recomienda omitirlo o pasar `adaptive`. * **Generación de video con referencias multimodales**：puede omitirse, el valor predeterminado es `adaptive`; también puedes especificar explícitamente una proporción fija. La interfaz no acepta campos heredados o de compatibilidad, como `prompt`, `image_urls`, `audio_urls`, `messages` y `first_frame_image`. Cuando recibas errores relacionados con este tipo de parámetros, elimina los campos antiguos y migra a `content`; por ejemplo, cambia `"prompt": "一只猫挥手"` por `"content": [{"type": "text", "text": "一只猫挥手"}]`。No envíes simultáneamente los dos formatos, nuevo y antiguo. ## Parámetros de elementos de contenido content Cada elemento de contenido debe tener `type`, y los demás campos se determinan según el tipo: | `type` | Campo de datos | `role` | Descripción | | - | - | - | - | | `text` | `text` | No se pasa | Cada solicitud debe contener un elemento de texto no vacío, con un máximo de 7000 caracteres | | `image_url` | `image_url.url` | `first_frame` | Imagen de fotograma inicial; cuando solo hay una imagen y se omite `role`, también se procesa como fotograma inicial | | `image_url` | `image_url.url` | `last_frame` | Imagen de fotograma final; puede usarse por separado o combinarse con `first_frame` para controlar el inicio y el final | | `image_url` | `image_url.url` | `reference_image` | Referencia de sujeto, personaje, producto, vestimenta, escena o estilo | | `video_url` | `video_url.url` | `reference_video` | Referencia de movimiento, movimiento de cámara, actuación o estructura de edición | | `audio_url` | `audio_url.url` | `reference_audio` | Referencia de timbre, diálogo, música o ritmo | Las direcciones de medios admiten tres formas: * URL HTTPS de acceso público, recomendada para archivos grandes. * `mm_file://{file_id}`, hace referencia a archivos ya cargados o a resultados existentes. * URI de datos Base64 del tipo de medio correspondiente. Base64 aumenta el tamaño aproximadamente en un tercio; asegúrate de que todo el cuerpo de la solicitud no supere los 64 MB. ## Especificaciones de materiales y límites de cantidad | Material | Format | Single-file limit | Dimensions / Duration | Quantity limit | | - | - | - | - | - | | Image | JPG, JPEG, PNG, WEBP, HEIC, HEIF | No more than 30 MB | Both width and height must be 256-5760 px; aspect ratio 0.4-2.5 | Up to 1 first frame, up to 1 last frame, up to 9 reference images | | Video | MP4, MOV; H.264/AVC or H.265/HEVC; audio track AAC or MP3 | No more than 50 MB | Each clip 2-15 seconds, total no more than 15 seconds; both width and height must be 256-5760 px; aspect ratio 0.4-2.5; 23.976-60 fps | Up to 3 reference videos | | Audio | WAV, MP3 | No more than 15 MB | Each clip 2-15 seconds, total no more than 15 seconds | Up to 3 reference audios | Images, videos, and audio in multimodal reference scenarios total no more than 12 files. First/last frame scenarios and reference material scenarios are mutually exclusive: once `reference_image`, `reference_video`, or `reference_audio` is used, `first_frame` or `last_frame` can no longer be used, and vice versa. ## Production-level capability showcase The following are not concept images or placeholder materials, but real reference inputs and actual video outputs from official MiniMax H3 production-level capability samples. The three groups of cases respectively cover brand shorts, live-action narratives, and fashion e-commerce, suitable for evaluating the model's most critical capabilities in commercial production. | Capability | Key observations | | - | - | | Character and face consistency | Whether facial features, hairstyle, makeup, and character temperament remain stable after multi-shot transitions | | Facial performance | Gaze, micro-expressions, emotional tension, and natural head movements in close-up shots | | Product structure preservation | Contours, materials, wearing relationships, and mirror reflections of products such as glasses and handbags | | Brand visual execution | Whether scene atmosphere, film grain, color, Logo, and editing rhythm are unified | | Cinematic narrative | Whether changes in shot scale, character blocking, camera movement, rhythm, and sound can form a complete sequence | Here, “face capability” refers to character appearance consistency, facial details, and performance control in video generation, not identity recognition, face comparison, or face-swapping interfaces. ### High-end brand short: unifying characters, products, and brand assets **Production goal:** 16:9 premium fashion brand film. Establish a cool atmosphere with a desert highway and a vintage car, maintain the female lead's appearance and the structure of the black handbag, and naturally incorporate the brand Logo at the end. This case focuses on testing cross-shot character consistency, product preservation, cinematic texture, and brand closing capability. | Atmosphere and scene reference | Character reference | | - | - | | 荒漠公路与复古汽车的品牌片氛围参考 | 品牌片女主角参考 | | Handbag product reference | Brand Logo reference | | - | - | | 黑色手袋产品参考 | 品牌 Logo 参考 |