摘要:本文用 OpenAI Python SDK 以非流式方式調用騰訊混元 Hy4 API,跑通第一個純文本請求,並說明怎樣驗收結果、估算費用、覈對賬單和處理常見報錯。
直接答案:騰訊混元 Hy4 API 可以通過 API易 的 OpenAI 兼容接口接入。準備三項配置即可發出首個請求:
- Key:在
api.apiyi.com/token創建,放在環境變量APIYI_API_KEY中。 - SDK Base URL:
https://api.apiyi.com/v1。 - 模型 ID:
hy4。
對應的 HTTP 端點是 POST https://api.apiyi.com/v1/chat/completions。截至 2026-11-21,定價表中 Hy4 每百萬 token 的價格爲:未命中緩存的輸入 $0.85,輸出 $2.55,緩存讀取 $0.045。實際計費以 API易 定價表爲準,地址是 docs.apiyi.com/models(騰訊分類)。
時間線如下:騰訊在 11 月 4 日發佈 Hy4 正式版,11 月 20 日開放權重。API易 在權重開放之前已經上架該型號,上架公告見 docs.apiyi.com/news/hy4-launch。公告中已有流式示例,所以本文只講另外四件事:非流式調用、結果驗收、賬單核對和失敗排障。公告提到 Hy4 支持圖片輸入,本文只演示純文本。視頻、Responses 接口和 Computer Use 都不在本文範圍內,文中也沒有任何實測數據。

騰訊混元 Hy4 API 接入的知識地圖與閱讀順序
整個流程分四步,前一步的產出就是後一步的輸入。建議按編號順序閱讀。第 4 節可以在報錯時單獨查閱。
| 步驟 | 對應正文 | 爲什麼放在這裏 | 驗收標準 |
|---|---|---|---|
| 準備請求 | 1.1、1.2 | 端點、模型名和 Key 寫錯,後面的步驟都會失敗 | SDK 能導入,環境變量能讀到 Key,代碼裏沒有明文 Key |
| 首次調用 | 2.1、2.2 | 先用一條不含客戶數據的短文本確認鏈路通了 | 返回內容爲“產品=混元、版本=Hy4”,沒有截斷,並保存了 usage 和 request ID |
| 覈對賬單 | 3.1、3.2 | 鏈路通了以後再估算成本,用來判斷能否放大調用量 | 估算值與控制檯消費日誌能逐項對上 |
| 失敗排障 | 4 | 任一步失敗時,按錯誤碼和錯誤體定位原因 | 能分清配置錯誤、權限問題、限流和超時,並判斷是否可以重試 |

To Know:Hy4 API 相關術語
| 術語 | 簡明解釋 |
|---|---|
| 非流式(stream=False) | 模型生成完畢後一次性返回完整結果,便於整體檢查內容和用量 |
| finish_reason | 本次生成結束的原因。stop 表示正常結束,length 表示達到長度上限被截斷 |
| usage | 響應中的 token 用量字段,常見的有 prompt_tokens(輸入)和 completion_tokens(輸出) |
| request ID | 單次請求的標識,用於在日誌中定位這次調用。並非每次響應都一定帶有 |
| 緩存讀取 | 輸入中命中緩存的部分,按單獨的緩存讀取價計費 |
| 分組(Default/SVIP) | 令牌所屬的分組,決定這個令牌可以調用哪些模型 |
1. 準備騰訊混元 Hy4 API 請求
1.1 配置 Hy4 模型與端點
請先把配置項逐一覈對清楚。大部分首次調用失敗都出在這一步。
| 配置項 | 取值 | 說明 |
|---|---|---|
| SDK base_url | https://api.apiyi.com/v1 |
只寫到 /v1,SDK 會自動拼接 /chat/completions |
| HTTP 端點 | POST https://api.apiyi.com/v1/chat/completions |
不使用 SDK、直接發 HTTP 請求時用這個地址 |
| 模型 ID | hy4 |
正式版的型號名,按小寫原樣填寫 |
| 可用分組 | Default、SVIP | 令牌所在分組需要包含 Hy4 |
| 輸出方式 | stream=False |
本文全程使用非流式 |
最常見的錯誤是把完整端點填進了 base_url。SDK 會在這個地址後面再拼一次 /chat/completions,導致路徑重複,最後返回 404。兼容接口的完整說明見 docs.apiyi.com/api-capabilities/openai/compatible。
1.2 安裝 OpenAI SDK 並安全保存 Key
官方 Python SDK 的項目地址是 github.com/openai/openai-python。建議在虛擬環境中安裝,避免和系統中已有的包版本衝突:
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install openai
Key 在 api.apiyi.com/token 創建。創建時請確認令牌所屬分組可以調用 Hy4。拿到 Key 後寫入當前終端的環境變量,不要寫進代碼文件:
export APIYI_API_KEY="你的令牌" # Windows PowerShell: $env:APIYI_API_KEY="你的令牌"
管理 Key 時注意以下幾點:
- 代碼只通過
os.environ['APIYI_API_KEY']讀取 Key。沒有設置環境變量時,用getpass交互輸入,輸入內容不會回顯在屏幕上。 - 如果用
.env文件保存 Key,要把它加入.gitignore,避免提交到倉庫。 - 截圖、日誌或工單中出現 Key 時,先替換成
sk-***之類的掩碼。
驗收:在終端運行 python -c "import openai, os; print(openai.__version__, bool(os.environ.get('APIYI_API_KEY')))"。輸出版本號和 True,說明這一步完成了。
2. 用 OpenAI SDK 發出首個 Hy4 請求
2.1 完整非流式 Python 示例
這個首次請求只做一件簡單的事:從一句公開的話中提取產品名和版本號,不含任何客戶數據。這樣設計有兩個好處。一是輸出很短,成本低。二是答案唯一,容易判斷對錯。
import os
import re
from getpass import getpass
from openai import OpenAI
key = os.environ.get("APIYI_API_KEY") or getpass("輸入 APIYI_API_KEY:")
PROMPT = "僅從這句話提取產品和版本:騰訊混元 Hy4 正式版已上線。請只寫一行:產品=…;版本=…"
with OpenAI(
base_url="https://api.apiyi.com/v1", # API易 OpenAI 兼容接口
api_key=key,
timeout=60.0,
max_retries=0, # 關閉自動重試,失敗時由人工判斷是否重發
) as client:
result = client.chat.completions.create(
model="hy4",
messages=[{"role": "user", "content": PROMPT}],
stream=False,
)
request_id = getattr(result, "_request_id", None)
print("request_id:", request_id if request_id else "響應未提供")
if not result.choices:
raise SystemExit("未通過:choices 爲空,沒有返回正文")
choice = result.choices[0]
content = (choice.message.content or "").strip()
print("finish_reason:", choice.finish_reason)
print("content:", content)
usage = getattr(result, "usage", None)
prompt_tokens = getattr(usage, "prompt_tokens", None) if usage else None
completion_tokens = getattr(usage, "completion_tokens", None) if usage else None
print("prompt_tokens:", prompt_tokens if prompt_tokens is not None else "缺失(不按 0 處理)")
print("completion_tokens:", completion_tokens if completion_tokens is not None else "缺失(不按 0 處理)")
def accept(text: str, finish_reason) -> tuple[bool, str]:
if not text:
return False, "正文爲空"
if finish_reason == "length":
return False, "輸出被截斷"
t = re.sub(r"\s+", "", text)
t = t.replace(":", "=").replace(":", "=").replace(";", ";")
prod = re.search(r"產品=([^;\n]+)", t)
ver = re.search(r"版本=([^;\n]+)", t)
if not prod or not ver:
return False, "缺少產品或版本字段"
strip_punct = lambda s: re.sub(r"[。..,,、!!??\"“”'‘’]", "", s)
if "混元" not in strip_punct(prod.group(1)):
return False, f"產品值錯誤:{prod.group(1)}"
if strip_punct(ver.group(1)) != "Hy4":
return False, f"版本值錯誤:{ver.group(1)}"
return True, "通過"
ok, reason = accept(content, choice.finish_reason)
print("驗收:", reason)
示例中的幾項設置需要說明:
max_retries=0關閉了 SDK 的自動重試。第 4 節會講到,超時以後服務端可能已經執行完請求,自動重發可能造成重複計費,所以重試與否要由人來判斷。with語句會在調用結束後關閉連接。- usage 字段缺失時,代碼明確打印“缺失”,不會當作 0 處理,避免後面算賬時漏掉費用。
響應結構的更多說明見 docs.apiyi.com/api-capabilities/openai/response-handling。
2.2 首次 Hy4 請求的驗收標準
驗收時只看 message.content 中的兩個字段:產品值包含“混元”,版本值是“Hy4”。全角或半角的冒號、分號,以及句末標點的差異都可以接受。下面是一行符合要求的輸出,這是示意格式,不是實測回包:
產品=騰訊混元;版本=Hy4
以下幾種情況一律判爲不通過,不能因爲“看起來差不多”就放行:
| 情況 | 判定 | 原因 |
|---|---|---|
| choices 爲空,或 content 爲空字符串 | 不通過 | 沒有拿到正文,說明鏈路並沒有真正跑通 |
finish_reason 爲 length |
不通過 | 輸出被截斷,結果不完整 |
| 版本寫成 Hy3、Hunyuan 等其他值 | 不通過 | 字段值錯誤 |
| 只有標點、空格或冒號的全半角不同 | 通過 | 屬於允許的格式差異 |
驗收通過後,把 request ID(如果響應中有)、請求時間、模型名、prompt_tokens 和 completion_tokens 記錄下來。3.2 節覈對賬單時會用到這些信息。
3. 估算並覈對 Hy4 API 費用
3.1 按定價表估算一次批量任務
首次請求的輸入很短,花費可以忽略不計,用它來估算成本意義不大。下面換成一個與示例短請求無關的假設場景:某次任務輸入 10 萬 token,全部未命中緩存,輸出 2 萬 token。輸入和輸出分別按各自的單價計算:
| 計費項 | 假設用量 | 單價(每百萬 token) | 費用 |
|---|---|---|---|
| 未命中緩存輸入 | 100,000 | $0.85 | $0.085 |
| 輸出 | 20,000 | $2.55 | $0.051 |
| 合計 | — | — | $0.136 |
計算過程是 0.1 × 0.85 + 0.02 × 2.55 = 0.136。估算時要注意兩點:
- 輸出單價是未命中輸入單價的 3 倍。輸出量較大的任務,成本主要由輸出決定。
- 如果 completion_tokens 已經包含模型的思考部分,就不要再單獨加一次思考的費用,否則會重複計算。
3.2 區分緩存桶與實際消費日誌
“緩存讀取”是一個單獨計費的部分,但不同響應中字段的拆分方式未必相同,所以沒有一個普遍適用的字段名可以保證結果精確。可靠的做法是先在賬單中確認:命中緩存的 token 是否已經計入總輸入。
如果賬單確認緩存部分已經包含在總輸入中,就從總輸入里扣除一次緩存部分,再分別計價。下面沿用 3.1 的假設,並進一步假設 10 萬輸入中有 4 萬命中緩存:
| 計費項 | 假設用量 | 單價(每百萬 token) | 費用 |
|---|---|---|---|
| 未命中緩存輸入 | 60,000 | $0.85 | $0.051 |
| 緩存讀取 | 40,000 | $0.045 | $0.0018 |
| 輸出 | 20,000 | $2.55 | $0.051 |
| 合計 | — | — | $0.1038 |

估算值只能作爲參考,最終以消費日誌爲準。覈對方法是在控制檯 api.apiyi.com/log 中篩選出對應的記錄:
- 按請求時間縮小範圍。
- 如果響應提供了 request ID,用它精確定位到這一次請求。
- 確認模型爲
hy4,令牌與代碼實際使用的令牌一致。 - 對比日誌中的輸入、緩存、輸出用量和扣費金額,看與估算值是否一致。
日誌字段的具體含義見 docs.apiyi.com/faq/log-billing-explained。
4. Hy4 API 失敗排障
排障時先看 HTTP 狀態碼,再讀錯誤體中的具體信息。只看狀態碼容易判斷錯誤,比如同樣是 429,原因可能完全不同。在第 2.1 節的原請求處捕獲 SDK 異常:連接超時看 APITimeoutError,其他連接失敗看 APIConnectionError;拿到錯誤響應時,從 APIStatusError 記錄 status_code、request_id 和錯誤體。先判斷現有請求結果,再決定要不要重試;反饋前給錯誤體脫敏。處理順序如下:
| 錯誤 | 優先檢查 | 是否重試 |
|---|---|---|
| 401 | Key 是否正確、是否已失效,以及 base_url 是否爲 https://api.apiyi.com/v1 |
修正配置前不要重試 |
| 403 | 根據錯誤體判斷是否爲分組權限問題,確認令牌所在分組包含 Hy4 | 修正權限前不要重試 |
| 404 | 路徑是否重複拼接了 /chat/completions,模型名是否爲 hy4 |
修正配置前不要重試 |
| 429 | 根據錯誤體判斷是臨時限流還是額度不足 | 臨時限流可以有限次退避重試,額度不足需要先充值或調整額度 |
| 連接錯誤 | 網絡、代理、DNS 是否正常,以及 base_url 的協議和域名是否正確 | 網絡恢復後可以重試 |
| 超時 | 先在 api.apiyi.com/log 中按時間查找,確認請求是否已經執行 |
已執行就不要重發,未執行再重試 |
需要特別說明 429 和超時兩種情況:
- 429 的退避重試:只適用於臨時限流。重試次數要設上限,每次間隔逐步加長。額度不足時,重試多少次都不會成功。
- 超時:客戶端在 60 秒內沒收到響應,並不代表服務端沒有處理這個請求。如果服務端已經處理完,直接重發會再執行一次,費用也會再扣一次。所以應先查日誌,確認請求沒有執行,再重新發送。
如果需要聯繫技術支持,提交前先把錯誤體和日誌中的 Key、客戶數據等敏感信息脫敏,再附上狀態碼、請求時間、模型名和 request ID。錯誤信息的留存與提交方式見 docs.apiyi.com/api-manual/error-reporting。
全部排障完成後,用 2.1 的示例重新運行一次,整套流程需要同時滿足三個條件纔算通過:
- 驗收函數輸出“通過”。
- finish_reason 不是
length。 - 控制檯日誌中能找到同一時間、模型爲
hy4的記錄,並且用量與本地記錄的 usage 一致。
