更新情報新機能

すべてのAI回答エンジンを1つのAPIにまとめました

API
POST /v1/async/task へのリクエスト、返ってきたキュー内のタスク、webhook で届いた完了タスク

1回のリクエストで対応するAIエンジンに質問を送り、回答を構造化されたJSONとしてwebhookまたはポーリングで受け取れます。

得られる結果

  • すべてのエンジンで共通のエンドポイントPOST /v1/async/taskを使います。taskTypeでエンジンを、countryで市場を選びます。
  • エンジンごとに異なるresponseを共通の形式が包みます。タスクのid、status、日時はいつも同じ場所に入ります。
  • 結果は好きな方法で受け取れます。タスクが終わった瞬間にwebhookでサーバーへ届けるか、必要なときにGET /v1/async/task/{id}で取得します。
  • idempotencyKeyで安全に再試行できます。同じキーで送り直すと、作成済みのタスクがそのまま返ります。

仕組み

AIエンジンの回答には数秒から数分かかるため、すべてのリクエストは確実に保存されるタスクになります。タスクはQUEUEDからPROCESSINGへ進み、回答付きのCOMPLETEDか理由付きのFAILEDで終わります。エンジン側で一時的なエラーが起きるとタスクはキューに戻って再試行されるため、短い不調はお客様に届く前に処理されます。

webhook.urlを指定すると完了したタスクをサーバーへ送信し、約30分のあいだに最大5回まで送ります。完了したタスクは24時間ポーリングでも取得できるため、webhookとポーリングを組み合わせればすべての結果を確実に受け取れます。

活用例

  • 自社のバックエンドから好きな頻度でブランドの露出を確認できます。
  • 同じ質問を複数のエンジンに送り、回答を並べて比較できます。
  • 時間のかかる処理もシンプルです。送信したら次の作業に移り、結果はwebhookが届けます。

リクエストを送る

API キーを 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"
  }'

リクエストのフィールド

taskTypestring必須
実行するエンジン。CHATGPT や GOOGLE などを指定します。
payloadobject必須
エンジンへの入力。prompt または query に、country とエンジンごとのオプションを加えます。
webhook.urlstring
サーバーの HTTPS アドレス。タスクが完了した瞬間に結果をここへ送ります。
idempotencyKeystring
リクエストに付ける独自の ID。1つのキーはアカウント内で1つのタスクを作るため、再送してもタスクは1つのままです。

レスポンス

呼び出すと QUEUED のタスクがすぐに返ります。credits はタスクが終わるまで0で、idempotencyKey は送った値のまま返ります。

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

結果を受け取る

status が COMPLETED か FAILED になるまで、数秒ごとに GET /v1/async/task/{id} でタスクを取得します。結果はタスクの完了から24時間取得できます。

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

完了したタスクには、差し引かれた credits とエンジンの response が入ります。実際のタスクを、長さを抑えて抜粋しています。

JSON
{
  "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 を経て、回答付きの COMPLETED か error 付きの FAILED で終わります。
credits.creditsChargedinteger
完了したタスクに請求されたクレジット。失敗したタスクは0です。

Webhook

webhook.url を指定すると、完了したタスクが取得時と同じ task、credits、response を持つ POST としてサーバーに届きます。失敗したタスクも同じ形で、response.error と差し引き0クレジットを持って届きます。すべての配信に3つの署名ヘッダーが付きます。

querying-webhook-idstring
タスク ID。配信は少なくとも1回届くため、この値で重複を取り除いてください。
querying-webhook-timestampstring
配信に署名した時刻（Unix 秒）。直近5分以内に署名された配信を受け付けてください。
querying-webhook-signaturestring
v1, に続けて、{id}.{timestamp}.{body} の base64 HMAC-SHA256。鍵は API キーの SHA-256 ダイジェストです。

本文をパースする前に、受け取ったままの本文で署名を確かめ、一致した配信を受け付けます。

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)

30秒以内に 2xx のステータスで応答してください。それ以外の応答や30秒を超えた場合は、2分、4分、8分、16分後に再配信し、合計5回試みます。どの試行にも同じ querying-webhook-id が付きます。

エラー

拒否されたリクエストは、success が false で、code、message、フィールドのエラーでは details を持つ error をすぐに返します。キューの外で終わるため、クレジットは0です。

VALIDATION_ERRORHTTP 400
フィールドが欠けているか、範囲外の値です。details に該当するフィールドが入ります。
MISSING_API_KEYHTTP 401
Authorization ヘッダーが欠けているか、キーが誤っている、期限切れ、または無効化済みです。
INSUFFICIENT_CREDITSHTTP 402
残高がタスクの料金を下回っています。クレジットを追加するかプランを上げてから、もう一度送ってください。
KEY_SCOPE_DENIEDHTTP 403
キーの「許可するエンジン」の対象外のエンジンです。別のキーを使うか、「キーを管理」でエンジンを追加してください。
RESOURCE_ALREADY_EXISTSHTTP 409
この idempotencyKey のタスクがすでにアカウントにあるため、タスクは1件のままです。バッチではその項目を成功として扱います。
PAYLOAD_TOO_LARGEHTTP 413
本文が 1 MiB を超えています。バッチは 8 MiB まで受け付けます。
REGION_UNSUPPORTEDHTTP 422
country がエンジンの対応国の外にあります。再送しても同じ結果になるため、details.retryable は false です。
PLAN_CONCURRENCY_LIMITHTTP 429
待機中と実行中のタスクがプランの上限に達しました。無料プランは2件、Basic は10件、Pro は25件、Scale は50件、Max は100件です。Retry-After 秒後に再送してください。
KEY_DAILY_CREDIT_LIMITHTTP 429
キーが「1日のクレジット上限」に達しました。Retry-After は次の UTC 午前0時までです。
QUEUE_BACKPRESSUREHTTP 429
エンジンのキューが一時的に満杯です。Retry-After 秒後に再送してください。

料金

エンジンごとにクレジット単価が決まっており、タスクの完了時に課金されます。失敗したタスクは予約していたクレジットを返却します。

ほかの更新

最新情報を受け取る

製品の更新をメールでお届けします。

RSS フィード