> ## Documentation Index
> Fetch the complete documentation index at: https://gccai.heqingsong.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Generación de vídeo MiniMax-H3-Max

>  - Versión rápida de MiniMax Video Generation V2 con envío asíncrono de tareas
- Admite texto a vídeo, control de fotogramas inicial/final y generación con referencias multimodales
- Admite 480P / 768P / 1080P y vídeos de 5 a 15 segundos con audio
- Admite imágenes, vídeos y audios de referencia; no admite 2K ni fotogramas intermedios 

> [!NOTE]
>
> **Selección del modelo:** `MiniMax-H3-Max` es adecuado para generación rápida desde texto, control de fotogramas inicial/final y referencias multimodales en 480P, 768P o 1080P. Para 2K o fotogramas intermedios, use [MiniMax-H3](https://gccai.heqingsong.uk/es/api-reference/videos/minimax-h3/generation.md).

```bash cURL theme={null}
curl --request POST \
  --url https://gccai.heqingsong.uk/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MiniMax-H3-Max",
    "prompt": "Un detective con gabardina se gira en una calle iluminada por neón bajo la lluvia. La cámara se acerca lentamente.",
    "duration": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://gccai.heqingsong.uk/v1/videos/generations",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={
        "model": "MiniMax-H3-Max",
        "prompt": "Un detective se gira en una calle de neón bajo la lluvia.",
        "duration": 5,
        "resolution": "768P",
        "aspect_ratio": "16:9",
    },
)
print(response.json())
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ"
    }
  ]
}
```

```json 400 theme={null}
{
  "error": {
    "code": 400,
    "message": "Parámetros de solicitud no válidos",
    "type": "invalid_request_error"
  }
}
```

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "message": "Error de autenticación. Compruebe su clave de API.",
    "type": "authentication_error"
  }
}
```

```json 402 theme={null}
{
  "error": {
    "code": 402,
    "message": "Saldo de cuenta insuficiente",
    "type": "payment_required"
  }
}
```

## Autenticación

**Authorization** `string` *required*

Todos los endpoints requieren un Bearer Token. Obtenga su clave en la [página de claves de API](https://gccai.heqingsong.uk/keys).

```
Authorization: Bearer YOUR_API_KEY
```

## Elegir el modelo

| Capacidad | `MiniMax-H3` | `MiniMax-H3-Max` |
| - | - | - |
| Resolución | `2K` / `768P`, predeterminada `2K` | `480P` / `768P` / `1080P`, predeterminada `768P` |
| Duración | 4–15 segundos | 5–15 segundos |
| Texto a vídeo | Compatible | Compatible |
| Fotograma inicial / final | Compatible | Compatible |
| Fotograma intermedio | Compatible | No compatible |
| Referencias multimodales | Imagen, vídeo y audio | Imagen, vídeo y audio |
| Coste de imágenes de entrada | Primeras 5 gratis | Las primeras 2 imágenes son gratuitas; las adicionales se cobran por imagen |
| Coste de vídeos de referencia | Según la duración de entrada, con la misma tarifa que la salida de igual resolución | Según la duración de entrada, con tarifa independiente |
| Marca de agua AIGC | Compatible | Compatible en 480P / 768P; no disponible en 1080P |

> [!WARNING]
>
> `MiniMax-H3-Max` no admite 2K y su salida no puede usarse como origen para [Regeneration](https://gccai.heqingsong.uk/es/api-reference/videos/minimax-h3/regeneration.md).

## Modos de generación

Los campos de la solicitud determinan el modo automáticamente; no envíe `mode`.

| Modo | Activador | Comportamiento |
| - | - | - |
| Texto a vídeo (T2V) | Solo `prompt` y campos comunes | Genera desde texto |
| Imagen a vídeo (I2V) | `first_frame_image` / `last_frame_image` o roles equivalentes en `image_with_roles` | Controla el fotograma inicial, final o ambos |
| Referencias multimodales (R2V) | `image_urls` / `video_urls` / `audio_urls` o `reference_image` en `image_with_roles` | Genera con imágenes, vídeos y audios de referencia; también en 1080P |

> [!WARNING]
>
> Los fotogramas inicial/final no pueden combinarse con referencias. El audio de referencia requiere al menos una imagen o vídeo de referencia. Las combinaciones inválidas devuelven HTTP 400 de forma síncrona, sin crear ni cobrar una tarea.

## Parámetros de solicitud

**model** `string` *required*

Valor fijo: `MiniMax-H3-Max`. No distingue mayúsculas y minúsculas; `minimax-h3-max` también se acepta.

**prompt** `string` *required*

Descripción no vacía del vídeo, obligatoria en todos los modos. Máximo de `7000` caracteres.

**duration** `integer` (default: 5)

Duración en segundos: entero de `5` a `15`, valor predeterminado `5`. No se admiten 4 segundos.

**resolution** `string` (default: 768P)

Resolución de salida: `480P`, `768P` (predeterminada) o `1080P`.

En `1080P`, omita `watermark` y su alias `aigc_watermark`, incluso si su valor es `false`.

> [!WARNING]
>
> `2K`, `1440P` y `2048P` no se admiten. Un valor no válido devuelve HTTP 400 sin reducción automática.

**aspect\_ratio** `string`

Relación de aspecto. También se aceptan los alias `size` y `ratio`.

Valores T2V: `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`.

* T2V sin el campo o con `adaptive`: usa `16:9`
* I2V: la determina la imagen de entrada; este campo se ignora
* Referencias multimodales: opcional, valor predeterminado `adaptive`; también puede indicar una proporción concreta

**first\_frame\_image** `string`

URL pública de la imagen usada como fotograma inicial.

**last\_frame\_image** `string`

URL pública de la imagen usada como fotograma final. Puede usarse sola o junto con `first_frame_image`.

**image\_with\_roles** `object[]`

Array de imágenes con roles que puede sustituir a `first_frame_image`, `last_frame_image` o `image_urls`.

**Elemento de image\_with\_roles**

**url** `string` *required*

URL pública de la imagen

**role** `string`

Roles admitidos:

* `first_frame`; alias `first` y `start`
* `last_frame`; alias `last`, `end_frame` y `tail`
* `reference_image`: imagen de referencia; alias `reference`; un rol vacío se trata como referencia

Como máximo un fotograma inicial y uno final. Las referencias de este array y de `image_urls` suman como máximo `9` imágenes. No mezcle roles de fotograma con roles de referencia.

**image\_urls** `string[]`

Array de URL públicas de imágenes de referencia. Máximo `9` imágenes junto con las referencias de `image_with_roles`. Todas se tratan como referencias, nunca automáticamente como fotogramas inicial/final. Para el fotograma inicial use `first_frame_image` o el rol `first_frame`.

**video\_urls** `string[]`

Array de URL públicas de vídeos de referencia; un solo vídeo también admite `video_url` (string). Máximo `3` clips, de `2` a `15` segundos cada uno, con duración total de vídeos de referencia no superior a `15` segundos.

La duración de los vídeos de referencia se lee al enviar la solicitud para la facturación. Si no puede leerse, se devuelve HTTP 400 de forma síncrona, sin crear ni cobrar una tarea.

**audio\_urls** `string[]`

Array de URL públicas de audios de referencia; un solo clip también admite `audio_url` (string). Máximo `3` clips, de `2` a `15` segundos cada uno, con duración total de audios de referencia no superior a `15` segundos. Requiere al menos una imagen o vídeo de referencia; no admite solo audio.

**watermark** `boolean` (default: false)

Añade una marca de agua AIGC. Alias: `aigc_watermark`.

Las marcas de agua solo se admiten en `480P` / `768P`. En `1080P`, omita `watermark` y su alias `aigc_watermark`, incluso si su valor es `false`.

**webhook** `string`

Recibe una notificación cuando la tarea termina correctamente o con error.

> [!NOTE]
>
> Use `webhook`, no el `callback_url` de MiniMax. La puerta de enlace reserva `callback_url` para uso interno.

## Restricciones de parámetros

Los siguientes parámetros o combinaciones inválidos devuelven HTTP 400 antes de crear y cobrar la tarea:

| Parámetro / valor | Motivo |
| - | - |
| Fotogramas inicial/final combinados con referencias | I2V y R2V son mutuamente excluyentes |
| Más de `9` imágenes de referencia o más de `3` vídeos o audios de referencia | Supera el límite de medios |
| Solo audio de referencia | Requiere una imagen o vídeo de referencia |
| `resolution: "2K"` | Solo se admiten `480P`, `768P` y `1080P` |
| `duration: 4` o superior a `15` | Solo 5–15 segundos |

Cada vídeo y audio de referencia debe durar de 2 a 15 segundos. Los totales de vídeo y audio se calculan por separado y no superan 15 segundos cada uno. Recorte los medios demasiado largos antes de enviarlos; no son entradas válidas.

> [!WARNING]
>
> En `1080P`, omita `watermark` y su alias `aigc_watermark`, incluso si su valor es `false`.

> [!TIP]
>
> Para 2K, fotogramas intermedios o un vídeo de 4 segundos, use [MiniMax-H3](https://gccai.heqingsong.uk/es/api-reference/videos/minimax-h3/generation.md) y ajuste los parámetros.

## Límites de medios de entrada

El cuerpo total de la solicitud no debe superar 64 MB. Use URL públicas para imágenes, vídeos y audios, no Base64.

### Imágenes

| Elemento | Límite |
| - | - |
| Formatos | JPG / JPEG / PNG / WEBP / HEIC / HEIF |
| Por archivo | ≤ 30 MB |
| Ancho y alto | 256–5760 px |
| Relación de aspecto | 0,4–2,5 |
| Cantidad | Máximo 1 fotograma inicial, 1 final y 9 referencias; no mezcle fotogramas con referencias |

### Vídeos de referencia

| Elemento | Límite |
| - | - |
| Formatos | MP4 / MOV, H.264 / H.265 |
| Por archivo | ≤ 50 MB |
| Cantidad | ≤ 3 |
| Duración por clip | 2–15 s |
| Duración total | ≤ 15 s |
| Ancho y alto | 256–5760 px |
| Relación de aspecto | 0.4–2.5 |
| Frecuencia de fotogramas | 23.976–60 fps |

### Audios de referencia

| Elemento | Límite |
| - | - |
| Formatos | WAV / MP3 |
| Por archivo | ≤ 15 MB |
| Cantidad | ≤ 3 |
| Duración por clip | 2–15 s |
| Duración total | ≤ 15 s |

El audio de referencia requiere una imagen o vídeo de referencia. Los totales de duración de vídeo y audio se calculan por separado, cada uno con un máximo de 15 segundos.

Los medios que incumplan los requisitos pueden fallar durante la generación; las tareas fallidas se reembolsan automáticamente.

## Ejemplos

### Imagen a vídeo con fotograma inicial

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "prompt": "La cámara se acerca lentamente mientras asciende el vapor.",
  "first_frame_image": "https://cdn.example.com/ramen.png",
  "duration": 5,
  "resolution": "480P"
}
```

### Imagen a vídeo con fotogramas inicial y final

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "prompt": "La escena pasa gradualmente de la mañana al atardecer.",
  "first_frame_image": "https://cdn.example.com/morning.png",
  "last_frame_image": "https://cdn.example.com/sunset.png",
  "duration": 8,
  "resolution": "768P"
}
```

### Texto a vídeo en 1080P

En `1080P`, omita `watermark` y su alias `aigc_watermark`, incluso si su valor es `false`.

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "prompt": "Atardecer en la costa, olas suaves en la playa, avance lento de cámara, textura cinematográfica.",
  "duration": 5,
  "resolution": "1080P",
  "aspect_ratio": "16:9"
}
```

### Generación con referencias multimodales

Cada vídeo y audio de referencia debe durar de 2 a 15 segundos. Los totales de vídeo y audio se calculan por separado y no superan 15 segundos cada uno. Recorte los medios demasiado largos antes de enviarlos; no son entradas válidas.

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "prompt": "El personaje de la imagen de referencia corre por la escena del vídeo de referencia al ritmo del audio de referencia.",
  "image_urls": [
    "https://cdn.example.com/role.png"
  ],
  "video_urls": [
    "https://cdn.example.com/scene.mp4"
  ],
  "audio_urls": [
    "https://cdn.example.com/beat.mp3"
  ],
  "duration": 6,
  "resolution": "1080P",
  "aspect_ratio": "16:9"
}
```

## Consultar una tarea

El envío devuelve `task_id`. Consulte el [estado de la tarea](https://gccai.heqingsong.uk/es/api-reference/tasks/status.md) cada 5–10 segundos y use un timeout de cliente de 15 minutos.

| `status` | Significado |
| - | - |
| `pending` | Enviada o en cola |
| `processing` | Generándose |
| `completed` | URL del vídeo en `result.videos[0].url` |
| `failed` | Consulte `error.message`; reembolso automático |

> [!NOTE]
>
> Las URL generadas suelen caducar tras unas 24 horas. Descargue y guarde el resultado cuanto antes.

## Precios

El coste total incluye vídeo generado, imágenes adicionales y vídeos de referencia:

```text theme={null}
Coste total = tarifa de generación por segundo × duración de salida
            + tarifa por imagen adicional × max(0, número de imágenes de entrada − 2)
            + tarifa de vídeo de referencia por segundo × duración total de vídeos de referencia
```

Se cuentan juntos los fotogramas inicial/final y las imágenes de referencia. Las primeras 2 imágenes son gratuitas; las adicionales se cobran por imagen. Los vídeos de referencia no superan 15 segundos en total.

| Elemento | Tarifa |
| - | - |
| Vídeo 1080P | Según los precios del modelo |
| Vídeo 768P | Según los precios del modelo |
| Vídeo 480P | Según los precios del modelo |
| Imágenes de entrada | Las primeras 2 imágenes son gratuitas; las adicionales se cobran por imagen; Según los precios del modelo |
| Vídeos de referencia | Se cobra por segundo de entrada según los precios del modelo; depende de la resolución de salida y es independiente de la tarifa de generación |
| Audios de referencia | **Gratis** |

| Ejemplo | Coste |
| - | - |
| 768P / 5s | 768P tarifa de generación × 5 |
| 768P / 10s | 768P tarifa de generación × 10 |
| 480P / 10s | 480P tarifa de generación × 10 |
| 480P / 15s | 480P tarifa de generación × 15 |
| 768P / 5s + Imágenes × 3 | 768P tarifa de generación × 5 + tarifa por imagen adicional × 1 |
| 480P / 10s + Vídeos de referencia (12s) | 480P tarifa de generación × 10 + 480P tarifa de vídeo de referencia × 12 |
| 1080P / 5s + Imágenes × 2 + Audios de referencia | 1080P tarifa de generación × 5 |

Todas las tarifas dependen de los precios del modelo. En el ejemplo 1080P con 2 imágenes de referencia y audio de referencia, las imágenes y el audio son gratuitos.

El importe estimado se reserva al enviar. Las tareas fallidas se reembolsan íntegramente; el campo `cost` de la tarea es definitivo.

## Errores

| Escenario | Resultado |
| - | - |
| `prompt` vacío o superior a 7000 caracteres | 400; sin tarea |
| `duration` fuera de 5–15 | 400; sin tarea |
| `resolution` no admitida | 400; sin tarea |
| Fotogramas inicial/final combinados con referencias / Solo audio de referencia | 400; sin tarea |
| Más de `9` imágenes de referencia o más de `3` vídeos o audios de referencia | 400; sin tarea |
| No se puede leer la duración del vídeo de referencia | 400; sin tarea |
| Rol de imagen inválido o más de una imagen para el mismo rol de fotograma inicial/final | 400; sin tarea |
| Saldo insuficiente | 402 |
| Rechazo de seguridad de contenido | 422 |
| Límite de solicitudes | 429; reintente con backoff |

Los fallos de generación devuelven `status = failed` y `error.message`, con reembolso automático.

## Response

**code** `integer`

Código de respuesta; 200 si es correcto

**data** `array`

Resultado del envío con estado inicial e ID de tarea

**Elemento del array**

**status** `string`

Inicialmente `submitted`

**task\_id** `string`

ID único para consultar progreso y resultado


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