作者注:API易 Request ID 查询文档已升级。本文讲清报错时该复制哪一串、哪些 ID 不能用、异步视频 task_id 怎么存,以及日志查不到时要补哪些材料。
调用报错后提工单,开发者常卡在同一个问题上:手上明明有一串 ID,客服在日志里却搜不到。原因通常是复制了 上游原厂的 X-Request-Id,而不是 API易 自己的 X-Shellapi-Request-Id。新版文档就是为解决这个问题重写的,地址是 docs.apiyi.com/faq/request-id-troubleshooting。
这不是一次换皮式的文档更新。旧版从“响应头”讲起,满篇“通常”“可能”,看完仍不知道去哪复制。新版把顺序倒了过来:先给答案,再给取法,最后给工单模板。
核心价值:读完本文,你能在 10 秒内拿到正确的 Request ID,也能认出哪些 ID 是错的。日志里查不到记录时,你也知道该补哪些材料。

API易 Request ID 文档升级改了什么
新版文档的第一句话就是答案:API易 的 Request ID 就是响应头里的 X-Shellapi-Request-Id,报错时错误消息末尾也会带上同一个值。旧页面里几处把 x-request-id 当成“记下来方便排查”的表述,这次也顺手修正了。
| 信息项 | 详情 |
|---|---|
| 更新时间 | 2026-11-16 |
| 文档位置 | FAQ 栏目「Request ID 排查」新版页面 |
| 核心答案 | Request ID = 响应头 X-Shellapi-Request-Id,报错 message 末尾 (request id: ...) 是同一个值 |
| 新增内容 | 2 种取法、ID 对照表、控制台日志不显示 ID、异步视频说明、查不到时怎么办、工单模板 |
| 安全说明 | Request ID 不是密钥,可以贴进工单、聊天和截图;不能外发的是 sk- 开头的完整 API Key |
| 影响人群 | 所有在 API易 调用文本、图像、Embedding、Claude Messages、Responses、异步视频接口的开发者 |
按文档原文,这个响应头的名字不区分大小写。成功请求、业务报错和流式请求都会返回它,流式请求的响应头在第一个数据块之前就会到达。异步视频接口的提交和查询也都会返回。
API易 Request ID 现在该复制哪一串:两条路径
先认格式:API易 的 Request ID 以 14 位 UTC 时间开头。例如 2026111602224568279882196e93ae3kTS58ypN,前 14 位 20261116022245 就是 2026-11-16 02:22:45 UTC,也就是北京时间 10:22:45。用这个前缀和自己的调用时间对一下,基本能判断有没有拿错。

路径一:从报错 JSON 里直接复制
这一条适合大多数客户端用户。报错时,错误 JSON 的 message 字段末尾会带一段 (request id: ...),把括号里那串完整复制下来即可。
- 在客户端或日志输出里找到完整的报错 JSON。
- 定位
message字段的末尾。 - 复制
request id:后面的整串字符,不要截断。
控制台日志:能确认调用,但不显示 Request ID
很多人第一反应是去控制台“日志”页找 ID。新版文档专门写了一节:日志页不显示 X-Shellapi-Request-Id,也没有按它搜索的入口。
日志里能看到的是时间、模型、令牌名、流式/非流式、耗时、状态、输入/输出 token、费用、分组、倍率、IP。这些足够确认这次调用有没有到达 API易、走的哪个模型、扣了多少钱,但没法拿来当报障定位。
所以报障时,ID 只有两个来源:报错原文(路径一)和响应头(路径二)。日志用来补时间、模型、令牌和费用这几项材料。
路径二:在代码里读响应头
做自动化报错收集时,建议在代码里直接记录这个头。所有方式的 Base URL 都应是 https://api.apiyi.com/v1。
- cURL:加
curl -D headers.txt把响应头写进文件,再在文件里找x-shellapi-request-id。临时排查也可以用curl -i直接打印。 - Python requests:拿到响应对象后读
r.headers.get("x-shellapi-request-id")。成功和报错时都可以读。 - OpenAI SDK(Python):普通返回值里的
_request_id读的是x-request-id,在 API易 上通常为空。正确做法是改用client.chat.completions.with_raw_response.create(...),读raw.headers.get("x-shellapi-request-id"),再用raw.parse()拿结果。报错时在except openai.APIStatusError as e里读e.response.headers。 - Node.js:用 fetch 时读
res.headers.get("x-shellapi-request-id")。 - Postman:发送请求后打开响应区的 Headers 标签,找到
X-Shellapi-Request-Id。 - 浏览器前端:跨域调用受 CORS 限制,JS 读不到这个头。可以在后端代理里记录,或者在开发者工具 Network → 该请求 → Response Headers 里查看。
🚀 快速上手:想确认自己的代码能读到这个头,可以用 API易 apiyi.com 的令牌发一次最小请求,看能否打印出以 14 位时间开头的 ID。这一步会消耗少量 token,建议选输出很短的提示词。
哪些 ID 不是 API易 Request ID
一次响应里可能同时出现好几种“ID”,很多工单就卡在这一步。新版文档列了一张对照表,下面把要点整理出来。

| 字段 | 来源 | 能否用于报障查日志 | 识别特征 |
|---|---|---|---|
| X-Shellapi-Request-Id | API易 | ✅ 就是它 | 14 位 UTC 时间开头 |
| X-Oneapi-Request-Id | 中间层 | ❌ | 头名不同 |
| X-Request-Id | 上游原厂 | ❌ 在 API易 日志里搜不到 | 常见 req_ 开头或 UUID |
| 其他渠道自定义头 | 渠道 | ❌ | 头名各异 |
响应体 id |
Completion ID / Response ID | ❌ | chatcmpl-、resp_ 开头 |
图片 generation_id |
生图结果 | ❌ | 在响应体里 |
task_id |
异步任务 | ❌ 不是 Request ID,但要一起提供 | 查任务、查扣费用 |
判断规则很简单:开头不是 14 位时间的,都不是 API易 的 Request ID。如果拿到的是 req_ 开头的 ID,请求可能直接打到了 OpenAI 官方。这时先检查 Base URL 是否写成了 https://api.apiyi.com/v1。
异步视频的 task_id 与 Request ID 怎么分开存
异步视频有“提交”和“查询”两步,每一步都会返回新的 X-Shellapi-Request-Id,再加上一个任务 ID,容易混在一起。新版文档的建议是:提交请求的 Request ID 和轮询用的任务 ID 分开保存。
| 模型 | 任务 ID 位置 | 查询接口 | 易混字段 |
|---|---|---|---|
| Seedance | 响应体顶层 id(字段不叫 task_id) |
GET /seedance/api/v3/contents/generations/tasks/{id} |
— |
| Wan / HappyHorse | output.task_id |
GET /v1/tasks/{task_id} |
响应体里的 request_id 是上游的,不是 API易 日志里的那个 |
实际存储时,建议每个任务保存 3 个字段:提交时的 X-Shellapi-Request-Id、任务 ID、提交时间。查询任务时返回的 Request ID 可以按需记录。提交失败时报障用 Request ID;任务卡住或扣费有疑问时,查任务和查扣费都要用到任务 ID。
Request ID 在日志里查不到时补什么
拿到了 ID,日志里也不一定查得到。新版文档把“控制台日志里没有 Request ID”单独列了一节,另外几种找不到的情况可以对照处理。
| 情况 | 原因 | 该补什么 |
|---|---|---|
| 请求在收到响应前就失败 | DNS、TCP/TLS、代理拒绝、客户端超时,根本没有响应头 | 报错原文、调用时间、网络环境说明 |
| 客户端只显示“请求失败” | 客户端没透出原始报错 | 按路径一或路径二取 ID;日志只能确认调用是否到达 |
ID 是 req_ 开头 |
可能打到了 OpenAI 官方 | 检查 Base URL 后重试 |
| 日志里也搜不到 | 超出保留期,或拿错了 ID | 核对 ID 格式;日志只保留当月和此前两个自然月 |
另外一点:控制台页面不显示 ID,但日志查询 API 能按 request_id 查。下表是 2026-11-16 的一次真实调用核对,模型为 deepseek-flash 和 gpt-image-2,请求发往 https://api.apiyi.com/v1。
| 调用 | HTTP 状态 | 响应头 | 日志按 request_id 查询结果 |
|---|---|---|---|
| deepseek-flash 非流式 | 200 | 有 x-shellapi-request-id,没有 x-request-id | 精确查回 1 条消费记录 |
| deepseek-flash 流式 | 200 | 有,第一个 data: 块之前就能读到 |
— |
| gpt-image-2,size=999×999 | 400 | 与 message 末尾的 request id 同值 | 3 行错误/重试记录,没有消费行 |
| 不存在的模型名 | 503 | 与 message 末尾的 request id 同值 | 一行都查不到 |
结论是:控制台日志页不显示 Request ID,但日志查询 API 能按 request_id 查到“消费行”和“错误行”,而且不能保证每次都有。请求已经到达渠道、再在渠道侧失败的(例如参数错误),会留下错误行。在网关层当场被拒绝的(例如无可用渠道),可能一行都没有。查不到时,用响应头或报错原文里的 ID,加上调用时间来补材料。
如果客服需要复现,可以在 API易 apiyi.com 上用同一个令牌、同一组参数再调一次,或者换一个模型对比是不是同一个报错。复现也会消耗 token,记得把每次复现的 Request ID 一并记录。
🎯 排查建议:复现报错时,把 Base URL 固定为
https://api.apiyi.com/v1,每次都记录 X-Shellapi-Request-Id 和调用时间。之后把 ID 和调用时间一起给客服,由后台按 ID 查,能更快确认错误发生在网关层还是渠道层。
API易 Request ID 报错工单模板
以下字段直接复制到工单里填写即可:
- Request ID:以 14 位时间开头的那串
- 模型:如 gpt-image-2
- 接口:如 POST /v1/chat/completions
- 时间:带时区,如 2026-11-16 11:24:04 UTC+8
- HTTP 状态:如 400 / 503
- 错误信息:粘贴完整报错,包含
(request id: ...) - 已尝试:如已换模型、已检查 Base URL、已重试 2 次
- task_id(仅异步视频):提交返回的任务 ID
注意两点:不要发完整的 API Key;请求体或图片里有隐私内容的,先脱敏再提交。
Request ID 文档升级对开发者的影响
对开发者的影响
- 报障少走一轮:一次就给对 ID,客服不用再回头追问。
- SDK 用户不再拿到空值:明确了
_request_id的坑和with_raw_response的取法。 - 视频任务可追溯:Request ID 和任务 ID 分开存,查任务、查扣费都有依据。
看旧文档时要注意
部分接口能力页、新闻页和报错留存类页面里,仍然把 x-request-id 写成“记录这个方便排查”的对象。遇到这类说法时,以新版 Request ID 这一页为准。代码模板里的 x-request-id 也请替换成 x-shellapi-request-id。
常见问题 FAQ
Q1:API易 Request ID 到底是哪一个?
是响应头里的 X-Shellapi-Request-Id,以 14 位 UTC 时间开头。报错时,错误 message 末尾 `(request id: …)` 里的值和它相同。
Q2:Request ID 发给别人安全吗?
安全。按文档原文,Request ID 不是密钥,可以贴进工单、聊天或截图。不能外发的是 `sk-` 开头的完整 API Key。
Q3:OpenAI SDK 读出来的 ID 为什么是空的?
SDK 默认的 `_request_id` 读的是 x-request-id。改用 `with_raw_response`,或者从 `APIStatusError` 的响应头里取 x-shellapi-request-id 即可。
Q4:如何快速验证自己能拿到正确的 Request ID?
1. 在 API易 apiyi.com 注册并获取 API Key,新用户有免费测试额度。
2. 把 Base URL 设为 `https://api.apiyi.com/v1`,发一次最小请求。
3. 打印 x-shellapi-request-id,确认每次调用都能拿到这串 ID;日志页只能核对这次调用有没有到达和扣费,不显示 ID。
Q5:三个月前的报错还能查吗?
一般查不到。日志保留当月和此前两个自然月,更早的记录需要靠自己保存的 Request ID 和报错原文来说明。
API易 Request ID 核心要点 Key Takeaways
- 唯一正确的 ID:X-Shellapi-Request-Id,以 14 位 UTC 时间开头
- 两条取法:报错 message 复制、代码读响应头(日志只能确认调用,不显示 ID)
- 常见错拿:X-Request-Id、
req_、chatcmpl-、resp_、UUID 都不能用于报障 - 视频要存两个:提交的 Request ID 和任务 ID 分开保存
- 日志不是百分百:控制台页面不显示 ID;网关当场拒绝的请求可能连记录都没有,要补报错原文和时间
- 上手验证:在 API易 apiyi.com 发一次最小请求,即可确认能读到这个头
总结
API易 Request ID 查询文档这次升级,核心就三件事:
- 答案前置:Request ID 就是 X-Shellapi-Request-Id,报错 message 末尾也有同一个值。
- 错 ID 排除:对照表列清了中间层、上游、响应体和任务 ID 的区别。
- 查不到有预案:四种情况分别补什么材料,附可直接使用的工单模板。
建议现在就把代码里的报错日志字段改成 x-shellapi-request-id。之后遇到问题,把 ID 和调用时间一起给客服,由后台按 ID 查,再带着完整材料提交工单。
📚 参考资料
- API易 Request ID 排查文档(新版):本文的事实依据
- 链接:
docs.apiyi.com/faq/request-id-troubleshooting -
说明:包含两种取法、控制台日志说明、ID 对照表、异步视频说明和工单模板
-
日志保存多久:日志保留期说明
- 链接:
docs.apiyi.com/faq/log-retention-policy - 说明:确认报错记录还能不能查到
作者:APIYI 技术团队
技术交流:欢迎在 API易 apiyi.com 网站首页联系我们,提交工单时附上 X-Shellapi-Request-Id 可以加快处理
