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

# Geração de vídeo MiniMax-H3-Max

>  - Versão rápida do MiniMax Video Generation V2 com envio assíncrono de tarefas
- Suporta texto para vídeo, controle dos quadros inicial/final e geração com referências multimodais
- Suporta 480P / 768P / 1080P e vídeos de 5 a 15 segundos com áudio
- Suporta imagens, vídeos e áudios de referência; não suporta 2K nem quadros intermediários 

> [!NOTE]
>
> **Escolha do modelo:** `MiniMax-H3-Max` é indicado para geração rápida a partir de texto, controle dos quadros inicial/final e referências multimodais em 480P, 768P ou 1080P. Para 2K ou quadros intermediários, use [MiniMax-H3](https://gccai.heqingsong.uk/pt/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": "Um detetive de sobretudo se vira em uma rua iluminada por néon sob a chuva. A câmera se aproxima 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": "Um detetive se vira em uma rua de néon sob a chuva.",
        "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 solicitação inválidos",
    "type": "invalid_request_error"
  }
}
```

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "message": "Falha na autenticação. Verifique sua chave de API.",
    "type": "authentication_error"
  }
}
```

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

## Autenticação

**Authorization** `string` *required*

Todos os endpoints exigem Bearer Token. Obtenha sua chave na [página de chaves de API](https://gccai.heqingsong.uk/keys).

```
Authorization: Bearer YOUR_API_KEY
```

## Escolha do modelo

| Capacidade | `MiniMax-H3` | `MiniMax-H3-Max` |
| - | - | - |
| Resolução | `2K` / `768P`, padrão `2K` | `480P` / `768P` / `1080P`, padrão `768P` |
| Duração | 4–15 segundos | 5–15 segundos |
| Texto para vídeo | Suportado | Suportado |
| Primeiro / último quadro | Suportado | Suportado |
| Quadro intermediário | Suportado | Não suportado |
| Referências multimodais | Imagem, vídeo e áudio | Imagem, vídeo e áudio |
| Custo das imagens de entrada | Primeiras 5 grátis | As primeiras 2 imagens são gratuitas; as adicionais são cobradas por imagem |
| Custo de vídeos de referência | Pela duração de entrada, com a mesma tarifa da saída de igual resolução | Pela duração de entrada, com tarifa independente |
| Marca d’água AIGC | Suportada | Suportada em 480P / 768P; indisponível em 1080P |

> [!WARNING]
>
> `MiniMax-H3-Max` não suporta 2K e sua saída não pode ser usada como origem para [Regeneration](https://gccai.heqingsong.uk/pt/api-reference/videos/minimax-h3/regeneration.md).

## Modos de geração

Os campos da solicitação determinam o modo automaticamente; não envie `mode`.

| Modo | Acionador | Comportamento |
| - | - | - |
| Texto para vídeo (T2V) | Apenas `prompt` e campos comuns | Geração a partir de texto |
| Imagem para vídeo (I2V) | `first_frame_image` / `last_frame_image` ou funções equivalentes em `image_with_roles` | Controla o primeiro, o último ou ambos os quadros |
| Referências multimodais (R2V) | `image_urls` / `video_urls` / `audio_urls` ou `reference_image` em `image_with_roles` | Gera com imagens, vídeos e áudios de referência; também em 1080P |

> [!WARNING]
>
> Os quadros inicial/final não podem ser combinados com referências. O áudio de referência exige pelo menos uma imagem ou vídeo de referência. Combinações inválidas retornam HTTP 400 de forma síncrona, sem criar nem cobrar uma tarefa.

## Parâmetros da solicitação

**model** `string` *required*

Valor fixo: `MiniMax-H3-Max`. Não diferencia maiúsculas e minúsculas; `minimax-h3-max` também é aceito.

**prompt** `string` *required*

Descrição não vazia do vídeo, obrigatória em todos os modos. Máximo de `7000` caracteres.

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

Duração em segundos: inteiro de `5` a `15`, padrão `5`. Quatro segundos não são suportados.

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

Resolução de saída: `480P`, `768P` (padrão) ou `1080P`.

Em `1080P`, omita `watermark` e seu alias `aigc_watermark`, mesmo que o valor seja `false`.

> [!WARNING]
>
> `2K`, `1440P` e `2048P` não são suportados. Um valor inválido retorna HTTP 400 sem redução automática.

**aspect\_ratio** `string`

Proporção de saída. Os aliases `size` e `ratio` também são aceitos.

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

* T2V sem o campo ou com `adaptive`: usa `16:9`
* I2V: determinada pela imagem de entrada; este campo é ignorado
* Referências multimodais: opcional, padrão `adaptive`; também permite uma proporção específica

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

URL pública da imagem usada como primeiro quadro.

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

URL pública da imagem usada como último quadro. Pode ser usada sozinha ou com `first_frame_image`.

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

Array de imagens com papéis que pode substituir `first_frame_image`, `last_frame_image` ou `image_urls`.

**Item de image\_with\_roles**

**url** `string` *required*

URL pública da imagem

**role** `string`

Funções suportadas:

* `first_frame`; aliases `first` e `start`
* `last_frame`; aliases `last`, `end_frame` e `tail`
* `reference_image`: imagem de referência; alias `reference`; papel vazio é tratado como referência

No máximo um quadro inicial e um final. As referências deste array e de `image_urls` somam no máximo `9` imagens. Não misture papéis de quadro com papéis de referência.

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

Array de URLs públicas de imagens de referência. No máximo `9` imagens junto com as referências de `image_with_roles`. Todas são referências, nunca automaticamente quadros inicial/final. Para o quadro inicial, use `first_frame_image` ou o papel `first_frame`.

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

Array de URLs públicas de vídeos de referência; para um único vídeo, também aceita `video_url` (string). No máximo `3` clipes, cada um de `2` a `15` segundos, com duração total dos vídeos de referência de até `15` segundos.

A duração dos vídeos de referência é lida no envio para cobrança. Se não puder ser lida, retorna HTTP 400 de forma síncrona, sem criar nem cobrar uma tarefa.

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

Array de URLs públicas de áudios de referência; para um único clipe, também aceita `audio_url` (string). No máximo `3` clipes, cada um de `2` a `15` segundos, com duração total dos áudios de referência de até `15` segundos. Exige pelo menos uma imagem ou vídeo de referência; áudio isolado não é permitido.

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

Adiciona marca d'água AIGC. Alias: `aigc_watermark`.

Marcas d’água são suportadas apenas em `480P` / `768P`. Em `1080P`, omita `watermark` e seu alias `aigc_watermark`, mesmo que o valor seja `false`.

**webhook** `string`

Recebe uma notificação quando a tarefa termina com sucesso ou falha.

> [!NOTE]
>
> Use `webhook`, não o `callback_url` da MiniMax. O gateway reserva `callback_url` para uso interno.

## Restrições de parâmetros

Os parâmetros ou combinações inválidos abaixo retornam HTTP 400 antes da criação e cobrança da tarefa:

| Parâmetro / valor | Motivo |
| - | - |
| Quadros inicial/final combinados com referências | I2V e R2V são mutuamente exclusivos |
| Mais de `9` imagens de referência ou mais de `3` vídeos ou áudios de referência | Limite de quantidade excedido |
| Apenas áudio de referência | Exige imagem ou vídeo de referência |
| `resolution: "2K"` | Apenas `480P`, `768P` e `1080P` são suportados |
| `duration: 4` ou acima de `15` | Apenas 5–15 segundos |

Cada vídeo e áudio de referência deve durar de 2 a 15 segundos. Os totais de vídeo e áudio são calculados separadamente, até 15 segundos cada. Corte os materiais longos antes do envio; eles não são entradas válidas.

> [!WARNING]
>
> Em `1080P`, omita `watermark` e seu alias `aigc_watermark`, mesmo que o valor seja `false`.

> [!TIP]
>
> Para 2K, quadros intermediários ou vídeos de 4 segundos, use [MiniMax-H3](https://gccai.heqingsong.uk/pt/api-reference/videos/minimax-h3/generation.md) e ajuste os parâmetros.

## Limites de mídia de entrada

O corpo total da solicitação não deve exceder 64 MB. Use URLs públicas para imagens, vídeos e áudios, sem Base64.

### Imagens

| Item | Limite |
| - | - |
| Formatos | JPG / JPEG / PNG / WEBP / HEIC / HEIF |
| Por arquivo | ≤ 30 MB |
| Largura e altura | 256–5760 px |
| Proporção | 0,4–2,5 |
| Quantidade | No máximo 1 quadro inicial, 1 final e 9 referências; não misture quadros com referências |

### Vídeos de referência

| Item | Limite |
| - | - |
| Formatos | MP4 / MOV, H.264 / H.265 |
| Por arquivo | ≤ 50 MB |
| Quantidade | ≤ 3 |
| Duração por clipe | 2–15 s |
| Duração total | ≤ 15 s |
| Largura e altura | 256–5760 px |
| Proporção | 0.4–2.5 |
| Taxa de quadros | 23.976–60 fps |

### Áudios de referência

| Item | Limite |
| - | - |
| Formatos | WAV / MP3 |
| Por arquivo | ≤ 15 MB |
| Quantidade | ≤ 3 |
| Duração por clipe | 2–15 s |
| Duração total | ≤ 15 s |

O áudio de referência exige uma imagem ou vídeo de referência. As durações totais de vídeo e áudio são calculadas separadamente, até 15 segundos cada.

Mídias fora dos requisitos podem falhar durante a geração; tarefas com falha são reembolsadas automaticamente.

## Exemplos

### Imagem para vídeo com primeiro quadro

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "prompt": "A câmera se aproxima lentamente enquanto o vapor sobe.",
  "first_frame_image": "https://cdn.example.com/ramen.png",
  "duration": 5,
  "resolution": "480P"
}
```

### Imagem para vídeo com primeiro e último quadros

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "prompt": "A cena passa gradualmente da manhã ao pôr do sol.",
  "first_frame_image": "https://cdn.example.com/morning.png",
  "last_frame_image": "https://cdn.example.com/sunset.png",
  "duration": 8,
  "resolution": "768P"
}
```

### Texto para vídeo em 1080P

Em `1080P`, omita `watermark` e seu alias `aigc_watermark`, mesmo que o valor seja `false`.

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "prompt": "Pôr do sol no litoral, ondas suaves na praia, aproximação lenta da câmera, textura cinematográfica.",
  "duration": 5,
  "resolution": "1080P",
  "aspect_ratio": "16:9"
}
```

### Geração com referências multimodais

Cada vídeo e áudio de referência deve durar de 2 a 15 segundos. Os totais de vídeo e áudio são calculados separadamente, até 15 segundos cada. Corte os materiais longos antes do envio; eles não são entradas válidas.

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "prompt": "O personagem da imagem de referência corre pela cena do vídeo de referência no ritmo do áudio de referência.",
  "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 uma tarefa

O envio retorna `task_id`. Consulte o [status da tarefa](https://gccai.heqingsong.uk/pt/api-reference/tasks/status.md) a cada 5–10 segundos e use timeout de 15 minutos.

| `status` | Significado |
| - | - |
| `pending` | Enviada ou na fila |
| `processing` | Em geração |
| `completed` | URL do vídeo em `result.videos[0].url` |
| `failed` | Consulte `error.message`; reembolso automático |

> [!NOTE]
>
> As URLs geradas normalmente expiram em cerca de 24 horas. Baixe e armazene o resultado rapidamente.

## Preços

O custo total inclui o vídeo gerado, imagens adicionais e vídeos de referência:

```text theme={null}
Custo total = tarifa de geração por segundo × duração de saída
            + tarifa por imagem adicional × max(0, quantidade de imagens de entrada − 2)
            + tarifa de vídeo de referência por segundo × duração total dos vídeos de referência
```

Quadros inicial/final e imagens de referência são contados juntos. As primeiras 2 imagens são gratuitas; as adicionais são cobradas por imagem. Vídeos de referência totalizam no máximo 15 segundos.

| Item | Preço |
| - | - |
| Vídeo 1080P | Conforme os preços do modelo |
| Vídeo 768P | Conforme os preços do modelo |
| Vídeo 480P | Conforme os preços do modelo |
| Imagens de entrada | As primeiras 2 imagens são gratuitas; as adicionais são cobradas por imagem; Conforme os preços do modelo |
| Vídeos de referência | Cobrado por segundo de entrada conforme os preços do modelo; varia com a resolução de saída e é separado da tarifa de geração |
| Áudios de referência | **Grátis** |

| Exemplo | Custo |
| - | - |
| 768P / 5s | 768P tarifa de geração × 5 |
| 768P / 10s | 768P tarifa de geração × 10 |
| 480P / 10s | 480P tarifa de geração × 10 |
| 480P / 15s | 480P tarifa de geração × 15 |
| 768P / 5s + Imagens × 3 | 768P tarifa de geração × 5 + tarifa por imagem adicional × 1 |
| 480P / 10s + Vídeos de referência (12s) | 480P tarifa de geração × 10 + 480P tarifa de vídeo de referência × 12 |
| 1080P / 5s + Imagens × 2 + Áudios de referência | 1080P tarifa de geração × 5 |

Todas as tarifas seguem os preços do modelo. No exemplo 1080P com 2 imagens de referência e áudio de referência, imagens e áudio são gratuitos.

O valor estimado é reservado no envio. Tarefas com falha recebem reembolso integral; o campo `cost` da tarefa é definitivo.

## Erros

| Cenário | Resultado |
| - | - |
| `prompt` vazio ou acima de 7000 caracteres | 400; nenhuma tarefa |
| `duration` fora de 5–15 | 400; nenhuma tarefa |
| `resolution` não suportada | 400; nenhuma tarefa |
| Quadros inicial/final combinados com referências / Apenas áudio de referência | 400; nenhuma tarefa |
| Mais de `9` imagens de referência ou mais de `3` vídeos ou áudios de referência | 400; nenhuma tarefa |
| Não foi possível ler a duração do vídeo de referência | 400; nenhuma tarefa |
| Papel de imagem inválido ou mais de uma imagem para o mesmo papel de quadro inicial/final | 400; nenhuma tarefa |
| Saldo insuficiente | 402 |
| Rejeição de segurança | 422 |
| Limite de solicitações | 429; tente novamente com backoff |

Falhas na geração retornam `status = failed` e `error.message`, com reembolso automático.

## Response

**code** `integer`

Código de resposta; 200 em caso de sucesso

**data** `array`

Resultado do envio com status inicial e ID da tarefa

**Item do array**

**status** `string`

Inicialmente `submitted`

**task\_id** `string`

ID exclusivo usado para consultar progresso e resultado


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