> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hingnet.com.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 请求追踪（Request ID）

> 如何使用请求 ID 追踪 API 调用、排查问题与提交工单

## 概述

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

<Info>无需额外配置，请求 ID 会自动包含在每个 API 响应中。</Info>

## 响应头说明

每次 API 调用的响应中会包含以下 Header：

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

## 错误响应中的请求 ID

当请求失败时，响应体的 JSON 中也会包含请求 ID：

```json theme={null}
{
  "error": {
    "message": "错误描述...",
    "type": "error_type",
    "request_id": "20260320153045abcdefgh",
    "upstream_request_id": "req_abc123..."
  }
}
```

| 字段                          | 含义         |
| --------------------------- | ---------- |
| `error.request_id`          | 平台请求 ID    |
| `error.upstream_request_id` | 上游供应商请求 ID |

## 如何获取请求 ID

### 通过 curl

```bash theme={null}
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

```python theme={null}
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

```javascript theme={null}
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}`);
```

## 使用场景

<CardGroup cols={3}>
  <Card title="提交工单" icon="ticket">
    遇到问题时，将平台请求 ID 附在工单中，可大幅加速排查效率。
  </Card>

  <Card title="上游追溯" icon="arrow-up-right-from-square">
    需要向上游供应商反馈问题时，提供 `X-Upstream-Request-Id` 作为追溯依据。
  </Card>

  <Card title="程序化处理" icon="code">
    在代码中捕获请求 ID，写入自己的日志系统，实现端到端链路追踪。
  </Card>
</CardGroup>

<Tip>建议在生产环境中记录每次 API 调用的请求 ID，便于事后排查。</Tip>