메인 콘텐츠로 건너뛰기
querying.ai는 답변 엔진 API의 공통 비동기 태스크 계약을 구현합니다. 아래 엔드포인트의 요청·응답 스키마는 같으므로, 동작하던 클라이언트는 보통 base URL과 키만 바꾸면 됩니다.

바꿀 부분

API 키 상수를 API 키에서 발급한 querying.ai 키로 바꾸세요. webhook URL, 멱등 키, 태스크 유형, 응답 파싱은 그대로 둡니다.

구현 범위

모든 엔진은 비동기로 실행되며, 답변이 올 때까지 요청을 붙잡아 두는 엔드포인트는 없습니다.

동작이 다른 부분

API 키는 계정 동시성을 공유합니다. API 키를 사용하는 작업 제출과 상태 조회에는 고정 분당 제한이 없습니다. 다음 제한은 적용됩니다.
  • API 처리 용량이 부족하면 Retry-After와 함께 503 SERVER_OVERLOADED를 반환합니다. 안내된 시간 뒤에 재시도합니다.
  • 요금제는 계정이 동시에 실행할 수 있는 태스크 수를 제한합니다. 한도를 넘는 태스크는 대기열에서 기다렸다가 실행 중인 태스크가 끝나는 대로 시작합니다. 계정 하나에 1,000,000개까지 기다릴 수 있고, 그보다 많으면 제출이 429 QUEUE_LIMIT_EXCEEDED를 반환합니다.
  • 키에 일일 크레딧 한도를 둘 수 있습니다. 넘으면 다음 UTC 자정까지 제출이 429 KEY_DAILY_CREDIT_LIMIT를 반환합니다.
대량 요청은 단건을 여러 번 보내지 말고 배치로 보내세요. 크레딧과 한도와 배치와 그리드를 참고하세요.
엔진마다 가격이 다릅니다. 예를 들어 ChatGPT와 Perplexity는 1 크레딧, Gemini와 Google AI 개요는 1.25 크레딧입니다. 모든 가격은 엔진 목록에 있습니다.제출 응답은 { "creditsToCharge": 0, "creditsCharged": 0 }을 보고합니다. 태스크가 COMPLETED가 되면 폴링과 webhook이 확정된 차감액을 보고합니다. 실패한 태스크에는 과금하지 않습니다.
경로가 없는 엔진과 국가 조합은 실패할 태스크를 접수하지 않고 즉시 422 REGION_UNSUPPORTED를 반환합니다. 같은 조합을 재시도해도 소용없습니다.형식이 맞는 제출은 모두 접수된다고 가정하는 클라이언트라면 422에 대한 분기가 필요합니다. 지역과 위치를 참고하세요.
payload.include 플래그를 모든 엔진이 따르지는 않습니다. 지원하지 않는 markdown, rawResponse, searchQueries 플래그는 무시됩니다. 지원하지 않는 html이나 analysis 플래그는 422를, 지원하지 않는 citationAnalysis 플래그는 400을 반환합니다. 보내기 전에 지원 매트릭스를 확인하세요.
모든 webhook에는 querying-webhook-id, querying-webhook-timestamp, querying-webhook-signature 헤더가 붙습니다. 기존 수신기는 이 헤더를 무시해도 계속 동작하지만, 검증하는 것이 좋습니다. Webhook을 참고하세요.
FAILED 태스크에 GET /v1/async/task/{id}를 호출하면 최상위 error 필드가 반환됩니다. 요청 오류가 쓰는 { code, message, timestamp } 객체가 아니라 일반 문자열입니다.
body.error가 참이면 요청이 실패했다고 보는 클라이언트는 실패한 태스크를 잘못 해석합니다. task.status로 분기하세요.

엔진과 태스크 유형 대응

GOOGLE_AIO은 AI 개요를 nullable 멤버 aioverview에 담은 검색 결과 페이지 봉투를 반환합니다. Google AI 개요를 참고하세요.

전환 검증

한동안 기존 연동과 querying.ai를 병행 실행하고, 실제로 쓰는 필드를 비교하세요. 보통 response.text, response.sources[], response.markdown입니다. 그림자 비교는 순서가 다른 출처 목록처럼 스키마 검사로는 잡히지 않는 차이를 잡아냅니다.