# Referência de API

## Autenticação

Use sua API key de [Settings > API Keys](https://renderingvideo.com/settings/apikeys). As solicitações acessam apenas os recursos dessa conta.

Formatos suportados:

| Método          | Formato                        |
| --------------- | ------------------------------ |
| Bearer Token    | `Authorization: Bearer sk-xxx` |
| Token Header    | `Authorization: Token sk-xxx`  |
| X-API-Key       | `X-API-Key: sk-xxx`            |
| Query Parameter | `?api_key=sk-xxx`              |

Lembretes de segurança:

- nunca exponha sua API key em código cliente
- faça sempre as chamadas da API a partir do servidor

---

## Visão geral dos endpoints

| Método | Endpoint                          | Uso                                    |
| ------ | --------------------------------- | -------------------------------------- |
| POST   | `/api/v1/video`                   | Criar uma tarefa permanente de vídeo   |
| GET    | `/api/v1/video`                   | Listar tarefas de vídeo                |
| GET    | `/api/v1/video/:taskId`           | Ler detalhes de uma tarefa             |
| DELETE | `/api/v1/video/:taskId`           | Excluir uma tarefa de vídeo            |
| POST   | `/api/v1/video/:taskId/render`    | Disparar renderização                  |
| POST   | `/api/v1/upload`                  | Enviar assets                          |
| GET    | `/api/v1/files`                   | Listar arquivos                        |
| DELETE | `/api/v1/files/:fileId`           | Excluir um arquivo                     |
| GET    | `/api/v1/credits`                 | Consultar saldo de créditos            |
| POST   | `/api/v1/preview`                 | Criar preview temporária               |
| GET    | `/api/v1/preview/:tempId`         | Ler configuração da preview            |
| DELETE | `/api/v1/preview/:tempId`         | Excluir preview                        |
| POST   | `/api/v1/preview/:tempId/convert` | Converter preview em tarefa permanente |
| POST   | `/api/v1/preview/:tempId/render`  | Converter preview e renderizar         |

---

## POST /api/v1/video

Cria uma tarefa permanente de vídeo a partir da sua configuração. Esta operação ainda não inicia a renderização.

Campos importantes:

| Campo      | Tipo   | Obrigatório | Descrição                                                 |
| ---------- | ------ | ----------- | --------------------------------------------------------- |
| `config`   | object | Sim         | Schema de vídeo conforme o [JSON Schema](https://renderingvideo.com/docs/json-spec.md) |
| `metadata` | object | Não         | Metadados personalizados anexados à tarefa                |

Campos de resposta mais úteis:

- `taskId`
- `videoTaskId`
- `previewUrl`
- `viewerUrl`
- `configUrl`
- `status`
- `quality`
- `width`
- `height`
- `duration`

---

## GET /api/v1/video

Lista todas as tarefas de vídeo da conta atual.

Parâmetros de query:

| Parâmetro | Tipo    | Padrão | Descrição                       |
| --------- | ------- | ------ | ------------------------------- |
| `page`    | integer | 1      | Número da página                |
| `limit`   | integer | 20     | Itens por página, máximo 100    |
| `status`  | string  | -      | Filtra pelo status mais recente |

A resposta contém uma lista `tasks` e um objeto `pagination`.

---

## GET /api/v1/video/:taskId

Recupera os detalhes completos de uma tarefa específica de vídeo.

Campos de retorno úteis:

- `taskId`
- `videoTaskId`
- `status`
- `videoUrl`
- `previewUrl`
- `viewerUrl`
- `configUrl`
- `costCredits`
- `createdAt`
- `completedAt`
- `metadata`

Valores de status:

| Status      | Significado                              |
| ----------- | ---------------------------------------- |
| `created`   | Tarefa criada, render ainda não iniciado |
| `rendering` | Renderização em andamento                |
| `completed` | Render concluído com sucesso             |
| `failed`    | Falha no render                          |

---

## DELETE /api/v1/video/:taskId

Exclui permanentemente uma tarefa e os registros locais de render associados. A API também tenta excluir a tarefa remota upstream.

Campos de resposta importantes:

- `deleted`
- `remoteDeleted`
- `message`

Se a exclusão upstream falhar, a exclusão local ainda pode ter sido concluída corretamente.

---

## POST /api/v1/video/:taskId/render

Inicia ou reinicia a renderização de uma tarefa existente.

Corpo da requisição:

| Campo         | Tipo    | Obrigatório | Padrão | Descrição                         |
| ------------- | ------- | ----------- | ------ | --------------------------------- |
| `webhook_url` | string  | Não         | -      | URL para notificação de conclusão |
| `num_workers` | integer | Não         | 5      | Número de workers de renderização |

Resultados possíveis:

- uma nova renderização com `status: rendering`
- uma resposta reaproveitando um render já concluído com `alreadyRendered: true`

Erros frequentes:

- `NOT_FOUND`
- `ALREADY_RENDERING`
- `INSUFFICIENT_CREDITS`
- `RENDER_TRIGGER_FAILED`

---

## Webhooks

`webhook_url` é suportado em:

- `POST /api/v1/video/:taskId/render`
- `POST /api/v1/preview/:tempId/render`

Fluxo de funcionamento:

1. sua `webhook_url` é salva junto da tarefa de render
2. o renderer upstream retorna `completed` ou `failed`
3. o projeto atualiza primeiro o banco local
4. em seguida envia um `POST` para a sua `webhook_url`

O payload reenviado normalmente inclui:

- `taskId`
- `renderTaskId`
- `status`
- `videoUrl`
- `error`
- `timestamp`

Limitações atuais:

- apenas `completed` e `failed` são reenviados
- `webhook_url` precisa ser uma URL absoluta válida
- ainda não existe assinatura de webhook
- ainda não existe fila de retry nem log de entrega

---

## POST /api/v1/upload

Permite enviar imagens, vídeos e áudios para uso posterior em configurações de vídeo.

Campos do formulário:

| Campo   | Tipo   | Obrigatório | Descrição       |
| ------- | ------ | ----------- | --------------- |
| `file`  | File   | Não\*       | Arquivo único   |
| `files` | File[] | Não\*       | Vários arquivos |

\*Pelo menos um entre `file` ou `files` é obrigatório.

Famílias MIME suportadas:

- `image/*`
- `video/*`
- `audio/*`

Limites de armazenamento por plano:

| Plano    | Limite |
| -------- | ------ |
| Free     | 512 MB |
| Starter  | 10 GB  |
| Standard | 20 GB  |
| Pro      | 50 GB  |

A resposta de sucesso inclui `count` e uma lista `assets`.

---

## GET /api/v1/files

Lista os arquivos enviados para o proprietário atual da API key.

Parâmetros de query:

| Parâmetro | Tipo    | Padrão | Descrição                   |
| --------- | ------- | ------ | --------------------------- |
| `page`    | integer | 1      | Número da página            |
| `limit`   | integer | 20     | Itens por página            |
| `type`    | string  | -      | `image`, `video` ou `audio` |

A resposta inclui `files` e `pagination`.

---

## DELETE /api/v1/files/:fileId

Exclui permanentemente um arquivo da biblioteca. Tanto o objeto armazenado quanto o registro do arquivo são removidos.

Campos de resposta úteis:

- `fileId`
- `deleted`
- `message`

---

## GET /api/v1/credits

Recupera o saldo atual de créditos da conta.

Resposta típica:

```json
{
  "success": true,
  "credits": 985,
  "currency": "credits"
}
```

---

## POST /api/v1/preview

Cria uma preview temporária sem consumir créditos.

Regras importantes:

- o schema completo do vídeo é enviado diretamente no body
- links de preview duram **7 dias**
- a preview **não** consome créditos
- a preview **não** gera arquivo de vídeo para download

Campos de resposta:

- `tempId`
- `previewUrl`
- `viewerUrl`
- `expiresIn`

---

## GET /api/v1/preview/:tempId

Lê a configuração por trás de um link temporário de preview.

Campos de retorno:

- `tempId`
- `config`

---

## DELETE /api/v1/preview/:tempId

Exclui um link temporário de preview.

Campos de retorno:

- `tempId`
- `deleted`
- `message`

---

## POST /api/v1/preview/:tempId/convert

Clona uma preview temporária em uma tarefa permanente de vídeo. A preview temporária continua disponível.

Corpo opcional:

| Campo      | Tipo   | Obrigatório | Descrição                         |
| ---------- | ------ | ----------- | --------------------------------- |
| `category` | string | Não         | Categoria associada à nova tarefa |

Campos de retorno mais úteis:

- `converted`
- `taskId`
- `videoTaskId`
- `previewUrl`
- `viewerUrl`
- `configUrl`

---

## POST /api/v1/preview/:tempId/render

Clona uma preview temporária em uma tarefa permanente e dispara imediatamente a renderização.

Corpo da requisição:

| Campo         | Tipo    | Obrigatório | Padrão | Descrição                          |
| ------------- | ------- | ----------- | ------ | ---------------------------------- |
| `category`    | string  | Não         | `api`  | Categoria da nova tarefa           |
| `webhook_url` | string  | Não         | -      | Webhook para o resultado do render |
| `num_workers` | integer | Não         | 5      | Número de workers de renderização  |

Resposta de sucesso típica:

- `converted: true`
- `taskId`
- `renderTaskId`
- `status: rendering`
- `cost`
- `remainingCredits`
- `previewUrl`
- `viewerUrl`

---

## Cálculo de créditos

A regra de custo é:

- **custo = duração do vídeo em segundos × multiplicador de qualidade**

| Qualidade | Lado curto   | Multiplicador |
| --------- | ------------ | ------------- |
| 720p      | <= 720px  | 1.0           |
| 1080p     | <= 1080px | 1.5           |
| 2K        | <= 1440px | 2.0           |

A qualidade é determinada automaticamente a partir da menor dimensão do vídeo.

---

## Formato de erro

Todas as respostas de erro seguem este formato:

```json
{
  "success": false,
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": {
    "field": "additional context"
  }
}
```

Códigos de erro frequentes:

- `MISSING_API_KEY`
- `INVALID_API_KEY`
- `INVALID_API_KEY_FORMAT`
- `API_KEY_INACTIVE`
- `USER_NOT_FOUND`
- `INVALID_REQUEST`
- `INVALID_CONFIG`
- `INSUFFICIENT_CREDITS`
- `NOT_FOUND`
- `ALREADY_RENDERING`
- `REMOTE_ERROR`
- `RENDER_TRIGGER_FAILED`
- `INTERNAL_ERROR`

## Atualizações dos SDKs e da API

`GET /api/v1/capabilities` informa versão do schema, tipos de clipes/animações/transições, qualidades e recursos. Implantações antigas podem responder 404.

A criação aceita `title` (1–255 caracteres), `category` (1–100, padrão `api`) e objeto `metadata`. Listas e detalhes incluem título e categoria. `category=all` inclui tarefas do site; sem filtro, a categoria continua `api`. `all` é reservado para listagem.

Conversão e renderização de prévias aceitam `metadata` e `category`. `POST /api/v1/preview/:tempId/render` converte e inicia a renderização. Opções: `webhook_url` e inteiro positivo `num_workers` (padrão 5). Sem corpo são usados valores padrão. Parâmetros inválidos retornam `INVALID_REQUEST` (400); schemas inválidos, `INVALID_CONFIG` (400).

Prévias autenticadas oferecem URLs absolutas `previewUrl`, `playerUrl` e, quando disponível, `viewerUrl`. Preserve `tempId` e `expiresIn`. A qualidade deriva das dimensões do schema; não existe opção quality separada.