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

# Pixverse v6 Geração de Vídeo

>  - Modelo unificado de geração de vídeo Pixverse v6
- Suporta texto-para-vídeo, imagem-para-vídeo, transição entre primeiro/último frame, fusão de múltiplas imagens de referência e extensão de vídeo
- Suporta resoluções 360p/540p/720p/1080p, duração de 1–15 segundos
- API de tarefas assíncronas: após o envio, consulte o resultado pelo ID da tarefa 

<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": "pixverse-v6",
      "prompt": "A cinematic shot of a corgi running through a sunflower field at golden hour",
      "size": "16:9",
      "resolution": "540p",
      "duration": 5
    }'
  ```

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

  url = "https://api.apimart.ai/v1/videos/generations"

  payload = {
      "model": "pixverse-v6",
      "prompt": "A cinematic shot of a corgi running through a sunflower field at golden hour",
      "size": "16:9",
      "resolution": "540p",
      "duration": 5
  }

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://api.apimart.ai/v1/videos/generations";

  const payload = {
    model: "pixverse-v6",
    prompt: "A cinematic shot of a corgi running through a sunflower field at golden hour",
    size: "16:9",
    resolution: "540p",
    duration: 5
  };

  const headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  };

  fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload)
  })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error("Error:", error));
  ```
</RequestExample>

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

  ```json 400 theme={null}
  {
    "error": {
      "type": "invalid_request_error",
      "message": "invalid duration 20, allowed range: 1-15 seconds"
    }
  }
  ```

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

  ```json 403 theme={null}
  {
    "error": {
      "code": 403,
      "message": "insufficient quota: balance=0, required=0.25",
      "type": "quota_not_enough"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": 429,
      "message": "Muitas requisições, tente novamente mais tarde",
      "type": "rate_limit_error"
    }
  }
  ```
</ResponseExample>

## Autenticação

<ParamField header="Authorization" type="string" required>
  Todos os endpoints requerem autenticação via Bearer Token.

  Obter uma API Key:

  Acesse a [página de gerenciamento de API Key](https://apimart.ai/keys) para obter sua API Key.

  Adicione o seguinte cabeçalho à requisição:

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

## Parâmetros da requisição

<ParamField body="model" type="string" required>
  Nome do modelo de geração de vídeo. Fixo em `pixverse-v6`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Descrição do conteúdo do vídeo, até 5000 caracteres. Obrigatório em todos os modos.
</ParamField>

<ParamField body="resolution" type="string" default="540p">
  Nível de resolução do vídeo. Afeta diretamente a cobrança.

  * `360p`: SD
  * `540p`: Padrão (padrão)
  * `720p`: HD
  * `1080p`: Full HD

  <Warning>
    Outros valores de resolução retornam erro de parâmetro.
  </Warning>
</ParamField>

<ParamField body="duration" type="integer" default="5">
  Duração do vídeo em segundos, faixa `1–15`.

  <Warning>
    O modo de transição entre primeiro/último frame só suporta `5` ou `8` segundos.
  </Warning>
</ParamField>

<ParamField body="size" type="string" default="16:9">
  Proporção do vídeo. Efetivo apenas nos modos texto-para-vídeo e fusão de múltiplas referências.

  * `16:9`: Paisagem widescreen (padrão)
  * `4:3`: Paisagem 4:3
  * `1:1`: Quadrado
  * `3:4`: Retrato 3:4
  * `9:16`: Retrato vertical
  * `2:3`: Retrato 2:3
  * `3:2`: Paisagem 3:2
  * `21:9`: Cinema widescreen
</ParamField>

<ParamField body="seed" type="integer" default="0">
  Semente aleatória, faixa `0–2147483647`. Mesmo prompt e seed reproduzem resultados similares.
</ParamField>

<ParamField body="negative_prompt" type="string">
  Prompt negativo para excluir conteúdo indesejado. Até 2048 caracteres.
</ParamField>

<ParamField body="audio" type="boolean" default="false">
  Indica se uma trilha de áudio deve ser gerada.

  * `true`: Gerar áudio (aumenta o preço)
  * `false`: Sem áudio (padrão)
</ParamField>

<ParamField body="watermark" type="boolean" default="false">
  Indica se uma marca d'água deve ser adicionada no canto inferior direito do vídeo.

  * `true`: Adicionar marca d'água
  * `false`: Sem marca d'água (padrão)
</ParamField>

<ParamField body="motion_mode" type="string">
  Modo de movimento.

  * `normal`: Modo padrão (`pixverse-v6` suporta apenas este valor)

  <Warning>
    `fast` aplica-se apenas a modelos legados e será rejeitado pelo upstream para `pixverse-v6`.
  </Warning>
</ParamField>

<ParamField body="generate_multi_clip_switch" type="boolean" default="false">
  Indica se um vídeo contínuo de múltiplos clipes deve ser gerado. Suportado apenas em texto-para-vídeo e imagem-para-vídeo.

  * `true`: Gerar vídeo contínuo de múltiplos clipes
  * `false`: Clipe único (padrão)
</ParamField>

<ParamField body="image_urls" type="array<url>">
  Array de URLs de imagens de entrada para imagem-para-vídeo. Apenas a primeira é usada.

  As imagens devem ser URLs HTTP/HTTPS publicamente acessíveis.
</ParamField>

<ParamField body="first_frame_image" type="url">
  URL do primeiro frame no modo de transição. Deve ser fornecido junto com `last_frame_image`.
</ParamField>

<ParamField body="last_frame_image" type="url">
  URL do último frame no modo de transição. Deve ser fornecido junto com `first_frame_image`.
</ParamField>

<ParamField body="img_references" type="array<url>">
  Array de URLs de imagens de referência para o modo de fusão de múltiplas referências. Suporta 1–7 imagens.

  Fornecer este campo aciona o modo de fusão de múltiplas imagens de referência.
</ParamField>

<ParamField body="extend_from_task_id" type="string">
  ID da tarefa de origem para extensão de vídeo. Fornecer este campo aciona o modo de extensão.

  A tarefa de origem deve pertencer ao usuário atual, usar o modelo `pixverse-v6` e ter status `completed`.
</ParamField>

## Modos de geração

O adaptador despacha automaticamente para o modo de geração correspondente conforme os campos da requisição. A correspondência segue a ordem de prioridade; o primeiro a corresponder vence.

| Modo                            | Condição de ativação                            | Descrição                                          |
| ------------------------------- | ----------------------------------------------- | -------------------------------------------------- |
| Texto-para-vídeo                | Sem campos de imagem ou extensão                | Gera vídeo a partir do `prompt`                    |
| Imagem-para-vídeo               | `image_urls` com uma imagem                     | Usa a primeira imagem como entrada                 |
| Transição primeiro/último frame | `first_frame_image` e `last_frame_image` juntos | Gera transição suave entre dois frames             |
| Fusão de múltiplas referências  | Array `img_references` fornecido                | Funde 1–7 imagens de referência em um vídeo        |
| Extensão de vídeo               | `extend_from_task_id` fornecido                 | Continua a partir de uma tarefa Pixverse concluída |

<Warning>
  Todas as entradas de imagem aceitam apenas URLs HTTP/HTTPS publicamente acessíveis. base64 e Data URI não são suportados. Se você só tiver imagens locais, faça o upload para um object storage e forneça a URL.
</Warning>

## Regras de parâmetros

| Limite                         | Descrição                                                                                     |
| ------------------------------ | --------------------------------------------------------------------------------------------- |
| Duração                        | `1 ≤ duration ≤ 15` segundos; modo de transição apenas `5` ou `8` segundos                    |
| Resolução                      | Apenas `360p`, `540p`, `720p`, `1080p` são suportadas                                         |
| Proporção                      | `size` é efetivo apenas em texto-para-vídeo e fusão de múltiplas referências                  |
| Tamanho do prompt              | `prompt` até 5000 caracteres, `negative_prompt` até 2048 caracteres                           |
| Imagem-para-vídeo              | `image_urls` usa apenas a primeira imagem                                                     |
| Transição                      | `first_frame_image` e `last_frame_image` devem ser enviados juntos                            |
| Modo de movimento              | `pixverse-v6` suporta apenas `normal`                                                         |
| Fusão de múltiplas referências | `img_references` suporta 1–7 imagens                                                          |
| Extensão de vídeo              | `extend_from_task_id` deve apontar para uma tarefa `pixverse-v6` `completed` do usuário atual |

## Resposta

<ResponseField name="code" type="integer">
  Código de status da resposta. `200` em caso de sucesso.
</ResponseField>

<ResponseField name="data" type="array">
  Array de tarefas retornado.

  <Expandable title="Elemento do array">
    <ResponseField name="status" type="string">
      Status inicial da tarefa. `submitted` após envio bem-sucedido.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      Identificador único da tarefa para consultar status e resultado.
    </ResponseField>
  </Expandable>
</ResponseField>

## Consulta do resultado da tarefa

A geração de vídeo é uma tarefa assíncrona. Após o envio, um `task_id` é retornado. Use o endpoint [Obter status da tarefa](/pt/api-reference/tasks/status) para consultar progresso e resultado.

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

Recomenda-se fazer polling a cada 5 segundos até o status ficar `completed` ou `failed`.

### Exemplo de sucesso

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KSPX48B8V1M6C2ZN0D0T4BKB",
    "status": "completed",
    "progress": 100,
    "cost": 0.2,
    "credits_cost": 2,
    "created": 1779958948,
    "completed": 1779958999,
    "estimated_time": 100,
    "actual_time": 51,
    "result": {
      "videos": [
        {
          "url": ["https://upload.apimart.ai/f/video/xxxx.mp4"],
          "expires_at": 1780045399
        }
      ]
    }
  }
}
```

A URL do vídeo está em `data.result.videos[0].url[0]`. O campo `url` é, ele mesmo, um array. Os links de vídeo geralmente expiram após 24 horas — baixe ou transfira-os a tempo.

### Exemplo de falha

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KSPX48B8V1M6C2ZN0D0T4BKB",
    "status": "failed",
    "progress": 100,
    "cost": 0,
    "credits_cost": 0,
    "created": 1779958948,
    "completed": 1779958960,
    "error": {
      "code": "task_failed",
      "message": "pixverse error 400063: moderation failed",
      "type": "task_failed"
    }
  }
}
```

Em caso de falha, `cost` geralmente é `0`. A causa do erro está em `data.error.message`.

## Casos de uso

### Caso 1: Texto-para-vídeo

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "A neon-lit alley in Tokyo at night, light rain, anamorphic lens flare",
  "size": "21:9",
  "resolution": "720p",
  "duration": 8,
  "seed": 42,
  "audio": true
}
```

### Caso 2: Imagem-para-vídeo

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "Camera slowly zooms in, gentle wind moves the leaves",
  "image_urls": ["https://example.com/first-frame.jpg"],
  "resolution": "540p",
  "duration": 5
}
```

### Caso 3: Transição primeiro/último frame

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "transform smoothly from a puppy to a cat",
  "first_frame_image": "https://example.com/puppy.jpg",
  "last_frame_image": "https://example.com/cat.jpg",
  "resolution": "540p",
  "duration": 5,
  "motion_mode": "normal"
}
```

### Caso 4: Fusão de múltiplas referências

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "A girl wearing the outfit from image 2, holding the cat from image 3",
  "img_references": [
    "https://example.com/character.jpg",
    "https://example.com/outfit.jpg",
    "https://example.com/cat.jpg"
  ],
  "size": "9:16",
  "resolution": "720p",
  "duration": 5
}
```

### Caso 5: Extensão de vídeo

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "the character now walks into a forest",
  "extend_from_task_id": "task_01JWXXXXXXXXXXXX",
  "resolution": "540p",
  "duration": 5
}
```