Cache & Request Affinity

Updated: 2026-07-02

Long-context requests often rely on prompt caching. For more stable cache behavior, requests from the same project, session, or task should carry a stable cache or affinity identifier when your client supports it.

Quick Answer

X-Affinity-Key is an HTTP request header, not a JSON request body field. You can add it only when your client, SDK, proxy tool, or web client supports custom headers.

X-Affinity-Key: project-or-session-id

Use a project ID, session ID, workspace ID, or another stable string. Do not use a random value that changes on every request.

HTTP / curl

If you send HTTP requests directly, put X-Affinity-Key in the request headers:

curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Affinity-Key: project-or-session-id" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {
        "role": "user",
        "content": "Continue the task."
      }
    ]
  }'

For native Claude /v1/messages requests, it also belongs in the request headers:

curl https://api.example.com/v1/messages \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Affinity-Key: project-or-session-id" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Continue the task."
      }
    ]
  }'

OpenAI-Compatible Requests

If your tool uses an OpenAI-compatible endpoint, there are two common options:

• X-Affinity-Key: put it in the HTTP request headers.
• prompt_cache_key: put it in the JSON request body.

{
  "model": "gpt-5.4",
  "prompt_cache_key": "project-or-session-id",
  "messages": [
    {
      "role": "user",
      "content": "Continue the task."
    }
  ]
}

If the client supports both custom headers and request body parameters, you can send both:

X-Affinity-Key: project-or-session-id

{
  "model": "gpt-5.4",
  "prompt_cache_key": "project-or-session-id",
  "messages": [
    {
      "role": "user",
      "content": "Continue the task."
    }
  ]
}

OpenAI SDK

When using an SDK, X-Affinity-Key usually belongs in default headers or per-request headers.

JavaScript example:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.API_KEY,
  baseURL: "https://api.example.com/v1",
  defaultHeaders: {
    "X-Affinity-Key": "project-or-session-id"
  }
});

await client.chat.completions.create({
  model: "gpt-5.4",
  prompt_cache_key: "project-or-session-id",
  messages: [
    {
      role: "user",
      content: "Continue the task."
    }
  ]
});

Python example:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.example.com/v1",
    default_headers={
        "X-Affinity-Key": "project-or-session-id",
    },
)

client.chat.completions.create(
    model="gpt-5.4",
    prompt_cache_key="project-or-session-id",
    messages=[
        {
            "role": "user",
            "content": "Continue the task.",
        }
    ],
)

Native Claude Requests

Native Claude requests use /v1/messages. If the request contains a long and repeated system prompt, tool definition, or context block, add cache_control to the stable content block.

cache_control belongs in the stable request body block. X-Affinity-Key belongs in the request headers. They are different locations.

X-Affinity-Key: project-or-session-id

{
  "model": "claude-opus-4-8",
  "max_tokens": 1024,
  "metadata": {
    "user_id": "stable-user-or-session-id"
  },
  "system": [
    {
      "type": "text",
      "text": "Long stable system prompt or project context...",
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "Continue the task."
    }
  ]
}

Use at least one of the following whenever possible:

• A stable metadata.user_id in the request body.
• A stable X-Affinity-Key request header.
• A stable Session_id request header.
• A stable content block marked with cache_control.

Claude Desktop / Claude Code / Cherry Studio

Whether these tools can set the value depends on whether the tool exposes custom headers or advanced request settings.

Check in this order:

• Look for Custom Headers, Headers, or equivalent advanced settings in the Provider, API Endpoint, or model provider configuration.
• If available, add header name X-Affinity-Key and set the value to a stable project, session, or workspace identifier.
• If the tool supports a Claude / Anthropic provider, prefer that provider.
• If the tool converts Claude requests into OpenAI format, it may drop native Claude cache_control.
• If the tool does not support custom headers, metadata, or cache parameters, you cannot force this from the tool side; cache behavior will depend on gateway fallback behavior and the request content itself.

Example setting:

Header Name: X-Affinity-Key
Header Value: project-or-session-id

Third-Party Proxy, Switcher, or Web Tools

If you use a third-party proxy, model switcher, web client, or browser-based chat tool, confirm whether it preserves headers and request body fields.

• If the tool supports custom headers, add X-Affinity-Key.
• If the tool supports OpenAI-compatible request body parameters, add prompt_cache_key.
• If the tool supports native Claude requests, make sure it does not drop cache_control or metadata.
• If the tool only provides a normal chat input box with no header or advanced parameter settings, you usually cannot manually set cache or affinity identifiers.

How to Check

After sending long-context requests, check the usage logs for cache reads, cache creation, and whether long-running task requests remain stable. Short-context requests usually do not show visible cache benefits.