Criar um upscale

POST https://videoupscaler.co/api/v1/upscale

Inicia um upscale e retorna a nova tarefa. Baixamos o vídeo, lemos a duração real diretamente do arquivo e cobramos os créditos antes de o processamento começar. Você nunca precisa informar a duração.

Requisição

Cabeçalhos

Corpo

Requisitos do vídeo

• Formatos: MP4, MOV e WebM.
• Duração: até 1200 segundos em 1080p e 600 segundos em 2k e 4k.
• Tamanho: até 500MB para uma video_url remota e 100MB via /uploads.
• O servidor da video_url precisa responder a um GET simples com o arquivo e um cabeçalho Content-Length. Links assinados do S3, R2 ou Google Cloud Storage funcionam. Páginas de compartilhamento, como o YouTube ou as prévias do Google Drive, não.
• Arquivos MP4 fragmentados sem duração total são rejeitados. Recodifique-os antes em um MP4 comum.
• Arquivos WebM precisam registrar a duração no cabeçalho. Gravações feitas no navegador (MediaRecorder) muitas vezes não registram; recodifique-as antes.

Exemplo

curl https://videoupscaler.co/api/v1/upscale \
  -H "Authorization: Bearer $VIDEOUPSCALER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234" \
  -d '{"video_url": "https://example.com/clip.mp4", "resolution": "2k"}'

const res = await fetch('https://videoupscaler.co/api/v1/upscale', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDEOUPSCALER_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-1234',
  },
  body: JSON.stringify({ video_url: 'https://example.com/clip.mp4', resolution: '2k' }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const task = await res.json();

res = requests.post(
    "https://videoupscaler.co/api/v1/upscale",
    headers={
        "Authorization": f"Bearer {os.environ['VIDEOUPSCALER_API_KEY']}",
        "Idempotency-Key": "order-1234",
    },
    json={"video_url": "https://example.com/clip.mp4", "resolution": "2k"},
    timeout=300,
)
res.raise_for_status()
task = res.json()

Resposta

201 Created com a tarefa:

{
  "id": "0b6f3c1e-8a52-5d1e-9c43-3f1d2e7a9b10",
  "status": "processing",
  "resolution": "2k",
  "video_url": "https://example.com/clip.mp4",
  "duration_seconds": 12.4,
  "processed_seconds": 12.4,
  "credits_charged": 26,
  "watermark": false,
  "output_url": null,
  "thumbnail_url": null,
  "error": null,
  "created_at": "2026-09-30T08:00:00.000Z",
  "updated_at": "2026-09-30T08:00:02.000Z"
}

Depois, consulte a tarefa até ela ficar completed.

Esta requisição baixa o vídeo antes de responder, então um arquivo remoto grande pode demorar um pouco. Configure um timeout de pelo menos 5 minutos.

Idempotência

Envie um Idempotency-Key em toda requisição e reutilize-o ao repetir a chamada depois de um timeout ou erro de rede:

• A mesma chave com a mesma video_url e resolution retorna a tarefa original com 200 OK. Você não é cobrado de novo.
• A mesma chave com video_url ou resolution diferente retorna 409 idempotency_conflict.
• Sem o cabeçalho, cada requisição cria e cobra uma nova tarefa.

Cobrança

O preço é a duração do vídeo em segundos inteiros (arredondada para cima) multiplicada pela tarifa da resolução. Veja Créditos e preços. Um vídeo de 12,4 segundos em 2K custa 13 × 2 = 26 créditos.

Se o processamento falhar, os créditos são reembolsados automaticamente e a tarefa passa para failed.

Erros

Veja Erros para o formato dos erros.