Synthorai
新規 無料登録、10回の呼び出しを進呈。最大 $1、カード不要。

リクエストヘッダー

ゲートウェイが解釈する 3 つの任意ヘッダー:2 つは自前のトレースコンテキストを当社ログまで引き継ぎ、1 つは同じ会話を同一のアップストリームに固定して prompt caching を継続的にヒットさせます。いずれも省略可能で、送らなくても動作は変わりません。

ヘッダー ゲートウェイの挙動 用途
X-Trace-Id レスポンスにそのまま返し、アクセスログに記録します。 呼び出しを自前のトレーシング基盤に突き合わせる。
X-Span-Id レスポンスにそのまま返し、アクセスログに記録します。 そのトレース内の 1 つの span を識別する。
X-Session-Id そのまま返します。同じ値を持つ連続リクエストは同一チャネル・同一アップストリームキーに固定されます。 会話全体で prompt caching を効かせ続ける。
X-Request-ID クライアント値は採用しません。送った値は X-Client-Request-ID として返り、レスポンスの X-Request-ID は常にゲートウェイが生成した UUIDv7 です。 ゲートウェイ側での呼び出しの識別子。問い合わせの際はこれを伝えてください。

送り方

curl https://synthorai.io/v1/chat/completions \
  -H "Authorization: Bearer $SYNTHORAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Session-Id: conv-8f3a2b" \
  -H "X-Trace-Id: 7c1d9e40f2b84a17" \
  -H "X-Span-Id: 2f9b41c8" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

セッションアフィニティ

キャッシュはプロバイダー側の 1 つの API キーに紐づきます。1 つのチャネルが複数のキーを持つことがあり、手がかりがなければゲートウェイはリクエストを分散させます。その結果、会話の 2 ターン目があなたのプレフィックスを見たことのないキーに当たり、書き込みコストを再び支払うことになります。

1 つの会話のすべての呼び出しで同じ値を送り、別の会話には別の値を使ってください。サーバー側には何も保存されず、有効期限もありません。値をハッシュしてチャネルとキーを選ぶため、同じ値は常に同じ先に解決されます。

/v1/chat/completions と /v1/responses の 2 つの OpenAI 互換エンドポイントではヘッダーを省略できます。リクエストボディに prompt_cache_key があれば、ゲートウェイはそれをアフィニティキーとして使います。/v1/messages と Gemini のエンドポイントではヘッダーを送ってください。

アフィニティはベストエフォートです。同順位の候補の中でどれを選ぶかを決めるだけで、フェイルオーバー・レート制限のクールダウン・リトライ・明示的なルーティング指定はいずれもこれより優先されます。モデルの定価は、当社が選びうるどのチャネルでも同じです。

制限

  • 各 128 バイトまで。超過分は切り捨てられます。制御文字や印字可能 ASCII 以外を含む値は丸ごと破棄され、返却もログ記録もされません。これらの値はレスポンスヘッダーとログ行に入るため、ヘッダー/ログインジェクションを防ぎます。
  • ゲートウェイで止まります。3 つともモデルプロバイダーには転送されません。送信リクエストが持つのは認証・コンテンツタイプ・各社固有ヘッダーだけです。
  • いずれも課金上の識別子ではありません。課金・重複排除・突合はすべてゲートウェイ自身の X-Request-ID を基準とし、クライアントが操作できる値は使いません。

問題が起きたとき

  • 送信した X-Trace-Id か、レスポンスの X-Request-ID を伝えてください。どちらでも該当の呼び出しを特定できます。
  • トレース ID はコンソールの利用状況分析でも当該リクエストに表示されるため、問い合わせ前に自分で確認できます。
  • アフィニティが効いているか確かめるには、同じ X-Session-Id で同じ長いプレフィックスを数回送り、利用状況分析の Cache R・Cache W 列を見てください。最初の呼び出しはキャッシュへの書き込み、以降は読み取りになるはずです。値を変えると書き込みが再び現れます。

関連: Prompt Caching(プロンプトキャッシュ) · Usage Analytics