すべてのリクエストには引用できる ID があります

2026年10月26日 · Hyperouter · 読了目安 4 分

リクエストが想定外の動作をしたときに、状況を最も早く伝える方法は、その ID です。Hyperouter が受け付けたすべてのリクエストには ID があり、レスポンスで返され、そのリクエストの記録を引くキーになります。

ID の場所

ID は UUID で、ドキュメントではリクエスト ID と呼びます。レスポンスのボディにあり、エンドポイントごとに名前が異なります。

ドキュメントには、リクエスト ID を返すレスポンスヘッダーはありません。ID はボディから読み取ってください。 ご自身のコードで、呼び出しとあわせて ID をログに残します。

res = client.chat.completions.create(
    model="x-ai/grok-4.7",
    messages=[{"role": "user", "content": "Hello"}],
)
log.info("hyperouter request %s cost=%s", res.id, res.usage.cost)

const res = await client.chat.completions.create({
  model: "x-ai/grok-4.7",
  messages: [{ role: "user", content: "Hello" }],
});
console.log("hyperouter request", res.id);

usage.cost は Hyperouter が usage オブジェクトに追加したフィールドのため、型付きの SDK では宣言されていないことがあります。値は JSON に含まれています。

調べる

GET /v1/generations/{id} は、種類を問わず、お客様のリクエストの記録を返します。

curl https://api.hyperouter.app/v1/generations/0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21 \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY"

記録には、kind（chat、image、video）、model、status（queued、submitting、running、done、failed）、created_at と finished_at、usage とその cost、ttft_ms と latency_ms が含まれ、リクエストが失敗した場合は code と message を持つ error も含まれます。完了したチャットリクエストでは、provider_name がどのプロバイダーが処理したかを示します。画像と動画では、outputs に署名付きリンク（24 時間有効）が入り、リクエストから 30 日間利用できます。

プロバイダーがトークン数を送ってこず、Hyperouter が数えた場合は、usage_estimated が true になります。

プロンプトと生成テキストは記録に含まれません。Hyperouter は、どの API やダッシュボードのページを通じても、それらを返しません。

UUID ではない ID、存在しない ID、他のアカウントの ID には 404 not_found が返ります。読み取れるのは、ご自身のリクエストだけです。

チケットで引用する

課金、チャージ、API に関するご質問は、ダッシュボードでチケットを作成してください。スタッフが同じスレッドで返信します。特定のリクエストについて報告する際は、レスポンスの id を添えてください。

有用な報告には、ID、期待した結果、実際の結果の 3 点が含まれています。GET /v1/generations/{id} から得られる場合は、ステータスと error も貼り付けてください。ID があれば、スタッフはリクエストの状況をお尋ねすることなく、リクエストそのものを探せます。

エラーのレスポンスに ID が含まれていない場合は、代わりにそのステータス、code、リクエストの時刻を添えてください。

利用額を突き合わせる

同じ ID で、リクエストにいくらかかったかもわかります。usage.cost は USD の課金額で、JSON の数値です。ご自身のデータベースで各ジョブに ID を保存しておけば、お客様の記録と Hyperouter の記録を 1 対 1 で突き合わせられます。チャット、画像、動画のいずれも同じ方法で扱えます。

次のステップ

• 生成履歴に、記録のすべてのフィールドを掲載しています。
• Idempotency-Key で安全にリトライするでは、チャットの再送に対する 409 が最初のリクエストの ID を返す仕組みを説明しています。
• 対処できるエラーでは、エラーオブジェクトと error.generation_id を説明しています。