跳转至

请求链路追踪

请求链路追踪 (X-Request-id) 使用说明

为了实现请求的全链路追踪并大幅提升异常排查的效率，我们强烈建议您在每次发送 API 请求时，在 HTTP Header 中携带 X-Request-id 参数。

1. 参数说明

  • Header 参数名：X-Request-id

  • 值要求：每次请求必须保证全局唯一。推荐使用标准的 UUID v4（例如：123e4567-e89b-12d3-a456-426614174000），或者使用带有业务前缀的唯一字符串（例如：xxx-20231025-123456789）。

2. 作用与优势

  • 快速定位问题：当您遇到 API 报错、响应异常或需要核对特定的请求信息时，只需将该次请求对应的 X-Request-id 提供给我们的技术支持团队。

  • 精准查询日志：我们将通过这个唯一的 ID，在系统后台快速提取该笔请求的完整流转记录和底层日志，从而为您提供更快速、准确的解决方案。

3. 请求示例 (cURL)

curl --location 'https://genaiapi.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/chat/completions' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--header 'X-Request-id: {您的唯一请求ID，如：550e8400-e29b-41d4-a716-446655440000}' \
--data '{
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "hi"
                }
            ]
        }
    ],
    "model": "gemini-3-pro",
    "stream": false
}'

⚠️ 注意事项：请勿在不同的请求中重复使用同一个 X-Request-id，否则可能会导致日志关联混乱，影响后续的问题排查。