Cabeceras de solicitud

Tres cabeceras opcionales que la pasarela entiende: dos llevan tu 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ías ninguna, nada cambia.

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

Cabeceras que otras herramientas ya envían

Cuando una llamada no lleva ninguna de nuestras tres cabeceras, la pasarela lee la cabecera equivalente que ya envía un agente de programación, un SDK o un estándar de trazas, así que esas ejecuciones se agrupan en Trazas sin cambiar nada por tu parte.

Si están ambas, siempre gana nuestra cabecera. Session-Id y X-Codex-Turn-Metadata solo se leen de la CLI de Codex, y X-Interaction-Id solo de GitHub Copilot, reconocidos por su User-Agent. Una llamada sin ningún ID de traza recibe el ID de solicitud de la pasarela como X-Trace-Id.

En /v1/chat/completions y /v1/responses, el id de sesión también puede ir en el cuerpo, como session_id (con el SDK de OpenAI, en extra_body). Una cabecera tiene prioridad, y el campo se elimina antes de enviar la solicitud al proveedor.

OpenClaw envía traceparent en cada llamada al modelo, así que sus ejecuciones se agrupan en trazas sin configurar nada; para las sesiones, activa compat.sendSessionAffinityHeaders en el modelo. Open WebUI envía el id del chat y el del usuario cuando ENABLE_FORWARD_USER_INFO_HEADERS está activo; las cabeceras de nombre y correo que los acompañan no se leen. Un agente que no envía nada de esto (Cursor, Aider, Cline, Continue y la mayoría de los frameworks de agentes) necesita X-Session-Id en sus cabeceras personalizadas.

W3C Trace Context y Baggage

traceparent da la traza y, con su parent id, el span; una instrumentación HTTP de OpenTelemetry lo añade por sí sola. Lo demás viaja en baggage, con los nombres de OpenTelemetry: session.id o gen_ai.conversation.id para la sesión, gen_ai.agent.id y gen_ai.agent.name para el agente, user.id para el usuario final. Tu código tiene que ponerlos ahí: un SDK de OpenTelemetry no copia los atributos de span al baggage. El nombre de un agente se guarda como su tipo y admite letras, dígitos, ., _ y -. tracestate no se lee.

Agentes dentro de una sesión

Un agente de código que inicia subagentes indica qué agente hizo cada llamada. La pasarela lo guarda junto con la llamada: así, una sesión muestra su costo por agente, y una traza muestra qué llamadas fueron compactaciones o llamadas auxiliares y qué herramientas se ejecutaron entre dos llamadas. Ninguna de estas cabeceras cambia el enrutamiento: un subagente sigue en el upstream de su sesión.

Claude Code envía los ids de agente de forma predeterminada. El tipo de llamada y los tiempos de ejecución de las herramientas solo los envía si CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 está definido donde se ejecuta.

Se guarda: los ids, el tipo de un agente, el tipo de llamada y los nombres de las herramientas con sus tiempos de ejecución en milisegundos. No se guarda: el nombre que diste a un agente ni nada de lo que una herramienta leyó o escribió.

Etiquetar una solicitud

Envía X-Synthorai-Metadata con un objeto JSON de cadenas para indicar para qué era una solicitud: una función, un entorno, uno de tus usuarios. Las etiquetas aparecen en la solicitud en los registros, filtran registros, trazas y sesiones (metadata.feature = checkout), se suman en Analytics, Breakdown, y salen con tus exportaciones.

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

Hasta 10 etiquetas. Una clave tiene de 1 a 32 caracteres de a-z 0-9 _ . -; un valor es una cadena de hasta 128 bytes. _user indica el usuario final para el que se hizo la solicitud; cualquier otra clave que empiece por guion bajo está reservada. Una etiqueta que incumple una regla se descarta y la solicitud se ejecuta igualmente: la respuesta indica las claves descartadas en X-Synthorai-Metadata-Dropped.

Las etiquetas se conservan con la solicitud tanto tiempo como el registro de solicitudes, y el filtrado por etiqueta cubre los últimos 90 días. No pongas en ellas texto de prompts, datos personales ni secretos; un valor que parece una credencial se guarda como [redacted]. Nunca se envían al proveedor.

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ía 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 - puedes 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ía 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 tú controles.

Cuando algo falla

• Indica el X-Trace-Id que enviaste o el X-Request-ID de la respuesta: con cualquiera localizamos la llamada exacta.
• Tu ID de traza aparece en la llamada dentro de Registros y de Trazas, así que puedes localizarla antes de abrir un ticket.
• Para comprobar que la afinidad funciona, envía varias veces el mismo prefijo largo con un único X-Session-Id y observa las columnas de caché en Registros: la primera llamada escribe en la caché y las siguientes deberían leer de ella. Cambia el valor y la escritura debería reaparecer.

Véase también: Prompt Caching · Trazas y sesiones