Cortes IA

Corta um vídeo longo em vários clipes curtos verticais, rankeados por IA (transcrição → ranking dos melhores trechos → recorte automático). Aceita um link de página (YouTube, TikTok, Instagram) ou a URL de um arquivo de vídeo já hospedado. Responde 202 Accepted com um taskId; acompanhe o resultado por polling em GET /api/v1/tasks/:id.

Escopo necessário: generate:video.

O número de cortes é automático — derivado da duração do vídeo (cerca de 3 cortes a cada 10 min, mínimo 3, máximo 20). Não é configurável. A duração de links do YouTube é re-resolvida no servidor (o durationSec enviado é ignorado para YouTube). O custo é por duração do vídeo de entrada + número de cortes — o débito acontece na criação da task.

Body

Exemplo de request

curl -X POST https://avatrix.io/api/v1/generate/cortes \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c-cortes-001" \
  -d '{
    "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "aspectRatio": "9:16"
  }'

Resposta — 202

{ "success": true, "data": { "taskId": "...", "status": "queued" } }

Resultado — os N cortes

Faça polling em GET /api/v1/tasks/:id. Quando a task chega a completed, além do resultUrl (o primeiro corte, usado como capa) o corpo traz a lista completa clips:

{
  "success": true,
  "data": {
    "id": "...",
    "taskType": "cortes",
    "status": "completed",
    "resultUrl": "https://storage.avatrix.io/.../corte-1.mp4",
    "clips": [
      {
        "url": "https://storage.avatrix.io/.../corte-1.mp4",
        "title": null,
        "hook": null,
        "score": null,
        "startTime": null,
        "endTime": null
      }
    ]
  }
}

Cada item de clips garante o url (mp4 do corte). Os campos de metadata — title, hook, score (relevância 0–1) e startTime/endTime (em segundos, no vídeo original) — são best-effort: vêm preenchidos apenas quando o motor de clipping retorna o ranking junto do corte; hoje o caminho padrão de geração não o retorna e eles chegam como null. Trate todos como opcionais no seu parser.

Idempotência

Envie o header Idempotency-Key (opcional, máx. 128 chars). Requisições repetidas com a mesma chave (24h) retornam a resposta original sem novo débito. Ver Idempotência.

Erros relevantes

Ver Códigos de erro e Escopos.