リクエストヘッダー

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

送り方

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"}]
  }'

他のツールがすでに送っているヘッダー

呼び出しに当社の 3 つのヘッダーがない場合、ゲートウェイはコーディングエージェント、SDK、トレースの標準仕様がもともと送っている同等のヘッダーを読み取ります。そのため、こうした実行もあなたの側で何も変えずにトレースでグループ化されます。

両方ある場合は、常に当社のヘッダーが優先されます。Session-Id と X-Codex-Turn-Metadata は Codex CLI から、X-Interaction-Id は GitHub Copilot からのリクエストでのみ読み取り、User-Agent で判別します。トレース ID がまったくない呼び出しには、ゲートウェイのリクエスト ID が X-Trace-Id として返されます。

/v1/chat/completions と /v1/responses では、セッション ID をボディの session_id として送ることもできます(OpenAI SDK では extra_body に入れます)。ヘッダーがあればそちらが優先され、このフィールドはプロバイダーに送る前に取り除かれます。

OpenClaw はモデル呼び出しのたびに traceparent を送るため、設定なしで実行がトレースにまとまります。セッション単位でまとめるには、モデルの compat.sendSessionAffinityHeaders を有効にしてください。Open WebUI は ENABLE_FORWARD_USER_INFO_HEADERS を有効にするとチャット ID とユーザー ID を送ります。同時に送られる氏名とメールアドレスのヘッダーは読み取りません。これらを送らないエージェント(Cursor、Aider、Cline、Continue、および多くのエージェントフレームワーク)では、カスタムヘッダーに X-Session-Id を追加してください。

W3C Trace Context と Baggage

traceparent からトレースを、その parent id からスパンを読み取ります。OpenTelemetry の HTTP 自動計装を有効にすると自動で付与されます。それ以外は baggage に OpenTelemetry の名前で入れます。セッションは session.id または gen_ai.conversation.id、エージェントは gen_ai.agent.id と gen_ai.agent.name、エンドユーザーは user.id です。これらはアプリ側のコードで baggage に入れる必要があります。OpenTelemetry SDK はスパン属性を baggage にコピーしません。エージェント名はエージェントの種類として保存され、英数字と .、_、- が使えます。tracestate は読み取りません。

セッション内のエージェント

サブエージェントを起動するコーディングエージェントは、各呼び出しがどのエージェントのものかを伝えます。ゲートウェイはそれを呼び出しと一緒に保存するので、セッションではエージェント別のコストが、トレースではどの呼び出しがコンパクションや補助的な呼び出しだったか、2 つの呼び出しの間にどのツールが動いたかが分かります。これらのヘッダーはルーティングを変えません。サブエージェントはセッションと同じアップストリームに留まります。

Claude Code はエージェント ID を既定で送ります。呼び出しの種類とツールの実行時間は、実行環境で CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 を設定したときだけ送られます。

保存するもの:これらの ID、エージェントの種類、呼び出しの種類、ツール名とミリ秒単位の実行時間。保存しないもの:エージェントに付けた名前、ツールが読み書きした内容。

リクエストにラベルを付ける

X-Synthorai-Metadata に文字列だけの JSON オブジェクトを入れて、そのリクエストが何のためのものか(機能、環境、どのユーザーか)を伝えます。ラベルはログのリクエスト詳細に表示され、ログ・トレース・セッションの絞り込み(metadata.feature = checkout)に使え、Analytics の Breakdown でラベル別に集計され、エクスポートにも含まれます。

curl https://synthorai.io/v1/chat/completions \
  -H "Authorization: Bearer $SYNTHORAI_API_KEY" \
  -H 'X-Synthorai-Metadata: {"feature":"checkout","env":"prod","_user":"u_123"}' \
  -d '{"model":"claude-sonnet-5","messages":[{"role":"user","content":"Hi"}]}'

ラベルは最大 10 個。キーは a-z 0-9 _ . - の 1〜32 文字、値は 128 バイトまでの文字列です。_user はそのリクエストの対象となるエンドユーザーを表し、アンダースコアで始まるほかのキーは予約されています。ルールに合わないラベルは破棄され、リクエストはそのまま実行されます。破棄されたキーはレスポンスの X-Synthorai-Metadata-Dropped に示されます。

ラベルはリクエストログと同じ期間、リクエストとともに保存されます。ラベルでの絞り込みは直近 90 日間が対象です。プロンプトの文面、個人データ、シークレットは入れないでください。認証情報に見える値は [redacted] として保存されます。ラベルがプロバイダーに送られることはありません。

セッションアフィニティ

キャッシュはプロバイダー側の 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 で同じ長いプレフィックスを数回送り、ログのキャッシュ列を見てください。最初の呼び出しはキャッシュへの書き込み、以降は読み取りになるはずです。値を変えると書き込みが再び現れます。

関連: Prompt Caching(プロンプトキャッシュ) · トレースとセッション