Fluxo recomendado
1
Listar plataformas (opcional)
GET /platforms retorna hosts suportados e capacidades (video, audio, image, metadata).2
Resolver a URL
POST /media/resolve com { "url": "..." } retorna data.id, título, thumbnail e formats[].3
Enfileirar download
POST /media/download com { "media_id": "<data.id>", "format": "video_best" } retorna 202 e job_id.4
Consultar job
GET /jobs/{jobId} até status: "completed" — então use result.download_url.Exemplos completos
Resolver sem download prévio
Você pode enviarurl diretamente em POST /media/download, mas resolver antes evita reprocessamento e permite exibir metadados no seu UI antes do download.
Campo id vs media_id
TTL padrão do resolve: 1 hora (
API_MEDIA_RESOLVE_TTL_SECONDS=3600). Após expirar, media_not_found.
Formatos
Estados do job
Se o job expirar (TTL padrão 1h),
GET /jobs/{jobId} retorna 404 job_not_found — enfileire novamente.