Tencent TokenHub 免費體驗怎麼用？Hy3 Preview 學生 AI Agent 導流

騰訊混元是一條適合中文學生實驗的模型路線，但舊 Hunyuan 平台正在遷移到 TokenHub。騰訊雲公告寫明，原混元平台預計在 2026 年 9 月 30 日完全關閉；因此本文把目前可查的 TokenHub 新人免費體驗包當主流程，舊 endpoint 只作為遷移警示。TokenHub 官方目前列出語言模型 1,000,000 tokens、有效期一年；這是一次性、有限期、依帳戶與模型方案發放的額度，不是永久免費 token。

本篇把 TokenHub 規劃為每位學生自己的低量學習燃料：自己註冊、自己完成實名、自己保管 API key、自己讀回免費包和後付費狀態，使用公開或 synthetic data，完成後撤銷憑證。真正啟用前必須重新讀取 TokenHub 控制台、模型詳情、免費包、價格與服務條款；主 agent 不代註冊、不代收 key，也不代開後付費。

當日敲門模型：hy3-preview（TokenHub 免費體驗候選）

本篇的當日免費候選是 hy3-preview。騰訊雲遷移公告把舊 Hunyuan 模型映射到新的 TokenHub 模型體系，TokenHub 的官方模型方案又把 hy3-preview 定位為適合 Agent 工作流的模型；但「候選」不等於每個帳戶都一定有相同的免費包、地區或限頻。學生要在 TokenHub 模型廣場重新讀回 model id、免費體驗標籤、剩餘 token、到期日和 RPM／TPM，全部一致才可使用。

TokenHub 新人免費體驗是帳戶資格，不是可分享的 API token。官方目前說每個主帳戶只可參加一次、語言模型免費額度有效一年；免費包用完後，如果沒有明確開啟後付費，服務應停止。本文不把 hy3-preview 宣稱為永久最佳模型，也不把一次性的新人包寫成可供全班共用的燃料。

先把免費資源包和 token 分開

免費資源包是騰訊雲帳戶內的抵扣資源，按模型的輸入與輸出 token 或其他產品單位扣減。它不是可以匯出、轉移、分享或存成文字的 token；API key 只是請求授權憑證。把兩者混寫會讓學生誤以為拿到 key 就取得無限燃料。

主 agent 應同時記錄資源包餘額、模型、輸入 token、輸出 token、使用時間和帳單狀態。免費資源包消耗完時，agent 要停在人工檢查，不自動改用另一個帳戶或開啟後付費。

首次開通需要實名認證

TokenHub 快速入門要求騰訊雲帳戶與個人或企業實名認證，接著在模型廣場領取免費體驗包、建立 API key，再使用 OpenAI-compatible endpoint。這是帳戶資格和合規前置，不是可以由主 agent 代辦或用他人身份繞過的步驟。

文章不要求學生把身份證明、付款資料或帳戶登入交給任何人。每位學生自行決定是否符合資格；不能註冊多個帳戶來反覆取得一次性免費包，也不能把老師、同學或服務帳戶的 key 集中到共用 gateway。

一年的有效期不是按月重置

TokenHub 官方目前列出的新人語言模型免費體驗包，自領取或啟用日起一年內有效；沒有用完的額度到期作廢。它不像月度 free tier，不會在每個月自動補回，也不會因為幾個月沒有使用而暫停倒數。實驗開始前要記錄 activation date、expiry date 和最後一次 console read-back。

如果服務遷移、模型下線或控制台改變資源包規則，文章中的一年不能取代當日官方資料。過期後不要用 retry、換 endpoint 或新 key 尋找遺失的額度；停止並重新判斷是否有合法的新方案。

輸入輸出要分別記帳

混元文字服務的價格依輸入與輸出 token 計算，免費資源包則依官方產品表抵扣。學生要在請求前估算 prompt 和 max tokens，在回應後讀取 usage，並將兩者寫入同一個 task record。不要只記錄「呼叫一次」，因為一個長上下文請求可能遠高於十個短問題。

本地每日預算應低於控制台顯示的免費餘額，為資料延遲、重試和並發保留緩衝。若 usage 欄位遺失、資源包剩餘數字跳動或帳單尚未同步，先停止下一輪，等待 read-back 後再判斷。

完成作業後清理服務

作業結束時停止所有混元請求、IDE plugin、排程、queue worker 和本地 proxy，刪除測試用 API key，清除環境變數與臨時 log，再檢查控制台沒有未預期的後付費或付費資源包。需要保存的只有去除 secret 的程式、假資料、評測結果、usage 統計和官方查核日期。

不要把免費包餘額截圖、個人實名資訊、帳戶 ID、完整帳單或 key 放進公開作業。下一位學生應在自己的帳戶重跑 preflight，才能知道當下的模型與資源包，而不是沿用別人的過期狀態。

可分享的是流程，不是憑證和帳戶狀態。

每次啟用都重新核准。

不沿用舊憑證。

並保留新的查核時間。

再開始下一次實驗。

TokenHub 模型和免費包不能任意合併

TokenHub 的免費體驗頁目前以語言模型、視覺模型等方案分開列額度；語言模型的 1,000,000 tokens 不能直接推論成所有 hy3、視覺、影片或 embedding 模型共用同一個池。模型廣場、模型詳情和帳戶資源包的實際讀回，才是本次任務可以使用的範圍。

先在 TokenHub 確認實際 model id、資源包名稱、剩餘量、到期日、扣減順序和限頻，再把 model id 寫入 allowlist。模型名稱相似、latest 別名或舊 Hunyuan model id 不應直接視為 hy3-preview 免費包的一部分。

免費包優先扣抵不等於永遠不計費

TokenHub 官方說免費體驗包會優先使用；免費包優先扣抵只說明當下的扣減順序，不代表過期或用完後仍有免費餘額，也不代表帳戶不會因已開通的後付費或其他雲服務而產生費用。

在第一次 API 呼叫前，讀回帳戶是否已開通後付費、是否有付費資源包、目前模型的價格和餘額。只要這一項讀不到，就不批准主 agent 呼叫。學生不應為了延長免費量自行購買付費包或啟用日結後付費。

預設不自動進入後付費

TokenHub 官方目前說，免費體驗包用完後，如果沒有明確開啟後付費，服務會停止；若帳戶已開啟後付費，免費包耗盡後可能繼續產生費用。這是本篇的核心保護，但仍要查核帳戶歷史設定，因為「預設」不等於每一個既有帳戶目前都未開通。

若帳戶已開通後付費，模型請求可能在免費包用完後繼續計費。遇到免費資源包耗盡、到期或扣款類型不明時，立即停止 agent、IDE plugin、cron 和 background process，交由帳戶持有人在控制台關閉後付費或刪除 API key。

開通後付費是新的授權事件

任何人都不能把後付費開關藏在 retry、fallback 或部署腳本裡。它會改變免費實驗的風險、帳戶成本和停止條件，必須由學生或正式帳戶負責人明確決定。主 agent 的設定應在偵測到 pay-as-you-go 時直接拒絕，而不是詢問供應商能否繼續。

若未來真的需要付費，應建立獨立的 project、預算、模型 allowlist、低並發和帳單 read-back，再由人批准一個明確的付費任務。本文的免費燃料範圍不包含這個付費分支。

API key 只屬於自己的帳戶

官方 API Key 管理文件要求在控制台建立、查看和刪除 key，也提醒 key 是請求的安全憑證。學生把 key 放在自己的環境變數或 server-side secret store，不放入公開 Git、瀏覽器、notebook、課程群組、截圖或聊天訊息。

如果 key 出現在 log 或誤傳到別人手上，立即刪除並停止所有舊程序。撤銷 key 只會阻止未來請求，不會取消已使用的 token、已發生的付費或帳戶實名責任。

OpenAI 相容 endpoint 要固定

TokenHub 官方目前提供 OpenAI-compatible API，base URL 是 https://tokenhub.tencentmaas.com/v1，聊天完整路徑是 /v1/chat/completions。相容介面讓既有 adapter 容易移植，但不表示參數、停止語意、串流 usage 或工具呼叫和 OpenAI 完全相同；不要把舊 api.hunyuan.cloud.tencent.com endpoint 當成今天的新註冊入口。

官方文件特別說明，混元的 stop 行為目前和 OpenAI 有差異，未來可能再調整；streaming 的 usage 在最後一個資料塊回傳。第一個學生 lab 應先使用非串流純文字，並把這些差異寫入測試。

先做免費包 preflight

每次呼叫前讀回帳戶實名狀態、服務是否已開通、model id、資源包剩餘 token、到期日、後付費開關、API key 所屬帳戶、endpoint 和本地預算。任何欄位不一致就停止，不把上一次 console 的截圖當作本次授權。

const state = {
  model: process.env.TOKENHUB_MODEL || 'hy3-preview',
  freeTokens: Number(process.env.TOKENHUB_FREE_TOKENS_REMAINING),
  expiresAt: process.env.TOKENHUB_FREE_EXPIRES_AT,
  postpaid: process.env.TOKENHUB_POSTPAID_ENABLED === 'true',
  readbackAt: process.env.TOKENHUB_QUOTA_READBACK_AT
};

if (!state.model || !Number.isFinite(state.freeTokens) || state.freeTokens <= 0) {
  throw new Error('fresh Hunyuan free-resource read-back required');
}
if (!state.expiresAt || Date.parse(state.expiresAt) <= Date.now()) {
  throw new Error('free resource pack is expired');
}
if (state.postpaid) throw new Error('postpaid is enabled; require explicit approval');
if (!state.readbackAt) throw new Error('quota read-back timestamp is missing');
console.log({ model: state.model, freeTokens: state.freeTokens });

這些環境變數只是一次性查核結果，不是騰訊雲權威帳單。正式流程要由帳戶持有人在控制台讀回後再產生 manifest，並在免費包或後付費狀態變動時使 manifest 失效。

聊天請求限制在短文字

官方 OpenAI-compatible 範例使用 Bearer API key 和 chat completions。下面只示範 placeholder 和低輸出上限；真正的 model、免費包狀態與 endpoint 要使用當日 preflight 產生的設定。不要在程式中寫入真實 key，也不要讓瀏覽器直接持有學生憑證。

const apiKey = process.env.TOKENHUB_API_KEY;
const baseUrl = process.env.TOKENHUB_BASE_URL || 'https://tokenhub.tencentmaas.com/v1';
const model = process.env.TOKENHUB_MODEL || 'hy3-preview';
if (!apiKey || !model) throw new Error('missing verified TokenHub configuration');

const response = await fetch(`${baseUrl}/chat/completions`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model,
    messages: [{ role: 'user', content: '用三句話說明一次性免費資源包。' }],
    max_tokens: 160,
    temperature: 0.2
  })
});
const payload = await response.json().catch(() => ({}));
console.log({ status: response.status, model, usage: payload.usage || null });
if (!response.ok) throw new Error(payload.error?.message || `request failed: ${response.status}`);

TokenHub 限頻要以模型讀回

TokenHub 官方資料結構會回傳模型或帳戶的免費額度、扣款類型、付費開關、RPM／TPM 與停止原因；限頻不是免費 token 的同義詞。主 agent 不應把控制台顯示的上限當作學生可用目標，而應在本地設定 1 個並發、短 prompt 和低 max tokens，再保留供應商緩衝。

並發和免費 token 是兩個不同限制。降低並發不能增加額度；提高並發也不能縮短資源包有效期。只要收到 429、排隊、超時或 5 個並發的拒絕，就有限重試並回報，不建立更多帳戶或 key。

429 和限頻採有限退避

API 概覽和 OpenAI-compatible 文件都提醒有限頻與共享並發。429 或服務忙碌時，重試只是等待，不是擴充免費量。每個 task 設定最多兩次退避，保存 request id 和最後狀態；連續失敗就停機，不自動換 key。

async function withBoundedRetry(request, attempts = 2) {
  for (let index = 1; index <= attempts; index += 1) {
    const response = await request();
    if (response.status !== 429 || index === attempts) return response;
    await new Promise((resolve) => setTimeout(resolve, 700 * index));
  }
  throw new Error('retry loop ended unexpectedly');
}

const result = await withBoundedRetry(() => fetch(
  `${baseUrl}/chat/completions`,
  { method: 'POST', headers: { Authorization: `Bearer ${apiKey}` } }
));
if (result.status === 429) throw new Error('rate limit remains; stop task');

若第一次 POST 的送達狀態不明，不要無條件重送。先查 request record 或控制台 usage，避免成功請求的回應遺失後又消耗一次 token。

後付費錯誤要直接停機

免費資源包耗盡、到期或未開通服務時，錯誤不應被當作普通網路失敗。若回應顯示資源不足、欠費、未開通後付費或帳單異常，停止並由帳戶持有人查看控制台。不要把 key 放進錯誤訊息，也不要因為另一個模型還有餘額就自動改 model。

401、403 要檢查 key、實名、服務與模型權限；400 要修正請求 schema；429 要有限退避；5xx 要有限重試或人工切換到已批准的供應商。任何需要購買資源包或開啟後付費的修復，都超出本篇免費批准範圍。

模型差異要在 adapter 測試

雖然介面相容 OpenAI，混元的 stop 行為目前可能在匹配內容之後才停止，且未來可能修改；streaming usage 需要等最後資料塊。function calling、search、vision、embedding 和 reasoning 欄位也不是每一個 model 都支援。

學生先做非串流文字測試，確認 role、content、finish reason、usage、錯誤與停止語意，再逐步加入工具。評測報告保存 model id、API base URL、日期、參數、實際輸出和 token 統計，不用「看起來像 OpenAI」作為相容性證明。

資料最小化和內容責任

騰訊混元相關服務條款要求輸入內容合法合規，並提醒不要輸入未經授權的自然人個資、智慧財產或商業秘密。免費額度不會給學生抓取網站、複製付費內容、上傳客戶資料或執行未授權安全測試的權利。

教學輸入只使用公開、去識別化或 synthetic data；帳密、API key、內部 prompt、未公開研究和個資一律先遮罩。工具呼叫預設 read-only，模型不能直接改資料、發信、購買、部署或代表學生做外部承諾。

用量和帳單要雙向讀回

控制台可以查看免費資源包和計費詳情，但頁面更新、帳單結算和 API response 可能有時間差。每次實驗保留開始時間、結束時間、model、輸入輸出 usage、資源包剩餘、後付費狀態、request id 和最後查核時間；不要因為剛才看不到扣款就繼續壓測。

如果 console 顯示免費包扣抵以外的付費資源、按量後付費或欠費，立即停止所有呼叫和排程。資源包扣款順序可以說明一筆費用怎麼抵扣，但不能取代帳戶實際 bill read-back。

TokenHub 遷移需要重新驗證

騰訊雲遷移公告目前寫明，舊混元平台停止新增模型能力與新購服務，原平台預計在 2026 年 9 月 30 日完全關閉；舊模型 ID 也要依公告映射到 TokenHub 的新模型體系。這代表文章中的 endpoint、model list、免費包和購買流程都有可能在下一次啟用前變更。

學生不要自行把舊 API key 改接新 endpoint，也不要看到 TokenHub 有相似模型就推斷免費包可共用。新流程要重新建立或核准 key、base URL、model id、免費包、後付費開關和資料政策；沒有新證據就停在舊流程之外。

學生個人工作流

第一步由學生自行完成實名與服務開通，讀回免費資源包、到期日和後付費狀態。第二步建立自己的 API key，使用環境變數與固定 endpoint。第三步設定本地並發 1、短 prompt、低 max tokens 和每日上限，再做十到二十筆合成案例。

第四步記錄品質、usage、錯誤和帳單；遇到額度、付款、資料或條款疑問就停止。第五步關閉 IDE plugin、cron 和 background process，撤銷不再需要的 key，提交 adapter、假資料與統計，不提交帳戶或憑證。

不建立共用學生 gateway

TokenHub 免費體驗包屬於主帳戶和模型方案邊界；不能把一個學生 key 放入全班共用 proxy，不能用主子帳號拆分免費量，也不能把免費 API 包裝成對外課程或轉售服務。

團隊若要正式使用，應另行決定帳戶治理、資料處理、模型授權、並發、付費和 SLA。本文只批准每位學生自己的非生產學習實驗，不能代表騰訊雲允許共用或商業用途。

停止條件提前寫入系統

當免費包不存在、已過期、餘額不足、後付費已開通、帳單狀態不明、模型不在當日 allowlist、TokenHub 遷移未重新確認、資料含未授權個資、收到 429 連續失敗或任務需要部署與長跑時，立即停止。

恢復必須由帳戶持有人重新讀取官方計費、API key、模型、限頻、條款、TokenHub 公告和帳單，再明確批准一個新的 task manifest。禁止用排程器悄悄重試或替換帳戶。

官方文件清單

啟用前請閱讀TokenHub 新人免費體驗、TokenHub 快速入門、TokenHub 線上推理、TokenHub 資源與狀態資料結構、混元遷移公告、官方 API Key 管理與TokenHub 模型方案。若新 TokenHub 頁面、控制台或服務條款與本文不同，以當日官方資料為準。

和既有免費燃料的分工

TokenHub 適合作為「一次性、一年有效、語言模型新人包、免費包用完且未開通後付費時停機」的中文模型實驗分支。它和 Alibaba Model Studio 都需要讀回帳戶、模型和資源包，但 TokenHub 還要特別注意實名、舊 Hunyuan 遷移和主帳戶的免費資格。想比較另一種免費模型路線，可閱讀SiliconFlow 免費模型 API 的學生實驗說明，也可先看AI Agent 常見問題。

跨供應商 fallback 只能使用各自獲准的個人 key，並且每個 request 要知道自己的來源和停止條件。不能把多個供應商串成一個匿名免費池，也不能用 fallback 掩蓋某一個帳戶已開通後付費。

本篇批准結果

TokenHub／混元通過「每位學生個人、完成合法實名、一次性新人免費體驗包、重新核准 hy3-preview 與 endpoint、未開通後付費、公開或 synthetic data、低並發且可停止」的窄批准。它沒有通過「共用 key、主 agent 代管學生帳戶、免費包耗盡後自動付費、舊 Hunyuan endpoint 未查核就長期使用或長期 production gateway」的批准。

本篇沒有登入騰訊雲、沒有完成實名、沒有建立或讀取 API key、沒有啟用後付費、沒有做實際 API smoke，也沒有對 WordPress 或公開網站寫入。正式啟用前必須重新讀取免費包與 TokenHub 現況。