Skip to main content

​
概述

每次 API 请求，平台都会自动生成一个唯一的 请求 ID，贯穿整个调用链路。该机制适用于 所有 API 接口，包括 Chat、图像生成、视频生成、音频、Embeddings、Rerank 等。
无需额外配置，请求 ID 会自动包含在每个 API 响应中。

​
响应头说明

每次 API 调用的响应中会包含以下 Header：
响应头含义说明
X-Oneapi-Request-Id平台请求 ID平台为本次请求生成的唯一标识
request-id平台请求 ID（别名）与 X-Oneapi-Request-Id 值相同，方便不同客户端读取
X-Upstream-Request-Id上游供应商请求 ID上游 AI 供应商返回的原始请求标识（如有）

​
错误响应中的请求 ID

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

​
如何获取请求 ID

​
通过 curl

curl -i https://models.hingnet.com.cn/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
X-Upstream-Request-Id: req_abc123...

​
Python

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://models.hingnet.com.cn/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")
upstream_request_id = response.headers.get("X-Upstream-Request-Id")

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

​
Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://models.hingnet.com.cn/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");
const upstreamRequestId = response.headers.get("X-Upstream-Request-Id");

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

​
使用场景

提交工单

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

上游追溯

需要向上游供应商反馈问题时，提供 X-Upstream-Request-Id 作为追溯依据。

程序化处理

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