요청 헤더

게이트웨이가 인식하는 선택적 헤더 3개: 두 개는 자체 트레이스 컨텍스트를 당사 로그까지 전달하고, 하나는 같은 대화를 동일한 업스트림에 고정해 prompt caching이 계속 적중하게 합니다. 보내지 않아도 동작은 달라지지 않습니다.

헤더	게이트웨이 동작	용도
`X-Trace-Id`	응답에 그대로 반환하고 액세스 로그에 기록합니다.	호출을 자체 트레이싱 시스템과 연결.
`X-Span-Id`	응답에 그대로 반환하고 액세스 로그에 기록합니다.	해당 트레이스 내 하나의 span을 식별.
`X-Session-Id`	그대로 반환합니다. 같은 값을 가진 연속 요청은 동일한 채널과 동일한 업스트림 키에 고정됩니다.	대화 전반에서 prompt caching을 계속 활용.
`X-Request-ID`	클라이언트 값을 신뢰하지 않습니다. 보낸 값은 `X-Client-Request-ID`로 반환되며, 응답의 `X-Request-ID`는 항상 게이트웨이가 생성한 UUIDv7입니다.	게이트웨이 측 호출 식별자입니다. 문의 시 이 값을 알려주세요.

보내는 방법

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

세션 어피니티

캐시 항목은 공급사 측 하나의 API 키에 묶입니다. 한 채널이 여러 키를 가질 수 있고, 힌트가 없으면 게이트웨이는 호출을 분산시킵니다. 그래서 대화의 두 번째 턴이 접두사를 본 적 없는 키에 도달해 쓰기 비용을 다시 지불하게 됩니다.

한 대화의 모든 호출에 같은 값을 보내고, 다른 대화에는 다른 값을 사용하세요. 서버에는 아무것도 저장되지 않고 만료도 없습니다. 값을 해시해 채널과 키를 고르므로 같은 값은 항상 같은 곳으로 해석됩니다.

/v1/chat/completions와 /v1/responses 두 OpenAI 호환 엔드포인트에서는 헤더를 생략해도 됩니다. 요청 본문에 prompt_cache_key가 있으면 게이트웨이가 이를 어피니티 키로 사용합니다. /v1/messages와 Gemini 엔드포인트에서는 헤더를 보내세요.

어피니티는 best-effort입니다. 우선순위가 같은 후보 중 어느 것을 고를지만 결정하며, 장애 조치·레이트 리밋 쿨다운·재시도·명시적 라우팅 설정이 모두 우선합니다. 모델의 정가는 저희가 선택할 수 있는 어느 채널에서나 동일합니다.

제한

각 128바이트. 초과분은 잘립니다. 제어 문자나 출력 가능한 ASCII 범위를 벗어난 값이 포함되면 전체가 폐기되어 반환도 기록도 되지 않습니다. 이 값들은 응답 헤더와 로그 줄에 들어가므로 헤더·로그 인젝션을 막습니다.
게이트웨이에서 멈춥니다. 세 헤더 모두 모델 공급사로 전달되지 않습니다. 아웃바운드 요청은 인증, 콘텐츠 타입, 공급사 전용 헤더만 담습니다.
어느 것도 과금 식별자가 아닙니다. 과금, 중복 제거, 대사는 모두 게이트웨이 자체 X-Request-ID를 기준으로 하며 클라이언트가 제어하는 값은 쓰지 않습니다.

문제가 생겼을 때

보낸 X-Trace-Id 또는 응답의 X-Request-ID를 알려주세요. 둘 중 하나면 해당 호출을 찾을 수 있습니다.
트레이스 ID는 콘솔의 사용량 분석에서도 해당 요청에 표시되므로 문의 전에 직접 확인할 수 있습니다.
어피니티가 동작하는지 확인하려면 같은 X-Session-Id로 동일한 긴 프리픽스를 여러 번 보내고 사용량 분석의 Cache R·Cache W 열을 보세요. 첫 호출은 캐시 쓰기, 이후 호출은 읽기여야 합니다. 값을 바꾸면 쓰기가 다시 나타납니다.