Uma única API para todos os mecanismos de resposta com IA

Envie um prompt a qualquer mecanismo de IA compatível com uma única requisição e receba a resposta em JSON estruturado, por webhook ou por consulta.

O que você recebe

• Um único endpoint, POST /v1/async/task, para todos os mecanismos. Escolha o mecanismo com taskType e o mercado com country.
• O mesmo envelope para todos os mecanismos: o id, o status e os horários da tarefa envolvem uma response própria de cada mecanismo.
• Resultados do jeito que você preferir: um webhook para o seu servidor assim que a tarefa termina, ou GET /v1/async/task/{id} quando você quiser.
• Novas tentativas seguras com idempotencyKey: enviar a mesma chave de novo devolve a tarefa que você já criou.

Como funciona

Os mecanismos de IA levam de segundos a minutos para responder, por isso cada requisição vira uma tarefa persistente. A tarefa passa de QUEUED para PROCESSING e termina como COMPLETED com a resposta ou FAILED com o motivo. Se o mecanismo tiver um erro temporário, a tarefa volta para a fila e é tentada de novo, e as falhas breves se resolvem antes de chegar até você.

Adicione webhook.url e enviamos a tarefa concluída para o seu servidor, com até cinco tentativas em cerca de 30 minutos. As tarefas concluídas também ficam disponíveis para consulta por 24 horas, então webhook e consulta juntos cobrem todos os resultados.

Onde ajuda

• Verifique a visibilidade da sua marca a partir do seu próprio backend, na frequência que quiser.
• Envie o mesmo prompt a vários mecanismos e compare as respostas lado a lado.
• Simplifique trabalhos longos: envie, siga com outras tarefas e deixe o webhook trazer o resultado.

Envie a requisição

Envie a requisição com a sua chave de API no cabeçalho Authorization.

curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "CHATGPT",
    "payload": {
      "prompt": "Best coffee shops near me for working on a laptop",
      "country": "US"
    },
    "webhook": { "url": "https://your-server.example.com/hooks/querying" },
    "idempotencyKey": "laptop-cafes-us-0001"
  }'

Campos da requisição

taskTypestringObrigatório

O motor que executa a tarefa, como CHATGPT ou GOOGLE.

payloadobjectObrigatório

A entrada do motor: prompt ou query, mais country e as opções do motor.

webhook.urlstring

Um endereço HTTPS do seu servidor. A tarefa concluída é enviada para lá assim que termina.

idempotencyKeystring

Seu próprio ID para a requisição. Cada chave cria uma única tarefa por conta, então um reenvio continua sendo uma tarefa.

Resposta

A chamada responde na hora com a tarefa em QUEUED. credits fica em 0 até a tarefa terminar, e idempotencyKey volta como você enviou.

{
  "success": true,
  "task": {
    "id": "…",
    "taskType": "CHATGPT",
    "status": "QUEUED",
    "priority": 1,
    "createdAt": "…",
    "idempotencyKey": "laptop-cafes-us-0001"
  },
  "credits": { "creditsToCharge": 0, "creditsCharged": 0 }
}

Receba o resultado

Leia a tarefa com GET /v1/async/task/{id} a cada poucos segundos até status virar COMPLETED ou FAILED. Os resultados ficam disponíveis por 24 horas após o fim da tarefa.

curl https://api.querying.ai/v1/async/task/$TASK_ID \
  -H "Authorization: Bearer $QUERYING_API_KEY"

Uma tarefa concluída traz os credits cobrados e a response do mecanismo. Esta é real, resumida para facilitar a leitura.

{
  "success": true,
  "task": {
    "id": "e5aba119-a26e-4f82-a965-35c9234a428b",
    "taskType": "CHATGPT",
    "status": "COMPLETED",
    "createdAt": "2026-10-02T15:41:03.858Z"
  },
  "credits": { "creditsToCharge": 2, "creditsCharged": 2 },
  "response": {
    "text": "Here are several **nearby cafés that look particularly suitable for laptop work**, based on current local listings and work-friendly details:\n…",
    "sources": [
      {
        "position": 1,
        "url": "https://awifiplace.com/cities/new-york",
        "label": "Best Coffee Shops to Work in New York (2026) | 103 Cafes with WiFi"
      }
    ],
    "searchQueries": [
      "best coffee shops for laptop work near me wifi outlets"
    ]
  }
}

task.statusstring

QUEUED, PROCESSING e, no fim, COMPLETED com a resposta ou FAILED com error.

credits.creditsChargedinteger

Créditos cobrados pela tarefa concluída. Uma tarefa que falhou cobra 0.

Webhooks

Com webhook.url, a tarefa concluída chega ao seu servidor como um POST com os mesmos task, credits e response da consulta. Uma tarefa com falha chega do mesmo jeito, com response.error e 0 créditos cobrados. Três cabeçalhos assinam cada entrega:

querying-webhook-idstring

O ID da tarefa. Cada entrega chega pelo menos uma vez, então use-o para descartar repetições.

querying-webhook-timestampstring

Segundos Unix do momento da assinatura. Aceite entregas assinadas nos últimos 5 minutos.

querying-webhook-signaturestring

v1, seguido do HMAC-SHA256 em base64 de {id}.{timestamp}.{body}, com o resumo SHA-256 da sua chave de API como chave.

Confira a assinatura no corpo bruto, antes de interpretá-lo, e aceite a entrega quando ela confere:

import base64
import hashlib
import hmac
import os
import time


def verify_webhook(headers, body: bytes) -> bool:
    """body is the raw request body, before json.loads."""
    task_id = headers["querying-webhook-id"]
    timestamp = headers["querying-webhook-timestamp"]
    key = hashlib.sha256(os.environ["QUERYING_API_KEY"].encode()).digest()
    signed = f"{task_id}.{timestamp}.".encode() + body
    digest = hmac.new(key, signed, hashlib.sha256).digest()
    expected = "v1," + base64.b64encode(digest).decode()
    given = headers.get("querying-webhook-signature", "")
    fresh = abs(time.time() - int(timestamp)) <= 300
    return fresh and hmac.compare_digest(expected, given)

Responda com um status 2xx em até 30 segundos. Com outra resposta, ou depois de 30 segundos, a entrega se repete após 2, 4, 8 e 16 minutos, cinco tentativas no total, todas com o mesmo querying-webhook-id.

Erros

Uma requisição recusada responde na hora com success em false e um error com code, message e, em erros de campo, details. Ela fica fora da fila e custa 0 créditos.

VALIDATION_ERRORHTTP 400

Falta um campo ou o valor está fora do intervalo. details indica o campo.

MISSING_API_KEYHTTP 401

Falta o cabeçalho Authorization, ou a chave é desconhecida, expirou ou foi revogada.

INSUFFICIENT_CREDITSHTTP 402

O saldo é menor que o preço da tarefa. Adicione créditos ou mude de plano e envie de novo.

KEY_SCOPE_DENIEDHTTP 403

O mecanismo está fora dos Mecanismos permitidos da chave. Use outra chave ou adicione o mecanismo em Gerenciar chave.

RESOURCE_ALREADY_EXISTSHTTP 409

Já existe na sua conta uma tarefa com este idempotencyKey, então o envio continua sendo uma única tarefa. Num lote, o item conta como sucesso.

PAYLOAD_TOO_LARGEHTTP 413

O corpo passa de 1 MiB, ou de 8 MiB num lote.

REGION_UNSUPPORTEDHTTP 422

country está fora da lista de países do mecanismo. Reenviar dá o mesmo resultado, por isso details.retryable é false.

PLAN_CONCURRENCY_LIMITHTTP 429

Suas tarefas na fila e em execução atingiram o limite do plano: 2 no plano gratuito, 10 no Basic, 25 no Pro, 50 no Scale e 100 no Max. Envie de novo após Retry-After segundos.

KEY_DAILY_CREDIT_LIMITHTTP 429

A chave esgotou o Limite diário de créditos. Retry-After vai até a próxima meia-noite UTC.

QUEUE_BACKPRESSUREHTTP 429

A fila do mecanismo está cheia no momento. Envie de novo após Retry-After segundos.

Preço

Cada mecanismo tem seu próprio preço em créditos, e a tarefa é cobrada quando é concluída. Uma tarefa com falha libera os créditos que havia reservado.