Cabeceras de solicitud

Tres cabeceras opcionales que la pasarela entiende: dos llevan su propio contexto de traza hasta nuestros registros y una mantiene una conversación en el mismo proveedor para que la caché de prompts siga acertando. Si no envía ninguna, nada cambia.

Cabecera	Qué hace la pasarela	Para qué sirve
`X-Trace-Id`	Se devuelve tal cual en la respuesta y se escribe en el registro de acceso.	Vincular una llamada con su propio sistema de trazas.
`X-Span-Id`	Se devuelve tal cual en la respuesta y se escribe en el registro de acceso.	Identificar un span concreto dentro de esa traza.
`X-Session-Id`	Se devuelve tal cual. Las solicitudes consecutivas con el mismo valor se fijan al mismo canal y a la misma clave del proveedor.	Mantener caliente la caché de prompts durante una conversación.
`X-Request-ID`	No se toma el suyo. Su valor vuelve como `X-Client-Request-ID`; el `X-Request-ID` de la respuesta es siempre el UUIDv7 que genera la pasarela.	La identidad de la llamada en la pasarela: cítela en un ticket de soporte.

Cómo enviarlas

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

Afinidad de sesión

Una entrada de caché vive en una sola clave de API del proveedor. Un canal puede tener varias claves y, sin una pista, la pasarela reparte las llamadas entre ellas: el segundo turno de una conversación puede caer en una clave que nunca vio su prefijo y pagar otra vez el coste de escritura.

Envíe el mismo valor en cada llamada de una conversación y uno distinto para otra conversación. No se guarda nada en el servidor ni caduca nada: el valor se somete a hash para elegir canal y clave, así que el mismo valor siempre resuelve igual.

En los dos endpoints compatibles con OpenAI - /v1/chat/completions y /v1/responses - puede omitir la cabecera: si el cuerpo lleva prompt_cache_key, la pasarela lo usa como clave de afinidad. En /v1/messages y los endpoints de Gemini, envíe la cabecera.

La afinidad es de mejor esfuerzo: solo decide qué canal se elige entre candidatos igual de preferentes. La conmutación por error, el enfriamiento por límite de tasa, los reintentos y una preferencia de enrutado explícita siempre tienen prioridad. El precio de lista de un modelo es el mismo en cualquier canal que podamos elegir.

Límites

128 bytes cada una. Los valores más largos se truncan. Un valor con caracteres de control o fuera del ASCII imprimible se descarta por completo: ni se devuelve ni se registra. Estos valores acaban en una cabecera de respuesta y en una línea de registro, así que esto evita la inyección de cabeceras y de registros.
Se detienen en la pasarela. Ninguna de las tres se reenvía al proveedor del modelo: la solicitud saliente solo lleva autenticación, tipo de contenido y cabeceras propias del proveedor.
Ninguna identifica una llamada a efectos de facturación. Facturación, deduplicación y conciliación se basan en el X-Request-ID de la pasarela, nunca en un valor que usted controle.

Cuando algo falla

Indique el X-Trace-Id que envió o el X-Request-ID de la respuesta: con cualquiera localizamos la llamada exacta.
Su ID de traza también aparece en la solicitud dentro de Analíticas de uso, así que puede localizar la llamada antes de abrir un ticket.
Para comprobar que la afinidad funciona, envíe varias veces el mismo prefijo largo con un único X-Session-Id y observe las columnas Cache R y Cache W en el análisis de uso: la primera llamada escribe en la caché y las siguientes deberían leer de ella. Cambie el valor y la escritura debería reaparecer.

Véase también: Prompt Caching · Usage Analytics