Session Persistence

Problem Phenomenon

When you initiate multiple rounds of conversation requests using different accounts (or different Clients), you may encounter request failures or context loss. This is because the server cannot automatically identify which requests belong to the same conversation.

Solution: Add Session Identifier

You only need to add a parameter to the HTTP Header of each request — X-Conversation-Id, whose value is the session ID you customize (please be sure to use the same ID for all requests in the same conversation).

Examples of Interface Calls

1. GPT Response Interface (Streaming Output)

curl --location --request POST 'https://genaiapi.cloudsway.net/v1/ai/{your endpoint}/responses' \
--header 'Authorization: Bearer {your ak}' \
--header 'X-Conversation-Id: conversation-test1' \
--header 'Content-Type: application/json' \
--data-raw '{
  "input": "Tell me another brain teaser with the answer. Return all of them together.",
  "previous_response_id": "resp_04825fd1c08c48820069c12ebdd7948190ac42abb8234f1a83",
  "stream": true
}'

2. Chat Completion API (unified style, supporting GPT / Claude / Gemini)

curl --location --request POST 'https://genaiapi.cloudsway.net/v1/ai/{your endpoint}/chat/completions' \
--header 'Authorization: Bearer {your ak}' \
--header 'X-Conversation-Id: conversation-test1' \
--header 'Content-Type: application/json' \
--data-raw '{    
    "messages": [
        {
            "role":"user",
            "content":"hi"
        }
    ]
}'

3. Claude Native Interface (Cache Control Supported)

If you are using the Claude model and wish to further optimize the caching effect, you can refer to the following examples:

curl --location --request POST 'https://genaiapi.cloudsway.net/{your endpoint}/v1/messages' \
--header 'Authorization: Bearer {your ak}' \
--header 'X-Conversation-Id: conversation-test1' \
--header 'Content-Type: application/json' \
--data-raw '{
    "model": "MaaS_Cl_Opus_4.7_20260416_cache",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "long context",
            "cache_control": {
                "type": "ephemeral"
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Analyze the major themes in Pride and Prejudice."
        }
    ]
}'

Improve cache hit rate

Besides resolving the issue of interrupted conversations, X-Conversation-Idhas another hidden capability — helping improve the cache hit rate. This means that:

• The model has a faster response speed

• Duplicate content does not need to be counted repeatedly, saving Token consumption

The caching mechanisms for different model series are as follows:

Model Series	Caching Method	What you need to do
Claude	Explicit caching (to be used with cache_control)	Use the same X-Conversation-Idfor the same session, and add the cache_controlflag to the message as needed
GPT series	Implicit Cache (Automatically Managed by the Server)	Just ensure that the same X-Conversion-Idis used within the same session
Gemini Series	Implicit Cache (Automatically Managed by the Server)	Just ensure that the same X-Conversion-Idis used within the same session

Notes	Description
Session ID Uniqueness	Please use a different X-Conversation-Idfor each independent conversation. The recommended format is conversation-{User Identification}-{session number}
Cross-account Isolation	Even if different accounts use the same session ID, their contexts will not interfere with each other (as accounts are inherently isolated by nature).
ID Persistence	It is recommended to save the session ID on the Client so that users can continue the same conversation next time.
Cache coherence	To make full use of the cache, please ensure that the content structure of requests in the same session remains stable