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

> Gere e edite vídeos com texto, quadros e referências de imagem/vídeo/áudio: 480p–4k, imagem do último quadro, MOV e geração de rascunho para vídeo final.

> [!NOTE]
>
> Esta API é assíncrona. Após o envio, leia `data[0].task_id` e consulte o [status da tarefa](https://docs.apimart.ai/pt/api-reference/tasks/status.md). A geração costuma levar de 1 a 3 minutos; consulte a cada 5–10 segundos. O tempo real depende da tarefa.

```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": "apimart-zoe",
    "prompt": "Um gatinho laranja no parapeito olha para a câmera, com luz solar lateral e um movimento lento de aproximação",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 8,
    "audio": true,
    "nsfw_check": true,
    "return_last_frame": true
  }'
```

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

response = requests.post(
    "https://api.apimart.ai/v1/videos/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "apimart-zoe",
        "prompt": "Um gatinho laranja no parapeito olha para a câmera, com luz solar lateral e um movimento lento de aproximação",
        "resolution": "1080p",
        "aspect_ratio": "16:9",
        "duration": 8,
        "audio": True,
        "nsfw_check": True,
        "return_last_frame": True
    }
)
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": "apimart-zoe",
    "prompt": "Um gatinho laranja no parapeito olha para a câmera, com luz solar lateral e um movimento lento de aproximação",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 8,
    "audio": true,
    "nsfw_check": true,
    "return_last_frame": true
  })
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

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

## Escolha do modo

| Modo | Parâmetros |
| - | - |
| Texto para vídeo | Envie `prompt` sem mídia. |
| Quadros para vídeo | Use os papéis `first_frame` e, opcionalmente, `last_frame` em `image_with_roles`, ou `first_frame_image` / `last_frame_image`. |
| Referências para vídeo | Imagens ou vídeos de referência, opcionalmente com áudio. Áudio sozinho não é aceito. |
| Rascunho | `draft: true` produz saída em `480p`. |
| Vídeo final | Use o `draft_task_id` de um rascunho concluído com sucesso para saída em `1080p`. |
| Edição de vídeo | Use `omni_reference_task_type: "edit"` e ao menos um vídeo de origem. Duração e proporção seguem a origem. |

## Cabeçalhos

**Authorization** `string` *required*

Autenticação Bearer: `Bearer <token>`, em que `<token>` é sua chave API APIMart. Envie o corpo com `Content-Type: application/json`.

## Parâmetros da requisição

**model** `string` *required*

Valor fixo: `apimart-zoe`.

**prompt** `string`

Até 204.800 caracteres. Obrigatório para texto para vídeo; opcional ao enviar apenas mídia. Proibido com `draft_task_id`: o vídeo final herda o prompt do rascunho.

**resolution** `string`

`480p`, `720p`, `1080p`, `2k`, `4k`, sem diferenciar maiúsculas e minúsculas. Padrão na geração normal: `720p`. Com `draft: true`, apenas `480p`, inclusive se omitido. Com `draft_task_id`, apenas `1080p`, inclusive se omitido.

**aspect\_ratio** `string`

`21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `adaptive`. Padrão: `adaptive`, definido pelo modelo ou pela mídia. Omita no vídeo final, que herda a proporção do rascunho.

Na edição (`edit`), omita o campo ou use `adaptive` para seguir a origem.

**size** `string`

Outro nome para `aspect_ratio`, com os mesmos valores. Prefira enviar apenas um dos campos. Omita no vídeo final.

**duration** `integer`

Geração normal: Segundos inteiros de `4` a `30`, padrão `5`. A duração solicitada ou padrão é cobrada sem ajuste pela duração do resultado. Com `-1`, o modelo decide: reserva de 30 segundos e ajuste pela duração real arredondada ao segundo inteiro mais próximo (0.5 para cima). Omita no vídeo final, que herda a duração do rascunho.

Na edição (`edit`), omita o campo ou use `-1`. Omitir equivale a `-1`; a duração segue o vídeo de origem.

**seconds** `integer`

Alias de `duration`, com as mesmas regras. Use apenas um dos campos. Omita no vídeo final.

**audio** `boolean`

Booleano que controla a geração de áudio junto com o vídeo. Alias: `generate_audio`. Se omitido, o modelo decide. Proibido no vídeo final. Controla o áudio de saída, não as referências de entrada em `audio_urls`.

Se enviar `audio` e `generate_audio`, os valores devem ser iguais; caso contrário, HTTP 400. Quando omitidos, o modelo decide e normalmente inclui som.

**generate\_audio** `boolean`

Alias de `audio`, com as mesmas regras. Use apenas um dos campos; omita no vídeo final.

Se enviar `audio` e `generate_audio`, os valores devem ser iguais; caso contrário, HTTP 400. Quando omitidos, o modelo decide e normalmente inclui som.

**seed** `integer`

Semente aleatória inteira. Proibida no vídeo final.

**nsfw\_check** `boolean`

A moderação fica desativada por padrão; use `true` para ativar.

Booleano opcional. `true` ativa a moderação de `prompt`, `image_urls`, `image_with_roles`, quadros inicial/final e imagens `asset://`. Vídeos e áudios de referência não são moderados.

A requisição final não contém prompt nem mídia. No fluxo rascunho → vídeo final, a moderação ocorre na geração do rascunho.

Uma detecção retorna HTTP 400 (`nsfw_content_detected`), com categorias em `error.message`. Exiba como recusa de moderação, não como erro genérico de parâmetros. Se o serviço de moderação falhar ou ficar indisponível, a geração continua; ativar o parâmetro não garante que toda requisição conclua a moderação.

**omni\_reference\_task\_type** `string`

Aceita `auto` (padrão, equivale a omitir; o modelo decide), `reference` e `edit`. `reference` / `edit` exigem mídia de referência; texto puro ou quadros inicial/final retornam HTTP 400 com esses valores. `edit` exige ao menos um item em `video_urls` e não permite `draft: true`. `extend` não está disponível e retorna HTTP 400. Omita na geração final.

**return\_last\_frame** `boolean`

Com `true`, retorna também o último quadro em PNG em `data.result.last_frame_url`. Desativado por padrão. Omita na geração final.

**output\_format** `string`

`mp4` (padrão) ou `mov` (contêiner QuickTime); outros valores retornam HTTP 400. Alias: `response_format`. Se ambos forem enviados, `output_format` prevalece. Omita na geração final.

**response\_format** `string`

Alias de `output_format`, aceita `mp4` / `mov`. Se ambos forem enviados, `output_format` prevalece. Omita na geração final.

**enhance\_prompt** `boolean`

Com `true`, otimiza automaticamente o prompt antes da geração. Por padrão, usa o prompt original sem otimização. Omita na geração final.

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

Cada item contém `url` e `role`. Papéis: `first_frame` (inicial), `last_frame` (final), `reference_image` (referência). No máximo um quadro inicial e um final; o final exige o inicial. Esses quadros não podem ser combinados com mídia de referência.

Não envie `image_urls` e `image_with_roles` juntos. Isso retorna HTTP 400 (`invalid_request_error`) no envio, sem cobrança. Os aliases `image`, `images` e `image_url` contam como `image_urls` e não contornam essa restrição.

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

Até 30 imagens de referência. Veja abaixo os requisitos de formato, dimensões e tamanho de arquivo.

Não envie `image_urls` e `image_with_roles` juntos. Isso retorna HTTP 400 (`invalid_request_error`) no envio, sem cobrança. Os aliases `image`, `images` e `image_url` contam como `image_urls` e não contornam essa restrição.

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

Endereço do quadro inicial, equivalente a `first_frame` em `image_with_roles`.

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

Endereço do quadro final, equivalente a `last_frame` em `image_with_roles`. Exige também um quadro inicial.

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

Até 10 vídeos de referência. URL `http(s)` pública ou `asset://<ID da mídia>`, sem `data:` Base64. Dimensões, duração exata e taxa de quadros são verificadas no envio pelas regras abaixo.

Para cobrança, as durações são somadas e só então arredondadas para baixo em segundos inteiros, sem ajuste posterior. Esse arredondamento não valida a duração individual dos vídeos. Falha de acesso ou medição da duração retorna HTTP 400 (`input_video_probe_failed`), sem cobrança.

`auto` / `reference`: 2–15 segundos, faixa aceita `1.8 ≤ t ≤ 15.2`. Origens para `edit`: 4–30 segundos, faixa aceita `3.8 ≤ t < 30.2`. Valide a duração exata, sem arredondar antes.

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

Até 10; WAV / MP3; cada um com 2–15 segundos e `≤ 15 MB`, até 30 segundos no total. Tolerância de ±0.2 segundo: `1.8 ≤ t ≤ 15.2` por clipe e total `≤ 30.2`. Exige imagem ou vídeo de referência.

URL pública `http(s)` ou `asset://<ID da mídia>`, sem `data:` Base64. A duração do áudio é validada no envio; valores inválidos retornam HTTP 400 síncrono sem cobrança.

**draft** `boolean`

`true` gera um rascunho em `480p`. Os demais parâmetros seguem as regras normais. Não envie este campo na geração final.

A edição de vídeo (`edit`) não permite rascunhos.

**draft\_task\_id** `string`

`task_id` de um rascunho bem-sucedido para gerar o vídeo final em `1080p`. Use em até 24 horas após a criação do rascunho. Prompt, mídia, duração e proporção são herdados e não podem ser reenviados. O vídeo final também proíbe `seed`, `audio` e seu alias `generate_audio`.

## Endereços e limites de mídia

Imagens, vídeos e áudios aceitam URLs públicas `http(s)` ou mídias APIMart `asset://<ID da mídia>`. Nenhum aceita `data:` Base64; envie a mídia antes. O registro é automático, sem chamada API adicional. Se falhar, a tarefa falha e a cobrança é devolvida.

| Mídia | Requisitos |
| - | - |
| Imagens de referência | Até 30; JPEG / PNG / WebP / BMP / TIFF / GIF / HEIC / HEIF; proporção 0.4–2.5; largura e altura entre 300–6000 pixels cada; cada uma `< 30 MB`. |
| Vídeos de referência | Até 10; MP4 / MOV (H.264 / H.265; faixa de áudio: AAC / MP3); cada um `≤ 200 MB`. Veja abaixo as regras de dimensões, duração e taxa de quadros. |
| Áudios de referência | Até 10; WAV / MP3; cada um com 2–15 segundos e `≤ 15 MB`, até 30 segundos no total. Tolerância de ±0.2 segundo: `1.8 ≤ t ≤ 15.2` por clipe e total `≤ 30.2`. Exige imagem ou vídeo de referência. |

### Validação dos vídeos de referência

| Propriedade | Requisito |
| - | - |
| Largura e altura | Largura e altura de 300–6000 pixels cada. |
| Área em pixels (largura × altura) | 409.600–8.295.044 pixels. |
| Proporção (largura / altura) | 0.4–2.5. |
| Duração por vídeo | `auto` / `reference`: 2–15 segundos, faixa aceita `1.8 ≤ t ≤ 15.2`. Origens para `edit`: 4–30 segundos, faixa aceita `3.8 ≤ t < 30.2`. Valide a duração exata, sem arredondar antes. |
| Taxa de quadros | Arredonde ao inteiro mais próximo (0.5 para cima), depois verifique 24–60fps. 23.976 e 59.94 são aceitos. |

Dimensões, área em pixels, proporção, duração exata e fps do vídeo, além da duração do áudio de referência, são validados no envio. Violações retornam HTTP 400 síncrono sem cobrança. Erros de vídeo usam `invalid_request_error` com medidas reais. Verifique a área, não lado menor mínimo de 480 e maior máximo de 4096.

Considerando só as dimensões, 420×1000 (420.000 pixels) é válido. 720×480 (345.600 pixels), 848×480 (407.040 pixels) e 4096×2160 (8.847.360 pixels) violam os limites de área. Duração, taxa de quadros e demais requisitos também devem ser atendidos.

Dimensões das imagens, tamanho de arquivo e codificação são verificados durante a geração. Mídia inválida causa falha com reembolso automático. Verifique essas propriedades antes da chamada quando possível.

### Regras de combinação de mídias

* Não envie `image_urls` e `image_with_roles` juntos. Isso retorna HTTP 400 (`invalid_request_error`) no envio, sem cobrança. Os aliases `image`, `images` e `image_url` contam como `image_urls` e não contornam essa restrição.
* Quadros inicial/final não podem estar na mesma requisição que imagens, vídeos ou áudios de referência.
* No máximo um quadro inicial e um final. O quadro final exige o inicial.
* Até 30 imagens, 10 vídeos e 10 áudios de referência, com no máximo 50 mídias no total.
* Violar essas combinações ou quantidades retorna HTTP 400 de forma síncrona, sem cobrança.
* `omni_reference_task_type: "edit"` exige ao menos um vídeo de origem (`3.8 ≤ t < 30.2` segundos). `duration` / `seconds`: omitir ou `-1`; `aspect_ratio` / `size`: omitir ou `adaptive`. Não combinar com `draft: true`. Auto/reference mantêm o limite de 2–15 segundos e sua tolerância.

> [!WARNING]
>
> Estes campos retornam HTTP 400 sempre que presentes, mesmo com `""`, `[]`, `false` ou `null`; remova-os por completo: `negative_prompt`, `camera_fixed`, `camerafixed`, `extend_from_task_id`, `mask_url`, `video_list`, `element_list`, `multi_shot`, `tools`. Omita `n` ou use `1`.

## Exemplos de requisição

As URLs abaixo são ilustrativas. Substitua por endereços de mídia acessíveis.

### Quadros inicial e final

```json theme={null}
{
  "model": "apimart-zoe",
  "prompt": "Transição natural do primeiro ao último quadro, mantendo a iluminação consistente",
  "image_with_roles": [
    {
      "url": "https://example.com/start.jpg",
      "role": "first_frame"
    },
    {
      "url": "https://example.com/end.jpg",
      "role": "last_frame"
    }
  ],
  "duration": 6
}
```

Também é possível usar `first_frame_image` e `last_frame_image`. Não adicione imagens, vídeos ou áudios de referência à mesma requisição.

### Referências de imagem, vídeo e áudio

```json theme={null}
{
  "model": "apimart-zoe",
  "prompt": "O personagem da imagem de referência se move naturalmente na cena do vídeo, com música acompanhando o ritmo visual",
  "image_urls": [
    "https://example.com/character.jpg"
  ],
  "video_urls": [
    "https://example.com/scene.mp4"
  ],
  "audio_urls": [
    "https://example.com/bgm.mp3"
  ],
  "duration": -1
}
```

As imagens em `image_urls` são referências. Com `duration: -1`, o modelo define a duração da saída.

### Edição de vídeo

`omni_reference_task_type: "edit"` exige ao menos um vídeo de origem (`3.8 ≤ t < 30.2` segundos). `duration` / `seconds`: omitir ou `-1`; `aspect_ratio` / `size`: omitir ou `adaptive`. Não combinar com `draft: true`. Auto/reference mantêm o limite de 2–15 segundos e sua tolerância.

```json theme={null}
{
  "model": "apimart-zoe",
  "prompt": "Transforme toda a cena em um filme clássico em preto e branco, mantendo o movimento da câmera e a composição",
  "video_urls": [
    "https://example.com/source_20s.mp4"
  ],
  "omni_reference_task_type": "edit"
}
```

A edição usa a tarifa com vídeo de referência. Reserva 30 segundos de saída e depois ajusta pela duração real arredondada ao segundo inteiro, incluindo a duração de referência conforme a fórmula abaixo.

### Último quadro, saída MOV e otimização do prompt

```json theme={null}
{
  "model": "apimart-zoe",
  "prompt": "Um gatinho laranja no parapeito olha para a câmera, com luz solar lateral e um movimento lento de aproximação",
  "duration": 5,
  "return_last_frame": true,
  "output_format": "mov",
  "enhance_prompt": true
}
```

## Rascunho → vídeo final

1. Envie o rascunho com `draft: true`. Se `resolution` for omitido, usa-se `480p`; se informado, também só pode ser `480p`.

```json theme={null}
{
  "model": "apimart-zoe",
  "prompt": "Um gatinho laranja no parapeito olha para a câmera, com luz solar lateral e um movimento lento de aproximação",
  "draft": true
}
```

2. Aguarde o sucesso do rascunho e use seu `task_id` para gerar o vídeo final. Bastam `model` e `draft_task_id`. Se informar `resolution`, use apenas `1080p`.

```json theme={null}
{
  "model": "apimart-zoe",
  "draft_task_id": "task_01KZOEEXAMPLE"
}
```

> [!WARNING]
>
> O vídeo final herda prompt, mídias, duração, proporção, seed e áudio do rascunho. Envie `model`, `draft_task_id`, opcionalmente `resolution: "1080p"` e campos comuns como `nsfw_check` / `webhook`. Os campos de geração a seguir devem estar ausentes; strings/arrays vazios, `false` e `null` também retornam HTTP 400: `prompt`, `image_urls`, `image_with_roles`, `image`, `images`, `image_url`, `first_frame_image`, `last_frame_image`, `video_urls`, `audio_urls`, `duration`, `seconds`, `aspect_ratio`, `size`, `seed`, `audio`, `generate_audio`, `draft`, `omni_reference_task_type`, `return_last_frame`, `output_format`, `response_format`, `enhance_prompt`. Use o rascunho em até 24 horas da criação; as duas gerações são cobradas separadamente.

## Consulta de tarefas e resultados

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

No envio, `data` é um array; na consulta, é um objeto de tarefa. `data.status`: `pending` = na fila, `processing` = gerando, `completed` = sucesso, `failed` = falha. Em caso de sucesso, leia o endereço no array `data.result.videos[].url`, por exemplo `data.result.videos[0].url[0]`. Os vídeos são copiados para o armazenamento APIMart. Abaixo estão apenas os campos principais de uma consulta bem-sucedida.

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KZOEEXAMPLE",
    "status": "completed",
    "result": {
      "videos": [
        {
          "url": [
            "https://example.com/generated-video.mp4"
          ],
          "expires_at": 1794475442
        }
      ],
      "last_frame_url": "https://example.com/generated-last-frame.png"
    },
    "progress": 100,
    "completed": 1794389042
  }
}
```

Em caso de falha, leia o motivo em `data.error.message`. Os valores cobrados são reembolsados automaticamente.

| Campo | Descrição |
| - | - |
| `data.progress` | Progresso da tarefa, 0–100. |
| `data.result.videos[].url` | Array de endereços de vídeo copiados para o armazenamento APIMart. |
| `data.result.videos[].expires_at` | O endereço expira 24 horas após a conclusão. Baixe o vídeo assim que possível. |
| `data.result.last_frame_url` | URL PNG do último quadro armazenado no APIMart. Presente somente em tarefas bem-sucedidas cuja solicitação incluiu `return_last_frame: true`. |
| `data.error.message` | Motivo da falha, apenas em `failed`. |
| `data.error.code` | String `task_failed` em caso de falha. |
| `data.cost` | Custo da tarefa; 0 para tarefas com falha após o reembolso da reserva. |

## Regras de cobrança

Cobrança por segundo conforme a resolução e o uso de vídeos de referência. Tarifas e descontos na [página de preços](https://apimart.ai/pricing). `D` é a duração de saída usada na cobrança, em segundos.

| Caso | Duração de saída cobrada D |
| - | - |
| Geração normal: `duration: 4–30` ou omitido (padrão 5) | Cobrança dos segundos solicitados, sem ajuste pela duração do vídeo pronto. |
| `duration: -1` / edição de vídeo `edit` | Reserva de 30 segundos, depois ajuste pela duração real arredondada ao segundo inteiro mais próximo (0.5 para cima). |
| Vídeo final | Herda a duração do rascunho. Se ele usou `duration: -1`, a duração real do rascunho serve de base, sem novo ajuste pela duração do vídeo final. |

* Duração total dos vídeos de referência `R`: verificar cada duração no envio, somar e arredondar a soma para baixo em segundos inteiros. Sem ajuste posterior.
* Sem vídeo de referência: segundos cobrados = `D`. Com referência: `D + max(R, ceil(D × 2/3))`. `ceil` arredonda para cima. Aplica-se a tarifa com vídeo de referência.
* Exemplo: solicitar 8 segundos mantém `D = 8`, mesmo com resultado de 8.2 segundos. Duração automática de 8.5 resulta em `D = 9`. Referências de 2.8 e 3.8 segundos somam 6.6 antes do arredondamento para baixo: `R = 6`.
* Rascunho (`480p`) e vídeo final (`1080p`) são cobrados separadamente. Referências do rascunho também entram com a duração original no vídeo final, sem novo upload.
* Envios com falha não são cobrados. Tarefas com falha são reembolsadas automaticamente.

## Erros comuns

Falhas no envio retornam um objeto `error`: detalhes em `error.message` e código string em `error.code`, diferente do status HTTP. Não há cobrança.

| HTTP | `error.code` | Causa e solução |
| - | - | - |
| 400 | `invalid_request_error` | Verifique duração, resolução, proporção, quantidade/combinação de mídia, parâmetros não aceitos e regras de rascunho/final. Também ocorre se `draft_task_id` não existir, não for rascunho, estiver incompleto ou tiver mais de 24 horas. Também cobre dimensões, duração exata ou taxa de quadros inválidas e a combinação de `image_urls` (incluindo aliases) com `image_with_roles`. Erros de vídeo incluem as medidas reais. Confira também duração do áudio, tipo de tarefa/regras de edição, `output_format`, igualdade dos aliases de áudio e presença de campos proibidos. |
| 400 | `nsfw_content_detected` | Recusa de moderação. Categorias em `error.message`. Exiba a recusa e ajuste o conteúdo antes de reenviar. Sem cobrança. |
| 400 | `input_video_probe_failed` | Vídeo de referência inacessível ou duração não detectável. Verifique endereço e conteúdo. |
| 402 | `payment_required` | Saldo insuficiente; duração automática reserva 30 segundos. |
| 503 | `draft_channel_unavailable` / `draft_task_unavailable` | Canal do rascunho indisponível ou consulta temporariamente falhou. Tente mais tarde ou gere novo rascunho. |


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