> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 기존 연동 마이그레이션

> 상수 두 개만 바꾸세요. 그다음 동작이 다른 부분을 확인하세요.

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

## 마이그레이션

```diff theme={null}
- const BASE = "https://api.your-current-provider.example"
+ const BASE = "https://api.querying.ai"
```

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

## 구현 범위

<CardGroup cols={2}>
  <Card title="지원" icon="check">
    `POST /v1/async/task`

    `POST /v1/async/task/batch`

    `GET /v1/async/task/{id}`

    Webhook 콜백
  </Card>

  <Card title="미구현" icon="x">
    `/v1/monitor/*` 동기 엔드포인트

    `/v1/async/status`
  </Card>
</CardGroup>

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

## 동작이 다른 부분

<AccordionGroup>
  <Accordion title="1. 속도 제한 없음, 배치를 쓰세요" icon="gauge">
    키 단위 속도 제한이 없습니다. 대량 요청은 배치 제출로 왕복 횟수를 줄이세요.

    [지역과 권장 사항](/ko/engines/capacity)을 참고하세요.
  </Accordion>

  <Accordion title="2. 크레딧은 엔진별입니다" icon="coins">
    `credits`는 봉투의 일부로 모든 응답에 있습니다. 제출과 폴링 응답은
    `{ "creditsToCharge": 0, "creditsCharged": 0 }`을 보고하고, webhook은 엔진별 크레딧 비용(엔진에 따라
    1–3 크레딧)을 보고합니다.

    실패한 태스크에는 과금하지 않습니다. 크레딧 잔액은 대시보드에서 확인할 수 있습니다.
  </Accordion>

  <Accordion title="3. 일부 엔진 × 지역 조합은 즉시 거부됩니다" icon="ban">
    전혀 서빙할 수 없는 조합이 하나 있습니다. `CHATGPT`/`PERPLEXITY`/`GEMINI`를 `CN`으로 보내는 경우로,
    exit 공급이 없어 요청이 대상에 닿지 못합니다. 접수하지 않고 즉시 `422 REGION_UNSUPPORTED`로
    실패합니다. 같은 상황의 일시적 버전은 `422 REGION_UNAVAILABLE`입니다.

    형식이 맞는 제출은 모두 접수된다고 가정하는 클라이언트라면 여기에 분기가 필요합니다.
    [지역](/ko/engines/capacity)을 참고하세요.
  </Accordion>

  <Accordion title="4. include 플래그는 대부분 효과가 없습니다" icon="toggle-left">
    `payload.include` 플래그는 받지만, 여기 있는 대부분의 엔진은 고정된 형태의 응답을 반환하며
    플래그를 무시합니다. 전체 플래그를 따르는 엔진은 ChatGPT뿐이고, `GEMINI`는 `markdown`과
    `rawResponse`만 따릅니다.

    예를 들어 Gemini에 `html`을 요청하면 오류도 필드도 없이 조용히 무시됩니다.
    [플래그 지원 표](/ko/engines/overview)를 참고하세요.
  </Accordion>

  <Accordion title="5. 상태 코드 하나 추가: 422" icon="hash">
    그 밖의 오류 처리는 일반적입니다. 검증 실패는 `400`, `401`은 `MISSING_API_KEY`, `404`는
    `RESOURCE_NOT_FOUND`를 보고하고, `details`가 문제 필드를 알려줍니다.

    추가된 것은 위에서 설명한 `422` 두 가지(`REGION_UNSUPPORTED`, `REGION_UNAVAILABLE`)뿐입니다. 서빙할
    수 없는 지역을 미리 알려주므로, `422`를 처리해 본 적 없는 클라이언트도 이를 받게 됩니다.
  </Accordion>

  <Accordion title="6. 실패한 태스크에는 최상위 `error` 문자열이 붙습니다" icon="triangle-alert">
    `FAILED` 태스크에 `GET /v1/async/task/{id}`를 호출하면 태스크 상태 스키마에 따로 정의되지 않은 최상위
    `error` 필드가 반환됩니다. 요청 수준 오류가 쓰는 `{code, message, timestamp}` 객체가 아니라
    **일반 문자열**입니다.

    ```json theme={null}
    { "success": true, "task": { "status": "FAILED", "...": "..." }, "error": "ENGINE_TIMEOUT: The engine did not answer before the task deadline." }
    ```

    `body.error`가 참이면 *요청*이 실패했다고 보는 클라이언트는, 정상 조회된 실패 *태스크*를 잘못
    해석합니다. `task.status`로 분기하세요.
  </Accordion>
</AccordionGroup>

<Note>
  이 동작들은 스키마를 읽어서가 아니라 이 API를 실제로 호출해서 확인했습니다. 공개 스펙과 실제
  응답이 다르면 이 문서는 실제 응답을 따릅니다.
</Note>

## 알맞은 `taskType` 고르기

지금 엔진별 엔드포인트를 호출하고 있다면 엔진 이름은 다음 `taskType`에 대응합니다.

| 기존 호출 대상 | `taskType` |
| - | - |
| ChatGPT | `CHATGPT` |
| Perplexity | `PERPLEXITY` |
| Gemini | `GEMINI` |
| Google AI 모드 | `AIMODE` |
| Google AI 개요 | `GOOGLE` |
| 네이버 | `NAVER_AI_BRIEF` / `NAVER_AI_TAB` |

<Note>
  `GOOGLE`이 "AI 개요"를 뜻하는 것은 명명 관례일 뿐 Google 제품명이 아닙니다. 응답은 `aioverview`를
  nullable 멤버로 가진 SERP 봉투입니다. [GOOGLE 응답 형태](/ko/engines/overview)를 참고하세요.
</Note>

## 전환 검증

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