Saltar para o conteúdo principal
A querying.ai implementa o contrato comum de tarefas assíncronas das APIs de mecanismos de resposta. Nos endpoints abaixo, os esquemas de requisição e resposta são os mesmos, então um cliente que já funciona costuma precisar apenas de uma nova URL base e de uma nova chave.

A mudança

Aponte sua constante de chave de API para uma chave da querying.ai criada em Chaves de API. URLs de webhook, chaves de idempotência, tipos de tarefa e o parsing das respostas continuam como estão.

O que está implementado

Todos os mecanismos funcionam de forma assíncrona; não há endpoint que fique bloqueado até a resposta chegar.

Onde o comportamento é diferente

As chaves API compartilham a concorrência da conta. Envios de tarefas e polling com chave API não têm limite fixo de RPM. Estes limites continuam válidos:
  • A sobrecarga da API retorna 503 SERVER_OVERLOADED com Retry-After. Tente novamente após esse intervalo.
  • Seu plano limita quantas tarefas da sua conta podem rodar ao mesmo tempo. As tarefas acima do limite esperam na fila e começam quando as que estão em execução terminam. Uma conta pode ter 1.000.000 tarefas em espera; acima disso, o envio retorna 429 QUEUE_LIMIT_EXCEEDED.
  • Uma chave pode ter um limite diário de créditos. Acima dele, o envio retorna 429 KEY_DAILY_CREDIT_LIMIT até a próxima meia-noite UTC.
Para grandes volumes, envie lotes em vez de muitas requisições individuais. Veja Créditos e limites e Lotes e grades.
Cada mecanismo tem seu próprio preço: por exemplo, 1 crédito para ChatGPT e Perplexity, 1,25 para Gemini e Google AI Overviews. O catálogo de mecanismos lista todos os preços.As respostas de envio informam { "creditsToCharge": 0, "creditsCharged": 0 }. Quando a tarefa fica COMPLETED, o polling e o webhook informam a cobrança efetuada. Tarefas com falha não são cobradas.
Um mecanismo e um país sem rota retornam 422 REGION_UNSUPPORTED na hora, em vez de aceitar uma tarefa que vai falhar. Repetir o mesmo par não adianta.Um cliente que supõe que todo envio bem formado é aceito precisa de um tratamento para 422. Veja Regiões e localização.
Nem todo mecanismo atende às flags de payload.include. Uma flag markdown, rawResponse ou searchQueries não suportada é ignorada. Uma flag html ou analysis não suportada retorna 422, e uma flag citationAnalysis não suportada retorna 400. Consulte a matriz de suporte antes de enviá-las.
Todo webhook traz os cabeçalhos querying-webhook-id, querying-webhook-timestamp e querying-webhook-signature. Seu receptor atual continua funcionando se os ignorar, mas você deve verificá-los. Veja Webhooks.
GET /v1/async/task/{id} em uma tarefa FAILED retorna um campo error no nível superior. É uma string simples, não o objeto { code, message, timestamp } usado nos erros de requisição.
Um cliente que trata um body.error verdadeiro como requisição com falha vai interpretar errado uma tarefa com falha. Decida pelo task.status.

Mapeie mecanismos para tipos de tarefa

GOOGLE_AIO retorna um envelope da página de resultados com o AI Overview em um membro aioverview que pode ser nulo. Veja Google AI Overviews.

Verifique a migração

Rode sua integração atual e a querying.ai em paralelo por um tempo e compare os campos que você consome, geralmente response.text, response.sources[] e response.markdown. Uma comparação em sombra pega diferenças que uma checagem de esquema não vê, como uma lista de fontes em outra ordem.