Cabeçalhos de requisição

Três cabeçalhos opcionais que o gateway entende: dois levam o seu contexto de rastreamento até os nossos logs e um mantém uma conversa no mesmo upstream para que o cache de prompts continue acertando. Não enviar nenhum deles não muda nada.

Cabeçalho	O que o gateway faz	Para que serve
`X-Trace-Id`	Devolvido na íntegra na resposta; gravado no log de acesso.	Ligar uma chamada ao seu próprio sistema de tracing.
`X-Span-Id`	Devolvido na íntegra na resposta; gravado no log de acesso.	Identificar um span dentro desse rastreamento.
`X-Session-Id`	Devolvido na íntegra. Requisições consecutivas com o mesmo valor ficam fixas ao mesmo canal e à mesma chave de upstream.	Manter o cache de prompts quente ao longo de uma conversa.
`X-Request-ID`	Não é aceite o seu valor. Ele volta como `X-Client-Request-ID`; o `X-Request-ID` da resposta é sempre o UUIDv7 gerado pelo gateway.	A identidade da chamada no gateway - cite-a em um chamado de suporte.

Como enviá-los

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

Afinidade de sessão

Uma entrada de cache vive numa única chave de API no provedor. Um canal pode ter várias chaves e, sem uma pista, o gateway distribui as chamadas por elas: o segundo turno de uma conversa pode cair numa chave que nunca viu o seu prefixo e pagar de novo o custo de escrita.

Envie o mesmo valor em cada chamada de uma conversa e um valor diferente para outra conversa. Nada é guardado no servidor e nada expira: o valor é submetido a hash para escolher canal e chave, pelo que o mesmo valor resolve sempre da mesma forma.

Nos dois endpoints compatíveis com OpenAI - /v1/chat/completions e /v1/responses - você pode omitir o cabeçalho: se o corpo da requisição tiver prompt_cache_key, o gateway o usa como chave de afinidade. Em /v1/messages e nos endpoints do Gemini, envie o cabeçalho.

A afinidade é best effort: apenas decide qual canal é escolhido entre candidatos igualmente preferidos. Failover, resfriamento por limite de taxa, novas tentativas e uma preferência de roteamento explícita sempre têm prioridade. O preço de tabela de um modelo é o mesmo em qualquer canal que possamos escolher.

Limites

128 bytes cada. Valores maiores são truncados. Um valor com caracteres de controle ou fora do ASCII imprimível é descartado por completo: não é devolvido nem registrado. Esses valores acabam em um cabeçalho de resposta e em uma linha de log, o que impede injeção de cabeçalhos e de logs.
Param no gateway. Nenhum dos três é encaminhado para o provedor do modelo: a requisição de saída leva apenas autenticação, tipo de conteúdo e cabeçalhos próprios do provedor.
Nenhum identifica uma chamada para faturamento. Faturamento, desduplicação e reconciliação se baseiam no X-Request-ID do próprio gateway, nunca em um valor que você controle.

Quando algo corre mal

Indique o X-Trace-Id que enviou ou o X-Request-ID da resposta: qualquer um permite-nos encontrar a chamada exata.
O seu ID de rastreamento também aparece na requisição em Análise de uso, então você pode encontrar a chamada antes de abrir um chamado de suporte.
Para confirmar que a afinidade funciona, envie o mesmo prefixo longo algumas vezes com um único X-Session-Id e observe as colunas Cache R e Cache W na Análise de uso: a primeira chamada grava no cache e as seguintes devem ler dele. Mude o valor e a gravação deve reaparecer.

Ver também: Prompt Caching · Usage Analytics