# API e uso

URL base:
- `https://video.renderingvideo.com`

Fluxo público:
- Use `POST /api/preview` para criar um preview
- Use `/t/:id` ou `/preview/:id` como link de reprodução
- Links de preview expiram em 7 dias
- Não dependa de rotas internas não documentadas

## 1. API de link temporário

Endpoints externos:
- `POST /api/preview`
- `GET /api/temp/:id`
- `GET /t/:id`
- `GET /preview/:id`
- `GET /`

Comportamento do link temporário:
- Os dados de preview são armazenados em KV
- A expiração padrão é de 7 dias
- A página de preview retornada pode ser compartilhada diretamente com usuários externos

## 2. `POST /api/preview`

Finalidade:
- Enviar um esquema para preview
- Executar a validação da estrutura de nível superior
- Gerar um link temporário de preview

### Cabeçalhos da requisição

```http
Content-Type: application/json
```

### Corpo da requisição

Envie o JSON completo do esquema diretamente como corpo da requisição.

Exemplo mínimo:

```json
{
  "meta": {
    "version": "2.0.0",
    "width": 1920,
    "height": 1080,
    "fps": 30
  },
  "tracks": [
    {
      "clips": [
        {
          "type": "text",
          "start": 0,
          "duration": 3,
          "text": "Temporary Preview"
        }
      ]
    }
  ]
}
```

### Resposta de sucesso

```json
{
  "success": true,
  "tempId": "uuid",
  "url": "/t/uuid",
  "viewerUrl": "/preview/uuid",
  "expiresIn": "604800 seconds (7 days)"
}
```

Campos da resposta:
- `url`: página limpa do player
- `viewerUrl`: variante da página de preview
- `tempId`: identificador usado para ler depois a configuração temporária

### Casos comuns de falha

A requisição pode falhar por causa de:
- JSON inválido
- Falta de `meta` ou `tracks` no nível superior
- Um corpo que não corresponde ao `VideoSchema` atual

## 3. `GET /api/temp/:id`

Finalidade:
- Ler o esquema por trás de um link temporário
- Permitir que sua aplicação inspecione a configuração atual de preview

### Resposta de sucesso

```json
{
  "success": true,
  "config": {
    "meta": {
      "version": "2.0.0",
      "width": 1920,
      "height": 1080,
      "fps": 30
    },
    "tracks": [
      {
        "clips": [
          {
            "type": "text",
            "start": 0,
            "duration": 3,
            "text": "Temporary Preview"
          }
        ]
      }
    ]
  }
}
```

Casos comuns de falha:
- `id` não é um UUID válido
- O link temporário não existe
- O link temporário expirou

## 4. Páginas de preview

Links temporários expõem duas páginas de reprodução:
- `GET /t/:id`: página limpa do player
- `GET /preview/:id`: variante da página de preview

Se o link temporário tiver expirado, essas páginas retornam uma mensagem de estado inválido.

- A API pública garante as URLs de preview, não detalhes internos da implementação do player
- Não dependa de caminhos proxy de assets não documentados, lógica de rewrite no cliente ou helpers internos de runtime

## 5. Fluxo externo recomendado

Ordem recomendada:
1. Montar `meta / assets / tracks`
2. Colocar mídia reutilizável em `assets` sempre que possível
3. Referenciar mídia por meio de `$ref` dentro dos clips quando apropriado
4. Enviar para `POST /api/preview`
5. Compartilhar o `/t/:id` ou `/preview/:id` retornado
6. Se necessário depois, converter o preview temporário em uma tarefa permanente pelo fluxo da sua aplicação

## 6. Recomendações de autoria

### Recomendação 1

Prefira `$ref` para mídia reutilizável em vez de repetir URLs em vários clips.

### Recomendação 2

Se as legendas vierem de um serviço externo, uma forma de resposta estável é:

```json
{
  "words": [
    {
      "word": "hello",
      "punctuated_word": "Hello",
      "start": 0,
      "end": 0.4
    }
  ]
}
```

### Recomendação 3

Não dependa de campos não documentados ou detalhes internos de implementação que não façam parte da API pública.

## 7. Checklist de depuração

Se a saída não corresponder ao esperado, verifique primeiro:
- Você ainda está enviando um objeto `video` legado no nível superior
- Seu esquema inclui `meta.version`, `meta.width`, `meta.height` e `tracks` válidos
- URLs remotas de mídia estão diretamente acessíveis pelo ambiente de reprodução
- O link temporário já expirou

## 8. Exemplo de requisição

```bash
curl -X POST https://video.renderingvideo.com/api/preview \
  -H "Content-Type: application/json" \
  -d @temp-preview.json
```

Mais exemplos: [Exemplos](https://renderingvideo.com/docs/examples.md)