Gasto e teto
O Pico cobra da sua conta só o que a fonte de pesquisa (Virlo) cobra do Pico — com o valor real do header x-cost da chamada, lançado no seu extrato. A IA (criar peças, análises, tradução) é paga pelo Pico.
O que custa
| Rota | Custo | Confirmação |
|---|---|---|
POST /v1/pesquisas | US$ 0,50 (coleta) + US$ 1,00 com dataIntelligence (ganchos, tópicos, intent match) | confirmarGasto |
POST /v1/criadores/satelite | US$ 0,50 | confirmarGasto |
POST /v1/criadores/monitorar | US$ 0,25 por ciclo de coleta | confirmarGasto |
POST /v1/pecas, …/analise, …/melhorar-intent, …/traduzir | IA do Pico — custo.fonte: "ia-do-pico", US$ 0 para você | nenhuma |
Tudo o mais (GET, agendar, perfil, taxonomias, sugerir keywords) | grátis | nenhuma |
GET /v1/pesquisas/{id} e os recortes (/videos, /ganchos…) não cobram: são leituras do que a coleta já pagou.
confirmarGasto: true
Rota que cobra exige o campo literal no corpo. Sem ele:
HTTP 409
{ "code": "gasto_nao_confirmado", "detail": "Pesquisar este nicho custa cerca de US$ 1,50. Repita com \"confirmarGasto\": true para seguir.", "estimativaUsd": 1.5 }Nada foi cobrado. É o desenho: o cliente (ou o Claude Code) mostra o valor, a pessoa diz sim, a chamada se repete com "confirmarGasto": true. Um script que sempre manda true está escolhendo gastar — e o teto do mês é a parede.
O teto do mês
GET /v1/custo mostra teto: { usdMes, gastoNoMesUsd }. PUT /v1/custo/teto com { "usdMes": 20 } fixa o teto; null remove; 0 bloqueia tudo que é pago.
A chamada que estouraria o teto é recusada antes de tocar a fonte:
HTTP 409
{ "code": "teto_do_mes", "detail": "Teto do mês: US$ 20,00 já gastos. Ajuste em Conta → Custo." }Leituras e chamadas grátis continuam funcionando com o teto estourado — é justamente quando você precisa ler o extrato.
Idempotency-Key
Nas rotas que cobram, mande um UUID por operação:
Idempotency-Key: 4d1f…Se a rede cair depois de a fonte já ter cobrado e o cliente repetir, a segunda chamada com o mesmo header (em 24 h) devolve a mesma resposta (Idempotent-Replayed: true) sem cobrar de novo. Header vazio ou com mais de 200 caracteres: 400 idempotencia_invalida.
O extrato
curl -s $PICO/custo -H "Authorization: Bearer $PICO_API_KEY"{
"month": "2026-09",
"researchUsd": 3.5,
"lines": [ { "at": "2026-09-11T14:02:11.000Z", "label": "Coleta do nicho", "usd": 1.5, "attributed": true } ],
"teto": { "usdMes": 20, "gastoNoMesUsd": 3.5 }
}Cada linha é uma chamada paga, com o valor que a fonte cobrou. A tela Conta → Custo lê a mesma tabela.
Quando a fonte está fora
502 virlo_indisponivel: a fonte não respondeu ou a chave dela (do Pico) está sem saldo. Não é da sua conta; tente mais tarde. Se persistir, é do operador do Pico.