作者注: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 可以加快處理
