VideoSpy API

Ler um vídeo

GET /api/v1/videos/:id devolve o vídeo da base da conta e, quando existe, a análise com transcrição, hook e resumo. Custa 2 unidades, inclusive quando a resposta é 404.

GET/api/v1/videos/:id2 unidades

O :id é o uuid devolvido em GET /videos, em video_id de uma ideia ou em video_ids de um criador. Fora da base da conta a resposta é 404 e as 2 unidades já foram debitadas.

Chamada

curl https://videospy.com.br/api/v1/videos/8c1d2e3f-4a5b-4c6d-8e7f-9012345678ab \
  -H "Authorization: Bearer vsk_sua_chave"

Resposta 200

O corpo é { data }. data junta o vídeo e analysis. analysis é null quando ainda não há linha de análise para esse vídeo.

{
  "data": {
    "id": "8c1d2e3f-4a5b-4c6d-8e7f-9012345678ab",
    "platform": "instagram",
    "canonical_url": "https://www.instagram.com/reel/exemplo",
    "caption": "Mas você pagaria 300 mil e receberia um apartamento assim?",
    "published_at": "2026-09-12T18:30:00.000Z",
    "views_current": 128430,
    "analysis": {
      "transcript": "Mas você pagaria trezentos mil…",
      "transcript_language": "pt",
      "summary": "Confronta o valor pago com o estado do imóvel.",
      "hook_exact": "Mas você pagaria 300 mil e receberia um apartamento assim?",
      "hook_template": "Mas você pagaria {valor} e receberia {promessa} assim?",
      "hook_type": "pergunta",
      "why_it_worked": "A pergunta traz o prejuízo para o primeiro segundo.",
      "status": "completed"
    }
  }
}

Campos

Campo	Tipo	Significado
id	uuid	Id do vídeo.
platform	texto	instagram, tiktok ou youtube no uso do produto.
canonical_url	texto	URL canônica.
caption	texto ou null	Legenda.
published_at	data e hora ou null	Publicação.
views_current	número ou null	Visualizações conhecidas.
analysis	objeto ou null	Linha de análise, ou null.
analysis.transcript	texto ou null	Transcrição. Em vídeo de edição pode vir vazia.
analysis.transcript_language	texto ou null	Idioma da transcrição, quando houver.
analysis.summary	texto ou null	Resumo.
analysis.hook_exact	texto ou null	Fala ou texto de abertura.
analysis.hook_template	texto ou null	Molde do hook com lacunas.
analysis.hook_type	texto ou null	Tipo atribuído na análise. Vídeo de edição pode vir como edit.
analysis.why_it_worked	texto ou null	Motivo registrado para o desempenho.
analysis.status	texto	Estado salvo. O app grava completed, processing, failed ou unavailable.

Erros

Status	Quando acontece
404	O id não está na base da conta. Corpo: { "error": "Vídeo fora da sua base." }. Conta 2 unidades.
401	Header ausente, esquema diferente de Bearer, chave que não começa com vsk_, chave curta, hash desconhecido ou chave revogada.
403	Plano sem API. Entram Ultra e Vitalício com assinatura ativa, e conta com acesso de Agência.
402	Cota do mês esgotada e saldo de créditos insuficiente para o uso extra. O corpo traz used, included e balance.
429	Mais de 60 requisições na mesma chave dentro de um minuto.
500	Falha ao registrar o uso ou ao ler os dados.
503	A função de cota ainda não está ativa neste ambiente.