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

# Vidu Q4 Preview Geração de vídeo

> Gere vídeos a partir de um quadro inicial ou até 15 imagens e 3 clipes de áudio de referência. 3–16 segundos, até 4K, com áudio por padrão.

<Info>
  Este modelo aceita imagem para vídeo e referências para vídeo, mas não texto sem imagens nem quadros inicial e final combinados. Após o envio, obtenha o ID em `data[0].task_id` e consulte o status e o resultado em [Consulta de tarefas](/pt/api-reference/tasks/status).
</Info>

## Modos de geração

`viduq4-preview` seleciona o modo automaticamente conforme as imagens, os papéis e o áudio de referência. Não é necessário um parâmetro de modo adicional.

| Entrada | Modo |
| - | - |
| Apenas `first_frame_image` ou uma imagem com `role: "first_frame"` | Imagem para vídeo |
| Uma imagem sem papel e sem áudio de referência | Imagem para vídeo |
| Papel `reference_image` ou `reference` presente, sem quadro inicial explícito | Referências para vídeo |
| Total de 2–15 imagens, sem quadro inicial explícito | Referências para vídeo |
| Áudio de referência e 1–15 imagens, sem quadro inicial explícito | Referências para vídeo |

* **Imagem para vídeo**: exatamente um quadro inicial; prompt opcional; não aceita áudio de referência.
* **Referências para vídeo**: 1–15 imagens, até 3 clipes de áudio de referência e **prompt obrigatório**. Com apenas uma imagem sem áudio de referência, defina `role: "reference_image"` explicitamente; caso contrário, será usado imagem para vídeo.
* Um quadro inicial explícito (`first_frame_image` ou `role: "first_frame"`) não pode ser combinado com outras imagens, papéis de referência ou áudio de referência. Caso contrário, retorna HTTP 400.

<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": "viduq4-preview",
      "prompt": "Uma garota se vira sorrindo, seus cabelos longos voam ao vento e a câmera se aproxima lentamente",
      "image_urls": ["https://example.com/first-frame.png"],
      "duration": 5,
      "resolution": "1080p"
    }'
  ```

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

  response = requests.post(
      "https://api.apimart.ai/v1/videos/generations",
      headers={"Authorization": "Bearer <token>"},
      json={
          "model": "viduq4-preview",
          "prompt": "Uma garota se vira sorrindo, seus cabelos longos voam ao vento e a câmera se aproxima lentamente",
          "image_urls": ["https://example.com/first-frame.png"],
          "duration": 5,
          "resolution": "1080p"
      }
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "viduq4-preview",
      prompt: "Uma garota se vira sorrindo, seus cabelos longos voam ao vento e a câmera se aproxima lentamente",
      image_urls: ["https://example.com/first-frame.png"],
      duration: 5,
      resolution: "1080p"
    })
  });
  if (!response.ok) throw new Error(await response.text());
  console.log(await response.json());
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01K..."
      }
    ]
  }
  ```
</ResponseExample>

## Cabeçalhos da requisição

<ParamField header="Authorization" type="string" required>
  Autenticação Bearer no formato `Bearer <token>`, em que `<token>` é sua APIMart API Key.
</ParamField>

## Parâmetros da requisição

<ParamField body="model" type="string" required>
  Deve ser exatamente `viduq4-preview`, em letras minúsculas.
</ParamField>

<ParamField body="prompt" type="string">
  Prompt de geração de vídeo, até 20.000 caracteres.

  * Imagem para vídeo: opcional. Se omitido, o modelo gera o conteúdo com base no quadro inicial.
  * Referências para vídeo: obrigatório. Se ausente, retorna HTTP 400.
</ParamField>

<ParamField body="image_urls" type="string[]">
  Array de imagens. Aceita URLs públicas ou Data URLs Base64, como `data:image/png;base64,...`.

  * Imagem para vídeo: apenas uma imagem, usada como quadro inicial.
  * Referências para vídeo: 1–15 imagens no total com `image_with_roles`.

  Pode ser combinado com `image_with_roles`; as quantidades são somadas. Não combine com `first_frame_image` nem com um papel `first_frame` explícito. Para uma imagem sem papel, a presença de áudio de referência também determina o modo.
</ParamField>

<ParamField body="image_with_roles" type="object[]">
  Array de imagens com papéis. Um elemento para imagem para vídeo; 1–15 imagens no total com `image_urls` para referências para vídeo.

  <Expandable title="Mostrar campos de imagem">
    <ParamField body="url" type="string" required>
      URL pública da imagem ou Data URL Base64.
    </ParamField>

    <ParamField body="role" type="string">
      Papel da imagem, sem distinção entre maiúsculas e minúsculas:

      * `first_frame`: quadro inicial para imagem para vídeo.
      * `reference_image`: imagem de referência; também aceita `reference`.
      * Omitido ou vazio: sem áudio de referência, o total determina o modo: uma imagem para imagem para vídeo, duas ou mais para referências para vídeo. Com áudio de referência, usa referências para vídeo.

      Outros valores, como `last_frame`, retornam HTTP 400 de forma síncrona.
    </ParamField>
  </Expandable>

  Pode ser combinado com `image_urls` para fornecer referências, mas papéis de quadro inicial não podem ser misturados com materiais de referência.
</ParamField>

<ParamField body="first_frame_image" type="string">
  Somente para imagem para vídeo. URL pública ou Data URL Base64 do quadro inicial.

  Ao usar este campo, não forneça outras imagens nem áudio de referência. Para referências para vídeo, use `image_urls` ou `image_with_roles`.
</ParamField>

<ParamField body="audio_urls" type="string[]">
  Array de URLs de áudio de referência, somente para referências para vídeo. Até 3 clipes no total com `audio_url`.

  Formato MP3, cada clipe com 3–12 segundos e até 50MB. Mesmo com áudio de referência, são necessários pelo menos uma imagem e um `prompt`.

  Formato ou duração de áudio inválidos causam falha durante a execução com reembolso integral, e não HTTP 400 síncrono no envio.
</ParamField>

<ParamField body="audio_url" type="string">
  URL de um único áudio de referência. Mesmos requisitos de `audio_urls`; até 3 clipes entre os dois campos.
</ParamField>

<ParamField body="aspect_ratio" type="string" default="16:9">
  Somente para referências para vídeo. Aceita `1:1`, `9:16`, `16:9`, `3:4` e `4:3`. Padrão: `16:9`.

  Em imagem para vídeo, o quadro inicial determina a proporção e este parâmetro é ignorado.
</ParamField>

<ParamField body="size" type="string">
  Alias de compatibilidade de `aspect_ratio` com os mesmos valores. Recomenda-se usar apenas um dos campos. Sem efeito em imagem para vídeo.
</ParamField>

<ParamField body="duration" type="integer" default="5">
  Duração em segundos. Aceita 3–16 segundos, não 1–2 segundos.
</ParamField>

<ParamField body="resolution" type="string" default="720p">
  Resolução: `540p`, `720p`, `1080p`, `2K` ou `4K`, sem distinção entre maiúsculas e minúsculas.
</ParamField>

<ParamField body="audio" type="boolean" default="true">
  Define se o vídeo inclui diálogos e efeitos sonoros.

  * `true`: vídeo com faixa de áudio (padrão).
  * `false`: vídeo sem som.

  Vídeos com ou sem som têm o mesmo preço.
</ParamField>

<ParamField body="seed" type="integer">
  Semente aleatória. Omita ou envie `0` para um valor aleatório.
</ParamField>

## Requisitos dos materiais

* Imagem para vídeo: exatamente um quadro inicial obrigatório; não aceita áudio de referência.
* Referências para vídeo: 1–15 imagens obrigatórias; até 3 clipes de áudio de referência opcionais.
* PNG, JPEG, JPG e WEBP, até 50MB por imagem.
* Com Base64, o corpo inteiro da requisição deve ser menor que 20MB. Prefira URLs públicas.
* URLs de imagem devem ser públicas. Substitua as URLs de exemplo por endereços realmente acessíveis.

<Warning>
  Ambos os modos exigem imagens e não aceitam `last_frame_image`. Misturar quadros iniciais com referências ou exceder as quantidades de imagens/áudio retorna HTTP 400 no envio, sem criar tarefa nem cobrar. Formato ou duração inválidos de áudio de referência causam falha na execução e reembolso.
</Warning>

## Exemplos de requisição

### Apenas quadro inicial, sem prompt

```json theme={null}
{
  "model": "viduq4-preview",
  "image_urls": ["https://example.com/first-frame.png"]
}
```

Por padrão, gera vídeo de 5 segundos, 720p e com áudio.

### Quadro inicial com papel explícito e saída 4K

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "A câmera se aproxima lentamente enquanto a pessoa sorri naturalmente",
  "image_with_roles": [
    {
      "url": "https://example.com/first-frame.png",
      "role": "first_frame"
    }
  ],
  "duration": 8,
  "resolution": "4K",
  "audio": true
}
```

### Vídeo sem som usando o campo de quadro inicial

```json theme={null}
{
  "model": "viduq4-preview",
  "first_frame_image": "https://example.com/first-frame.png",
  "duration": 5,
  "resolution": "1080p",
  "audio": false
}
```

### Vídeo com várias imagens e áudio de referência

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "O garoto da imagem 1 fala com a garota da imagem 2 usando o conteúdo do áudio de referência, no café da imagem 3",
  "image_urls": [
    "https://example.com/boy.png",
    "https://example.com/girl.png",
    "https://example.com/cafe.png"
  ],
  "audio_urls": ["https://example.com/line.mp3"],
  "aspect_ratio": "16:9",
  "duration": 8,
  "resolution": "720p"
}
```

### Referências para vídeo com uma única imagem

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "A pessoa da imagem de referência entra em um café e acena para os funcionários",
  "image_with_roles": [
    {
      "url": "https://example.com/person.png",
      "role": "reference_image"
    }
  ],
  "aspect_ratio": "9:16",
  "duration": 5,
  "resolution": "1080p"
}
```

Este exemplo não inclui áudio de referência e seleciona o modo referências para vídeo pelo papel `reference_image`. Substitua todas as URLs de imagem e áudio por endereços acessíveis.

## Resposta de envio

<ResponseField name="code" type="integer">
  Código de resposta; `200` indica sucesso.
</ResponseField>

<ResponseField name="data" type="array">
  Resultado do envio da tarefa.

  <Expandable title="Mostrar campos da tarefa">
    <ResponseField name="status" type="string">
      `submitted` indica envio bem-sucedido, não a conclusão da geração.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      ID da tarefa para consultar status e resultados.
    </ResponseField>
  </Expandable>
</ResponseField>

## Consultar resultados

Consulte a cada 5–10 segundos e pare em `completed` ou `failed`. Use o endpoint unificado:

```bash theme={null}
curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01K... \
  --header 'Authorization: Bearer <token>'
```

Exemplo de resposta bem-sucedida (URL de vídeo ilustrativa):

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "completed",
    "progress": 100,
    "result": {
      "videos": [
        {
          "url": ["https://example.com/generated-video.mp4"]
        }
      ]
    }
  }
}
```

| Status | Ação |
| - | - |
| `pending` | Na fila; continuar consultando |
| `processing` | Em geração; continuar consultando |
| `completed` | Sucesso; ler os links no array `data.result.videos[0].url` |
| `failed` | Falha; ler o motivo em `data.error.message` e parar as consultas; reembolso integral |

Os links de vídeo são válidos por 24 horas. Baixe e salve os arquivos rapidamente. Use `status` para determinar a conclusão, não valores fixos de progresso.

## Cobrança

Cobrança por duração e resolução: custo = duração (segundos) × preço por segundo da resolução.

Consulte os [preços dos modelos](https://apimart.ai/pricing). Os dois modos têm o mesmo preço, com ou sem áudio. Imagens e áudios de referência não geram cobrança adicional. Tarefas que falham são automaticamente reembolsadas integralmente.

## Erros de parâmetros comuns

Os seguintes casos retornam HTTP 400 de forma síncrona, sem criar tarefa nem cobrar:

| Problema | Ação |
| - | - |
| Nenhuma imagem | Forneça um quadro inicial ou 1–15 imagens de referência conforme o modo |
| Quadro inicial explícito misturado com outras imagens, papéis ou áudio de referência | Mantenha apenas um quadro inicial para imagem para vídeo; remova campos ou papéis de quadro inicial explícito para referências para vídeo |
| `role` não aceito, como `last_frame` | Use `first_frame`, `reference_image`, `reference` ou deixe vazio |
| Mais de 15 imagens de referência | Limite `image_urls` e `image_with_roles` a 15 no total |
| Mais de 3 clipes de áudio de referência | Limite `audio_urls` e `audio_url` a 3 no total |
| `prompt` ausente em referências para vídeo | Adicione um prompt de até 20.000 caracteres |
| Proporção de referência não aceita, como `21:9` | Use `1:1`, `9:16`, `16:9`, `3:4` ou `4:3` |
| `last_frame_image` fornecido | Remova o campo; quadros inicial e final combinados não são aceitos |
| `duration` menor que 3 ou maior que 16 | Use um inteiro de 3 a 16 segundos |
| Resolução não aceita, como `480p` ou `8K` | Use `540p`, `720p`, `1080p`, `2K` ou `4K` |

## Outros modelos Vidu

Para texto para vídeo ou quadros inicial e final, use [Vidu Q3 Pro / Turbo](/pt/api-reference/videos/vidu-q3-pro/generation). Este modelo já aceita várias imagens de referência; [Vidu Q3 Mix / Standard](/pt/api-reference/videos/vidu-q3/generation) também oferece referências para vídeo. Para clipes de 1–2 segundos, escolha `viduq3-pro`; este modelo exige pelo menos 3 segundos.


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