En-têtes de requête

Trois en-têtes optionnels reconnus par la passerelle : deux transportent votre contexte de trace jusqu'à nos journaux, un maintient une conversation sur le même fournisseur pour que la mise en cache des prompts continue de faire mouche. Ne rien envoyer ne change rien.

Comment les envoyer

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

En-têtes que d’autres outils envoient déjà

Quand un appel ne porte aucun de nos trois en-têtes, la passerelle lit l’en-tête équivalent qu’un agent de code, un SDK ou un standard de tracing envoie déjà : ces exécutions sont regroupées dans Traces sans rien changer de votre côté.

Notre propre en-tête l’emporte toujours quand les deux sont présents. Session-Id et X-Codex-Turn-Metadata ne sont lus que depuis la CLI Codex, et X-Interaction-Id que depuis GitHub Copilot, reconnus à leur User-Agent. Un appel sans aucun ID de trace reçoit l’ID de requête de la passerelle dans X-Trace-Id.

Sur /v1/chat/completions et /v1/responses, l’ID de session peut aussi être envoyé dans le corps, dans session_id (avec le SDK OpenAI, via extra_body). Un en-tête l’emporte, et le champ est retiré avant l’envoi de la requête au fournisseur.

OpenClaw envoie traceparent à chaque appel de modèle : ses exécutions sont regroupées en traces sans réglage ; pour les sessions, activez compat.sendSessionAffinityHeaders sur le modèle. Open WebUI envoie l’identifiant de la conversation et celui de l’utilisateur une fois ENABLE_FORWARD_USER_INFO_HEADERS activé ; les en-têtes de nom et d’e-mail qui les accompagnent ne sont pas lus. Un agent qui n’envoie rien de tout cela (Cursor, Aider, Cline, Continue et la plupart des frameworks d’agents) a besoin de X-Session-Id dans ses en-têtes personnalisés.

W3C Trace Context et Baggage

traceparent donne la trace et, par son parent id, le span ; une instrumentation HTTP OpenTelemetry l’ajoute d’elle-même. Le reste voyage dans baggage, sous les noms d’OpenTelemetry : session.id ou gen_ai.conversation.id pour la session, gen_ai.agent.id et gen_ai.agent.name pour l’agent, user.id pour l’utilisateur final. C’est à votre code de les y placer : un SDK OpenTelemetry ne copie pas les attributs de span dans le baggage. Le nom d’un agent est conservé comme son type et accepte lettres, chiffres, ., _ et -. tracestate n’est pas lu.

Les agents d’une session

Un agent de code qui lance des sous-agents indique quel agent a fait chaque appel. La passerelle conserve cette information avec l’appel : une session montre ainsi son coût par agent, et une trace montre quels appels étaient des compactions ou des appels annexes, et quels outils ont tourné entre deux appels. Aucun de ces en-têtes ne change le routage : un sous-agent reste sur l’upstream de sa session.

Claude Code envoie les ID d’agent par défaut. Il n’envoie le type d’appel et les durées d’exécution des outils que si CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 est défini là où il s’exécute.

Conservé : les ID, le type d’un agent, le type d’appel, et le nom des outils avec leur durée d’exécution en millisecondes. Non conservé : le nom que vous avez donné à un agent, et tout ce qu’un outil a lu ou écrit.

Étiqueter une requête

Envoyez X-Synthorai-Metadata avec un objet JSON de chaînes pour dire à quoi sert une requête : une fonctionnalité, un environnement, l’un de vos utilisateurs. Les libellés apparaissent sur la requête dans les journaux, filtrent les journaux, les traces et les sessions (metadata.feature = checkout), sont totalisés dans Analytics, Breakdown, et partent avec vos exports.

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

Jusqu’à 10 libellés. Une clé compte 1 à 32 caractères parmi a-z 0-9 _ . - ; une valeur est une chaîne de 128 octets au plus. _user désigne l’utilisateur final pour lequel la requête a été faite ; toute autre clé commençant par un tiret bas est réservée. Un libellé qui enfreint une règle est écarté et la requête s’exécute quand même : la réponse cite les clés écartées dans X-Synthorai-Metadata-Dropped.

Les libellés sont conservés avec la requête aussi longtemps que le journal des requêtes, et le filtrage par libellé couvre les 90 derniers jours. N’y mettez ni texte de prompt, ni données personnelles, ni secrets ; une valeur qui ressemble à un identifiant est enregistrée comme [redacted]. Ils ne sont jamais transmis au fournisseur.

Affinité de session

Une entrée de cache vit sur une seule clé API chez le fournisseur. Un canal peut détenir plusieurs clés et, sans indication, la passerelle répartit les appels entre elles : le deuxième tour d'une conversation peut atterrir sur une clé qui n'a jamais vu votre préfixe et repayer le coût d'écriture.

Envoyez la même valeur à chaque appel d'une conversation, et une valeur différente pour une autre conversation. Rien n'est stocké côté serveur et rien n'expire : la valeur est hachée pour choisir le canal et la clé, si bien qu'une même valeur aboutit toujours au même endroit.

Sur les deux points de terminaison compatibles OpenAI - /v1/chat/completions et /v1/responses - vous pouvez omettre l'en-tête : si le corps de la requête contient prompt_cache_key, la passerelle s'en sert comme clé d'affinité. Sur /v1/messages et les points de terminaison Gemini, envoyez l'en-tête.

L'affinité est au mieux : elle ne décide que du canal choisi parmi des candidats de même rang. Le basculement, le refroidissement après limitation, les reprises et une préférence de routage explicite priment toujours sur elle. Le prix catalogue d'un modèle est le même sur tous les canaux que nous pouvons choisir.

Limites

• 128 octets chacun. Au-delà, la valeur est tronquée. Une valeur contenant des caractères de contrôle ou hors ASCII imprimable est entièrement rejetée : ni renvoyée, ni journalisée. Ces valeurs finissent dans un en-tête de réponse et une ligne de journal, ce qui écarte l'injection d'en-tête et de journal.
• Ils s'arrêtent à la passerelle. Aucun des trois n'est transmis au fournisseur du modèle : la requête sortante ne porte que l'authentification, le type de contenu et les en-têtes propres au fournisseur.
• Aucun ne sert d'identifiant de facturation. Facturation, déduplication et rapprochement s'appuient tous sur le X-Request-ID de la passerelle, jamais sur une valeur que vous contrôlez.

En cas de problème

• Indiquez le X-Trace-Id que vous avez envoyé, ou le X-Request-ID de la réponse : l'un ou l'autre nous permet de retrouver l'appel exact.
• Votre ID de trace figure sur l’appel dans les journaux et dans Traces : vous pouvez retrouver l’appel avant d’ouvrir un ticket.
• Pour vérifier que l’affinité fonctionne, envoyez plusieurs fois le même préfixe long avec un seul X-Session-Id et regardez les colonnes de cache dans les journaux : le premier appel écrit dans le cache, les suivants doivent y lire. Changez la valeur et l’écriture doit réapparaître.

Voir aussi : Prompt Caching · Traces et sessions