Skip to main content
이 API는 표준 비동기 태스크 계약을 구현합니다. 지원하는 엔드포인트의 요청·응답 스키마는 같으므로, 동작하던 클라이언트는 보통 코드를 고칠 필요가 없습니다.

​
마이그레이션

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

​
구현 범위

지원

POST /v1/async/taskPOST /v1/async/task/batchGET /v1/async/task/{id}Webhook 콜백

미구현

/v1/monitor/* 동기 엔드포인트/v1/async/status
동기식 /v1/monitor/* 계열은 의도적으로 없습니다. 여기 있는 모든 엔진은 비동기로 동작하며, 질의에 걸리는 시간 동안 요청을 붙잡아 두는 형태는 이 서비스가 제공하지 않습니다.

​
동작이 다른 부분

키 단위 속도 제한이 없습니다. 대량 요청은 배치 제출로 왕복 횟수를 줄이세요.지역과 권장 사항을 참고하세요.
credits는 봉투의 일부로 모든 응답에 있습니다. 제출과 폴링 응답은 { "creditsToCharge": 0, "creditsCharged": 0 }을 보고하고, webhook은 엔진별 크레딧 비용(엔진에 따라 1–3 크레딧)을 보고합니다.실패한 태스크에는 과금하지 않습니다. 크레딧 잔액은 대시보드에서 확인할 수 있습니다.
전혀 서빙할 수 없는 조합이 하나 있습니다. CHATGPT/PERPLEXITY/GEMINI를 CN으로 보내는 경우로, exit 공급이 없어 요청이 대상에 닿지 못합니다. 접수하지 않고 즉시 422 REGION_UNSUPPORTED로 실패합니다. 같은 상황의 일시적 버전은 422 REGION_UNAVAILABLE입니다.형식이 맞는 제출은 모두 접수된다고 가정하는 클라이언트라면 여기에 분기가 필요합니다. 지역을 참고하세요.
payload.include 플래그는 받지만, 여기 있는 대부분의 엔진은 고정된 형태의 응답을 반환하며 플래그를 무시합니다. 전체 플래그를 따르는 엔진은 ChatGPT뿐이고, GEMINI는 markdown과 rawResponse만 따릅니다.예를 들어 Gemini에 html을 요청하면 오류도 필드도 없이 조용히 무시됩니다. 플래그 지원 표를 참고하세요.
그 밖의 오류 처리는 일반적입니다. 검증 실패는 400, 401은 MISSING_API_KEY, 404는 RESOURCE_NOT_FOUND를 보고하고, details가 문제 필드를 알려줍니다.추가된 것은 위에서 설명한 422 두 가지(REGION_UNSUPPORTED, REGION_UNAVAILABLE)뿐입니다. 서빙할 수 없는 지역을 미리 알려주므로, 422를 처리해 본 적 없는 클라이언트도 이를 받게 됩니다.
FAILED 태스크에 GET /v1/async/task/{id}를 호출하면 태스크 상태 스키마에 따로 정의되지 않은 최상위 error 필드가 반환됩니다. 요청 수준 오류가 쓰는 {code, message, timestamp} 객체가 아니라 일반 문자열입니다.
body.error가 참이면 요청이 실패했다고 보는 클라이언트는, 정상 조회된 실패 태스크를 잘못 해석합니다. task.status로 분기하세요.
이 동작들은 스키마를 읽어서가 아니라 이 API를 실제로 호출해서 확인했습니다. 공개 스펙과 실제 응답이 다르면 이 문서는 실제 응답을 따릅니다.

​
알맞은 taskType 고르기

지금 엔진별 엔드포인트를 호출하고 있다면 엔진 이름은 다음 taskType에 대응합니다.
GOOGLE이 “AI 개요”를 뜻하는 것은 명명 관례일 뿐 Google 제품명이 아닙니다. 응답은 aioverview를 nullable 멤버로 가진 SERP 봉투입니다. GOOGLE 응답 형태를 참고하세요.

​
전환 검증

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