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.

En-tête	Ce que fait la passerelle	À quoi ça sert
`X-Trace-Id`	Renvoyé tel quel dans la réponse ; écrit dans le journal d'accès.	Rattacher un appel à votre propre système de tracing.
`X-Span-Id`	Renvoyé tel quel dans la réponse ; écrit dans le journal d'accès.	Identifier un span précis dans cette trace.
`X-Session-Id`	Renvoyé tel quel. Les requêtes successives portant la même valeur sont épinglées au même canal et à la même clé amont.	Garder la mise en cache des prompts efficace sur toute une conversation.
`X-Request-ID`	Non repris de votre côté. Votre valeur revient dans `X-Client-Request-ID` ; le `X-Request-ID` de la réponse est toujours l'UUIDv7 généré par la passerelle.	L'identifiant de l'appel côté passerelle : à citer dans un ticket de support.

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

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 identifiant de trace apparaît aussi sur la requête dans les statistiques d'utilisation, ce qui vous permet de 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 Cache R et Cache W dans l'analyse d'utilisation : 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 · Usage Analytics