Pesquisa de nicho

Uma pesquisa é uma coleta na fonte (Virlo) a partir de um intent e de keywords: vídeos recentes das redes escolhidas, os criadores por trás deles, sons, hashtags, anúncios, uma análise e, com inteligência por vídeo, os ganchos ranqueados. O Pico guarda o resultado; você lê por recortes.

O ciclo

POST /v1/pesquisas  →  202 running
GET  /v1/pesquisas/{id}  (a cada ~5 s)  →  running… →  completed
POST /v1/pesquisas/{id}/traduzir  →  narrativa em português
GET  /v1/pesquisas/{id}/{recurso}  →  ganchos, vídeos, análise…

O GET é quem avança o estado. Não há cron: enquanto running, cada GET /v1/pesquisas/{id} pergunta à fonte; quando ela terminou, o Pico hidrata (baixa os oito recortes), grava e responde completed. Um cliente que nunca pergunta deixa a pesquisa parada em running — e a fonte já cobrou.

Escrever um bom intent

A fonte chama o intent de "a maior alavanca de qualidade". Uma frase dizendo tema, para quem, formato e objetivo comercial:

"conteúdo de moda casual para mulheres de 25 a 40 em São Paulo, para vender roupa online"

Tem uma descrição crua? POST /v1/pesquisas/melhorar-intent com { "descricao": "tenho loja de roupa" } reescreve usando o seu perfil (IA do Pico). Sem keywords? POST /v1/pesquisas/sugerir-keywords com o intent (grátis; o reasoning vem traduzido — reasoningIdioma diz pt ou en se a IA não respondeu a tempo).

Todos os idiomas entram por padrão (englishOnly: false): o corpus da fonte é majoritariamente inglês e o filtro de fábrica devolveria resultado inútil para PME brasileira.

dataIntelligence — o que a inteligência por vídeo dá

Com true (padrão, +US$ 1,00): para cada vídeo, tópico, resumo, tom, sentimento, se casa com o intent, e o gancho extraído dos primeiros segundos — é o que alimenta o recorte ganchos. Sem ela, ganchos vem vazio (cobertura.videosWithHooks: 0 significa "sem inteligência", não "o nicho não tem gancho").

Os recortes

GET /v1/pesquisas/{id}/{recurso}:

Pesquisa ainda rodando responde 409 pesquisa_em_andamento.

Português: a tradução

A fonte escreve a narrativa em inglês — a análise, as tendências, os resumos por vídeo. A API traduz e grava:

curl -s -X POST $PICO/pesquisas/ID/traduzir -H "Authorization: Bearer $PICO_API_KEY"

{ "id": "…", "completa": true, "total": 84, "traduzidas": 84, "novas": 84, "chamadas": 3, "pendentes": 0, "mapa": { "The niche is growing fast.": "O nicho está crescendo rápido.", "…": "…" } }

• Chamada repetida é barata: só traduz o que falta (novas: 0 quando já está tudo).
• Parcial é normal: a chamada tem um orçamento de ~40 s; se vier 202 e completa: false, chame de novo.
• GET …/{recurso} aplica a tradução por padrão (?idioma=pt); ?idioma=en devolve o bruto. Toda resposta traz traducao: { total, traduzidas } para você saber se está inteira.
• O que não se traduz, de propósito: hookText (é a fala do criador, na língua do vídeo — traduzir seria deturpar o dado), títulos, nomes, hashtags, rótulos de taxonomia. A tela do Pico usa a mesma tradução da narrativa. Além dela, a tela mostra a frase dos cartões de vídeo em português com um selo "traduzido" — é só exibição: pela API o hookText e o título vêm sempre como o criador escreveu, e o mapa de /traduzir só tem a narrativa.

Análise por IA (do Pico)

POST /v1/pesquisas/{id}/analise gera, em português e com o seu perfil no contexto, o relatório: resumo, temas, estratégia de conteúdo, padrões de gancho, horários. Grava em analise e substitui o da fonte para aquela pesquisa.

Criadores

• Satélite (POST /v1/criadores/satelite, US$ 0,50): consulta pontual de um perfil — seguidores, engajamento, 20 vídeos com outliers, relatório. GET /v1/criadores/satelite/{id} faz o poll e grava quando pronto.
• Monitorar (POST /v1/criadores/monitorar, US$ 0,25/ciclo): a fonte revisita o perfil na cadência (weekly, bi_weekly, monthly, every_other_day) e acumula snapshots.
• Briefing (POST /v1/criadores/{id}/analise, IA do Pico): 180–260 palavras com 3 ações para o seu negócio.

Taxonomias

GET /v1/pesquisas/taxonomias (grátis): tipos de gancho (hookType), tipos visuais, categorias da biblioteca e regiões — para interpretar e filtrar.