> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/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 e imagem para vídeo com primeiro quadro, último quadro ou ambos
- Suporta 768P / 480P, duração de 5 a 15 segundos e faixa de áudio
- Não suporta 2K, quadros intermediários ou referências multimodais 

<Info>
  **Escolha do modelo:** use `MiniMax-H3-Max` quando a velocidade for prioridade e texto para vídeo ou controle do primeiro/último quadro for suficiente. Para 2K, quadros intermediários, imagens, vídeos ou áudios de referência, use [MiniMax-H3](/pt/api-reference/videos/minimax-h3/generation).
</Info>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.apimart.ai/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://api.apimart.ai/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())
  ```
</RequestExample>

<ResponseExample>
  ```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"
    }
  }
  ```
</ResponseExample>

## Autenticação

<ParamField header="Authorization" type="string" required>
  Todos os endpoints exigem Bearer Token. Obtenha sua chave na [página de chaves de API](https://apimart.ai/keys).

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Escolha do modelo

| Capacidade                   | `MiniMax-H3`               | `MiniMax-H3-Max`               |
| ---------------------------- | -------------------------- | ------------------------------ |
| Resolução                    | `2K` / `768P`, padrão `2K` | `768P` / `480P`, 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      | Não suportado                  |
| Custo das imagens de entrada | Primeiras 5 grátis         | Grátis                         |

<Warning>
  `MiniMax-H3-Max` não suporta 2K e sua saída não pode ser usada como origem para [Regeneration](/pt/api-reference/videos/minimax-h3/regeneration).
</Warning>

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

<Warning>
  Este modelo não suporta `image_urls`, `video_urls`, `audio_urls` nem `image_with_roles[].role = "reference_image"`. Qualquer mídia de referência retorna HTTP 400 antes da criação e cobrança da tarefa.
</Warning>

## Parâmetros da solicitação

<ParamField body="model" type="string" required>
  Valor fixo: `MiniMax-H3-Max`. Não diferencia maiúsculas e minúsculas; `minimax-h3-max` também é aceito.
</ParamField>

<ParamField body="prompt" type="string" required>
  Descrição não vazia do vídeo, obrigatória em todos os modos. Máximo de `7000` caracteres.
</ParamField>

<ParamField body="duration" type="integer" default="5">
  Duração em segundos: inteiro de `5` a `15`, padrão `5`. Quatro segundos não são suportados.
</ParamField>

<ParamField body="resolution" type="string" default="768P">
  Resolução: `768P` (padrão) ou `480P`.

  <Warning>
    `2K`, `1440P` e `2048P` não são suportados. Um valor inválido retorna HTTP 400 sem redução automática.
  </Warning>
</ParamField>

<ParamField body="aspect_ratio" type="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
</ParamField>

<ParamField body="first_frame_image" type="string">
  URL pública da imagem usada como primeiro quadro.
</ParamField>

<ParamField body="last_frame_image" type="string">
  URL pública da imagem usada como último quadro. Pode ser usada sozinha ou com `first_frame_image`.
</ParamField>

<ParamField body="image_with_roles" type="object[]">
  Array de imagens com funções, alternativo a `first_frame_image` e `last_frame_image`.

  <Expandable title="Item de image_with_roles">
    <ResponseField name="url" type="string" required>
      URL pública da imagem
    </ResponseField>

    <ResponseField name="role" type="string" required>
      Funções suportadas:

      * `first_frame`; aliases `first` e `start`
      * `last_frame`; aliases `last`, `end_frame` e `tail`
    </ResponseField>
  </Expandable>

  No máximo uma imagem por função; `role` não pode ficar vazio.
</ParamField>

<ParamField body="watermark" type="boolean" default="false">
  Adiciona marca d'água AIGC. Alias: `aigc_watermark`.
</ParamField>

<ParamField body="webhook" type="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.
  </Note>
</ParamField>

## Parâmetros não suportados

Os valores abaixo retornam HTTP 400 antes da criação e cobrança:

| Parâmetro / valor                             | Motivo                                                     |
| --------------------------------------------- | ---------------------------------------------------------- |
| `image_urls`                                  | Tratado como imagens de referência, que não são suportadas |
| `image_with_roles[].role = "reference_image"` | Apenas primeiro e último quadros são suportados            |
| `video_urls` / `video_url`                    | Vídeo de referência não suportado                          |
| `audio_urls` / `audio_url`                    | Áudio de referência não suportado                          |
| `resolution: "2K"`                            | Apenas `768P` e `480P`                                     |
| `duration: 4` ou acima de `15`                | Apenas 5–15 segundos                                       |

<Tip>
  Para referências, 2K, quadros intermediários ou vídeo de 4 segundos, use [MiniMax-H3](/pt/api-reference/videos/minimax-h3/generation).
</Tip>

## Limites das imagens

O corpo total da solicitação deve ter no máximo 64 MB. Use URLs públicas; Base64 não é suportado.

| 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       | Até 1 primeiro quadro e 1 último quadro; 2 imagens no total |

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

## Consultar uma tarefa

O envio retorna `task_id`. Consulte o [status da tarefa](/pt/api-reference/tasks/status) 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.
</Note>

## Preços

Custo total = preço por segundo × duração. As imagens do primeiro e último quadro são gratuitas.

| Item               | Preço                  |
| ------------------ | ---------------------- |
| Vídeo 768P         | **\$0.075 / segundo**  |
| Vídeo 480P         | **\$0.0495 / segundo** |
| Imagens de entrada | **Grátis**             |

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              |
| Mídia de referência                        | 400; nenhuma tarefa              |
| Função de imagem inválida ou repetida      | 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

<ResponseField name="code" type="integer">
  Código de resposta; 200 em caso de sucesso
</ResponseField>

<ResponseField name="data" type="array">
  Resultado do envio com status inicial e ID da tarefa

  <Expandable title="Item do array">
    <ResponseField name="status" type="string">
      Inicialmente `submitted`
    </ResponseField>

    <ResponseField name="task_id" type="string">
      ID exclusivo usado para consultar progresso e resultado
    </ResponseField>
  </Expandable>
</ResponseField>