Skip to main content

​
概述

每次 API 请求，平台都会为本次调用分配一个 请求 ID，用于追踪 API 调用、排查问题与提交工单。该机制适用于 所有 API 接口，包括 Chat、图像生成、视频生成、音频、Embeddings、Rerank 等。
无需额外配置，请求 ID 会自动包含在每个 API 响应中。

​
响应头说明

每次 API 调用的响应中会包含以下 Header：
响应头含义说明
X-Oneapi-Request-Id平台请求 ID平台为本次请求分配的唯一标识
request-id平台请求 ID（别名）与 X-Oneapi-Request-Id 值相同，方便不同客户端读取

​
自定义请求 ID

如果你的系统已经有自己的链路追踪 ID，可以在请求头中传入：
请求头说明
X-Oneapi-Request-Id推荐使用；平台会优先采用该值
request-id兼容别名；当未传入 X-Oneapi-Request-Id 时采用
平台会去除首尾空白；如果传入值为空或长度超过 128 字符，平台会重新生成请求 ID。

​
错误响应中的请求 ID

当请求失败时，响应体的 JSON 中也会包含请求 ID： 
{
  "error": {
    "message": "错误描述...",
    "type": "error_type",
    "request_id": "20260320153045abcdefgh"
  }
}
字段含义
error.request_id平台请求 ID

​
如何获取请求 ID

​
通过 curl

curl -i https://models.kapon.cloud/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
响应头中可以看到： 
X-Oneapi-Request-Id: 20260320153045abcdefgh
request-id: 20260320153045abcdefgh

​
Python

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://models.kapon.cloud/v1"
)

response = client.chat.completions.with_raw_response.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)

# 从响应头获取请求 ID
platform_request_id = response.headers.get("X-Oneapi-Request-Id")

print(f"平台请求 ID: {platform_request_id}")

​
Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://models.kapon.cloud/v1",
});

const response = await client.chat.completions
  .create({
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello" }],
  })
  .asResponse();

// 从响应头获取请求 ID
const platformRequestId = response.headers.get("X-Oneapi-Request-Id");

console.log(`平台请求 ID: ${platformRequestId}`);

​
使用场景

提交工单

遇到问题时，将平台请求 ID 附在工单中，可大幅加速排查效率。

链路追踪

在请求头中传入自己的追踪 ID，可将平台调用与你的内部日志关联起来。

程序化处理

在代码中捕获请求 ID，写入自己的日志系统，实现端到端链路追踪。
建议在生产环境中记录每次 API 调用的请求 ID，便于事后排查。