> ## 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.

# 既存連携の移行

> 定数を2つ変えるだけ。その後、挙動が異なる箇所を確認してください。

この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">
    キー単位のレート制限はありません。大量のリクエストはバッチ送信で往復回数を減らしてください。

    [地域とベストプラクティス](/ja/engines/capacity)を参照してください。
  </Accordion>

  <Accordion title="2. クレジットはエンジンごと" icon="coins">
    `credits` はエンベロープの一部としてすべてのレスポンスに含まれます。送信とポーリングのレスポンスは
    `{ "creditsToCharge": 0, "creditsCharged": 0 }` を報告し、Webhookはエンジンごとのクレジットコスト
    (エンジンにより1–3クレジット)を報告します。

    失敗したタスクには課金しません。クレジット残高はダッシュボードで確認できます。
  </Accordion>

  <Accordion title="3. 一部のエンジン × 地域の組み合わせは即時拒否" icon="ban">
    まったく提供できない組み合わせが1つあります。`CHATGPT`/`PERPLEXITY`/`GEMINI` を `CN` に向ける場合で、
    出口の供給がなくリクエストが対象に届きません。受け付けずに即座に `422 REGION_UNSUPPORTED` で失敗します。
    同じ状況の一時的なものは `422 REGION_UNAVAILABLE` です。

    正しい形式の送信はすべて受け付けられると想定しているクライアントには、ここで分岐が必要です。
    [地域](/ja/engines/capacity)を参照してください。
  </Accordion>

  <Accordion title="4. includeフラグはほとんど効果なし" icon="toggle-left">
    `payload.include` フラグは受け付けますが、ここのほとんどのエンジンは固定形のレスポンスを返し、フラグを
    無視します。すべてのフラグに従うのは ChatGPT だけで、`GEMINI` は `markdown` と `rawResponse` のみに従います。

    たとえば Gemini に `html` を要求しても、エラーもフィールドもなく黙って無視されます。
    [フラグ対応表](/ja/engines/overview)を参照してください。
  </Accordion>

  <Accordion title="5. ステータスコードが1つ追加: 422" icon="hash">
    それ以外のエラー処理は一般的です。検証失敗は `400`、`401` は `MISSING_API_KEY`、`404` は
    `RESOURCE_NOT_FOUND` を報告し、`details` が問題のフィールドを示します。

    追加は上で説明した `422` の2つ(`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 | `NAVER_AI_BRIEF` / `NAVER_AI_TAB` |

<Note>
  `GOOGLE` が「AI による概要」を意味するのは命名上の慣例で、Google の製品名ではありません。レスポンスは
  `aioverview` をnullableメンバーとして持つSERPエンベロープです。[GOOGLE のレスポンス形](/ja/engines/overview)を参照してください。
</Note>

## 切り替えの検証

しばらく既存の連携とこの連携を並行稼働させ、実際に使うフィールドを比較してください。実務上は
`response.text`、`response.sources[]`、`response.markdown` です。シャドー比較は、値は入っているが順序が
異なるソース一覧のように、スキーマチェックでは捉えられない形の差異を捉えます。