Hugging Face 免費 API credits 怎麼用？gpt-oss-120b routed inference

本篇是免費 token fuel 系列第 84 篇，研究 Hugging Face Inference Providers 的 Free User monthly credits。Hugging Face 官方定價頁目前寫明，每個 Free User 每月有 USD 0.10 credits，可用於 Inference Providers，並特別標示金額 subject to change。這不是永久承諾、不是每個模型固定 token 數，也不是可以分享的公共 API key；它比較像一個極小、可觀察、用完即停的學生 agent 實驗預算。

以 Hugging Face 每月 USD 0.10 routed credits、gpt-oss-120b 與 provider routing 呈現的 YOLO LAB 原創編輯封面 — YOLO LAB 原創編輯封面：以 Hugging Face 每月 USD 0.10 routed credits、gpt-oss-120b、provider policy 與 custom key stop 呈現學生 Agent 的受控燃料入口；非 Hugging Face 官方宣傳圖。

本篇分類為 CONDITIONAL_HUGGINGFACE_INFERENCE_PROVIDERS_FREE_USER_010_MONTHLY_ROUTED_CREDITS。對主要 AI agent，最值得研究的是 Hugging Face routed request：由 Hugging Face 代理到多個 inference provider，以 Hugging Face User Access Token 驗證，usage 與 billing 集中在 Hugging Face 帳戶。若改用自己的 provider key，官方說該呼叫不使用 Hugging Face monthly credits，而由 provider 直接計費，所以兩條路線必須分開。

本文只做 Hugging Face 官方 pricing、Hub integration、InferenceClient、chat completion、security、token、rate limits 與 terms 整理，不代註冊帳號、不建立或取得 HF token、不替換 provider key、不購買 credits、不呼叫 live inference、不把任何學生資料送入 Hugging Face，也不把文章發布到 WordPress。主要 agent 的人工 handoff 原則可延伸閱讀 YOLO LAB AI agent 使用 FAQ。

Hugging Face Free User 的核心結論

Hugging Face Inference Providers 是一個統一 proxy layer，讓應用程式用一個 Hugging Face token 呼叫不同 provider 的模型。官方 Pricing and Billing 目前列出 Free Users 每月 USD 0.10，credits 只能用於 Inference Providers；PRO 是 USD 2.00，Team 或 Enterprise 是每席 USD 2.00，但那是不同 plan，不能把 PRO 或 organization 的額度當成學生 Free User 已擁有的燃料。

這筆 USD 0.10 的意義是「可以開始做很小的 inference 實驗」，不是「每月保證可產出多少 tokens」。實際能完成幾次請求取決於選中的模型、provider、輸入輸出 token、任務類型與該 provider 的 price。文章只把它標成 conditional，因為官方金額可能調整，模型 availability、routing、rate limit 與條款也會變動。

function classifyHuggingFaceFuel(snapshot) {
  if (snapshot.provider !== 'HUGGINGFACE_INFERENCE_PROVIDERS') return 'PROVIDER_MISMATCH';
  if (snapshot.accountType !== 'FREE_USER') return 'PLAN_REVIEW_REQUIRED';
  if (snapshot.monthlyCreditsUsd <= 0) return 'MONTHLY_CREDIT_STOP';
  if (snapshot.autoPurchase === true) return 'AUTO_PURCHASE_STOP';
  return 'ROUTED_FREE_CREDIT_CANDIDATE';
}

截至 2026-08-25 的敲門模型：openai/gpt-oss-120b

截至 2026-08-25，本篇以 Hugging Face 官方 gpt-oss guide 明確示範可經 Inference Providers 呼叫的 openai/gpt-oss-120b 作為能力優先的 routed 敲門模型；官方範例還展示了 :cerebras provider suffix 與 OpenAI-compatible Chat Completions。它適合先觀察 reasoning／agentic 能力與 provider routing，但不是 USD 0.10 的固定免費保證；正式 canary 前仍要讀回當日 model、provider、price、license、route policy 與剩餘 credits。

const currentHfEntry = {
  model: 'openai/gpt-oss-120b',
  providerPolicy: ':fastest',
  alternate: 'openai/gpt-oss-120b:cerebras',
  entitlement: 'CREDIT_AND_PROVIDER_READ_BACK_REQUIRED'
};

USD 0.10 不是 token 數

Hugging Face credits 是美元計價的 account credit，不是 input token、output token、request count 或固定 context window。不同 provider 對同一個 model 可能有不同價格，模型也會因 prompt、completion、image、audio 或 embedding 任務而有不同 cost。主要 agent 的 ledger 要記 model、provider、task、prompt tokens、completion tokens、total tokens、estimated cost、actual billed amount 與查核時間，不能用「每月十美分」反推固定 turns。

如果一次 canary 的實際成本尚未能從 Hugging Face billing 或 response usage 讀回，就先標成 provisional，降低 batch 大小並停止平行請求。Free User 的額度很小，錯誤的長 prompt、圖片或多輪 agent tool use 可能很快消耗完 credits。學習重點是看懂 provider routing 與 cost attribution，不是把每月額度消耗到零。

Routed request 與 custom provider key 必須分開

官方定價文件把 billing 方法分成兩種。Routed by Hugging Face 是請求通過 HF proxy，由 Hugging Face 帳戶管理 usage，monthly credits 可以套用，通常不需要另外建立 provider account。Custom Provider Key 是使用者把自己的 provider key 設在 Hugging Face，呼叫會由 provider 直接計費，Hugging Face monthly credits 不適用。兩者即使都使用 InferenceClient，也不能混寫在同一個 manifest。

對學生 agent，預設只允許 routed request，因為這樣比較容易集中記帳與停止。若 owner 已經有某個 provider 的正式帳戶，才另建 custom-key route，並明確寫出 provider name、provider billing、provider terms、key scope、撤銷方式與費用上限。不要因為某個 provider 在 HF model page 看起來可用，就偷偷把 provider key 貼進 notebook 或把 routed credits 當成 direct API credit。

function chooseHfBillingRoute(request) {
  if (request.customProviderKey === true) return 'DIRECT_PROVIDER_BILLING_REVIEW';
  if (request.hfToken && request.providerRoute === 'HUGGINGFACE_ROUTED') {
    return 'USE_HF_MONTHLY_CREDITS_CANDIDATE';
  }
  return 'BILLING_ROUTE_INCOMPLETE';
}

Hugging Face token 的最小權限

Hugging Face 官方 Inference Providers 頁面要求 User Access Token 具有 Inference Providers permission。Token 文件又建議依用途選 role，並指出 fine-grained token 可以縮小到特定資源或 organization；對只需要呼叫 Inference Providers 的學生 agent，不應使用帶有 repository write 或全帳戶管理能力的 token。實際權限名稱與設定畫面要以當日 token settings read-back 為準。

Token 只放在 server-side secret、受控環境變數或合規的 secret manager。不要放進 browser bundle、公開 gist、model card、notebook output、CI log、截圖、聊天訊息或文章。Hugging Face 官方建議每個 app 或 usage 建立獨立 token，並說若 token 洩漏，owner 應在 Access Tokens settings delete 或 refresh；主要 agent 不接收、不代保管、不轉交任何真實 token。

function validateHfTokenManifest(token, route) {
  if (route !== 'HUGGINGFACE_ROUTED') return 'ROUTE_REVIEW_REQUIRED';
  if (!token.reference || !token.expiresAt) return 'TOKEN_METADATA_INCOMPLETE';
  if (token.inferenceProvidersPermission !== true) return 'INFERENCE_PERMISSION_REQUIRED';
  if (token.repositoryWrite === true || token.admin === true) return 'SCOPE_TOO_BROAD';
  return 'TOKEN_REFERENCE_READY';
}

OpenAI 相容 endpoint 的範圍

Hugging Face 官方文件提供 OpenAI-compatible chat completions endpoint，base URL 是 https://router.huggingface.co/v1。這個相容介面目前是 chat completion route；官方明確提醒 image generation 等其他 task 要使用 Hugging Face inference clients。主要 agent 不應因為 chat endpoint 長得像 OpenAI，就推論所有 provider、所有模型、所有 tool calling 或所有輸入類型都完全相容。

官方 chat completion schema 目前包含 messages、max_tokens、stream、tools、response_format、reasoning_effort 與 usage 等欄位，但各 model／provider 對欄位的支援仍可能不同。小型 canary 只使用純文字、短 messages、有限 max_tokens 和 read-only output；需要 vision、image、audio、structured output 或 tool call 時，先查 task 頁與 model card，不要直接從 OpenAI code copy 成 production route。

import os;
from openai import OpenAI

client = OpenAI(
    base_url="https://router.huggingface.co/v1",
    api_key=os.environ["HF_TOKEN"],
)

completion = client.chat.completions.create(
    model=os.environ["HF_MODEL_ID"],
    messages=[{"role": "user", "content": "Summarize this public fixture in two short points."}],
    max_tokens=120,
)
print(completion.choices[0].message)

上面的程式碼只是官方介面的 placeholder，本文沒有執行 request。HF_TOKEN 和 HF_MODEL_ID 必須由 owner 在自己的環境建立；不能把真實值填回文章。模型 id 也要在當日 Hub／Inference Providers model page 確認，不把示例 model 視為永久可用或一定落在 USD 0.10 內。

InferenceClient 適合多任務路線

若使用 chat 以外的 task，官方建議用 huggingface_hub Python client 或 @huggingface/inference JavaScript client。InferenceClient 可以指定 provider，也可以讓 provider="auto" 自動選擇；目前文件說 auto 預設會依模型選擇最快的可用 provider，等價於 :fastest policy。這會影響 latency、provider exposure、price 和資料流，因此主要 agent 不應把 auto 當成固定路由。

需要成本控制時，可以先明確選 provider 或使用 :cheapest policy；需要固定組織偏好時才考慮 :preferred。不論哪一種 policy，先把實際 model、provider、billing route、response usage 與 error status 寫入 ledger。若 provider selection 改變，視為 routing drift，重新做短 canary，不讓既有的 cost 或 quality 結論自動延伸。

import os
from huggingface_hub import InferenceClient

client = InferenceClient(
    token=os.environ["HF_TOKEN"],
    provider="auto",
    timeout=30,
)

result = client.chat_completion(
    model=os.environ["HF_MODEL_ID"],
    messages=[{"role": "user", "content": "Classify this synthetic fixture as study-only."}],
    max_tokens=80,
)
print(result)

模型搜尋與 provider availability

Hugging Face Hub 可以依 inference provider 篩選 model，Inference Providers 也列出支援的 task 與 provider。這個目錄是路由前的候選清單，不是每一個 Free User 都能以 USD 0.10 使用所有模型的保證。模型可能需要 gated access、特定 provider、不同 license、不同輸入格式或不同計價；同一個 model id 的 provider suffix 也可能改變實際後端。

主要 agent 先選低成本、短文字、公開模型卡可讀的 model，再做 availability、task、license、price、input／output modality 與 credit route read-back。找不到官方當日 price 或 model card，就把候選標為 MODEL_RECHECK_REQUIRED。不要依據搜尋引擎摘要、第三方貼文或別人貼出的 token 來判定可用性。

Free credits 也會被 UI 功能消耗

Hugging Face Hub Integration 文件指出，model page 的 inference widgets、Inference Playground、Data Studio AI 等功能會使用 Inference Providers，並計入 monthly credits。這表示一個學生若先在 Playground 試很多 prompt，再從 agent 發 API request，兩者可能共同消耗同一個 account credit。ledger 必須把 source 分成 API、widget、playground、Data Studio 或其他 Hub surface。

課程若需要示範 UI，可以先設定明確的 prompt 數量與停止時間，再查 billing usage；課程若要保留 credits 給 agent，則把 UI exploration 視為同一個 budget 的消費。不能把瀏覽器試用說成「另外免費」，也不能在 credits 快用完時自動轉成 custom provider key 或購買補充 credits。

用完 monthly credits 後預設停止

官方 Pricing 文件說所有使用者在 monthly credits 用盡後仍可以透過購買 additional credits 繼續使用 API。這對 production 是便利性，對學生 agent 則是費用風險。主要 agent 的預設應是 credits remaining 不足就停止、保存已完成結果、回報 owner，不能在背景購買 credits、開啟 auto purchase、改用 owner 的付款方式或自動選一個更便宜但未查核的 provider。

只有 owner 明確核准 paid route，才建立獨立 manifest，記錄 credit purchase、付款責任、spend cap、provider、model、資料政策與撤銷／停用證據。Free User 的 USD 0.10 route 成功，不代表額外 credits 的金額、退款、稅務、付款條款或 provider quality 已經驗證。

function decideAfterHfCreditCheck(snapshot) {
  if (snapshot.monthlyCreditsRemainingUsd >= snapshot.estimatedCostUsd) {
    return 'ALLOW_ONE_SMALL_CANARY';
  }
  if (snapshot.ownerPaidApproval !== true) return 'STOP_NO_AUTO_PURCHASE';
  return 'PAID_CREDIT_MANIFEST_REVIEW_REQUIRED';
}

Hub rate limits 與 inference cost 不是同一件事

Hugging Face Hub Rate limits 文件說 Hub requests 分成 API、Resolvers 和 Pages 三個主要 bucket，額度以五分鐘 fixed window 計算。文件目前列出 Free User 的 API 1,000、Resolvers 5,000、Pages 200，但也註明 anonymous／Free limits 會依平台健康狀況變動。這些是 Hub platform rate limits，不是 USD 0.10 credit、模型 token price 或第三方 provider 的 inference quota。

遇到 429，要先讀 response、RateLimit 與 RateLimit-Policy headers，判斷是 Hub rate limit、provider capacity、model availability 或 credits 不足。Hub 的 429 可以依官方 header 與 SDK 的 smart retry guidance 做有限退避；但不能把所有 429 都重試，也不能以多帳戶、不同 IP、未授權 token 或平行 proxy 逃避平台限制。

function classifyHfFailure(response) {
  if (response.status === 429 && response.rateLimitResetSeconds) return 'FINITE_HUB_BACKOFF';
  if (response.status === 402 || response.code === 'CREDITS_REQUIRED') return 'CREDIT_STOP';
  if (response.status === 403) return 'TOKEN_OR_MODEL_PERMISSION_REVIEW';
  if (response.status >= 500) return 'PROVIDER_OR_SERVICE_RECHECK';
  return 'READBACK_AND_OWNER_REVIEW';
}

Routing policy 會影響成本與可重現性

官方文件說 Inference Providers API 是位於應用程式與多個 provider 之間的 proxy，provider=”auto” 可以自動選擇可用 provider，並有 fastest、cheapest、preferred 等 policy。這提高了模型可用性，但也表示同一個 model id 可能在不同時間走不同 provider。response ledger 要保存 route policy、實際 provider、model、timestamp、usage、cost、status 和 prompt fixture hash，才能知道結果是否可比較。

若研究目標是比較模型能力，固定 provider 與短 fixture 比較容易重現；若目標是低成本探索，才使用 auto 或 cheapest。若 provider unavailable，auto 可能 failover，這不是免費額度增加，也不是繞過 provider 的限制。agent 不應無限 failover；一次 route recheck 後仍不穩定就停止並交 owner。

Hugging Face routing 的資料邊界

Inference Providers Security 文件目前說，Hugging Face 不為訓練目的儲存 user data；routing through Hugging Face 時不儲存 request body 或 response，debug logs 最多保留 30 天，且不儲存 user data 或 tokens。文件也提醒，外部 provider 有各自的 security policy，因此不能把 HF proxy 的聲明延伸成每一個下游 provider 的相同資料條款。

學生 canary 仍只送 public 或 synthetic fixture，不送 API token、密碼、cookie、個資、學籍、客戶資料、私有 repository、未公開研究或付款內容。若模型 request 需要 URL、image、audio 或 file，先確認資料會經過哪一個 provider、模型條款與 retention；不要只看到 Hugging Face 不保存 request body，就跳過下游資料分類。

模型卡與 license 不能省略

Inference Providers 讓你用統一介面呼叫很多公開或私有模型，但模型可用不等於模型 license 可以任意使用。主要 agent 先讀模型卡、license、gated access、acceptable use、輸出限制與 provider terms，再決定能否用於課程。若要商用、發布輸出、處理客戶資料或建立衍生模型，交給 owner／法務確認，不從「免費 credits」推導出免費商業授權。

模型 id、provider id、task capability 和價格都可能改變。文章中只把 model 作為當日候選，不寫「永遠免費」或「一定不變」。每次啟用前重查 model page、Inference Providers task page、provider routing、license 與 pricing；任何一項缺資料，就維持 conditional。

帳號年齡與學生資格

Hugging Face Terms of Service 目前寫明，建立帳號的自然人至少要 13 歲，且帳戶資料要準確有效；使用者要負責帳戶與密碼安全，不能把密碼交給第三方。這只是服務條款的最低帳號條件，不是學校、地區或課程的自動批准。未成年、學校帳號、研究資料與課堂共用環境，仍由責任組織依適用 consent、privacy、校規與資訊安全要求判定。

官方沒有在這些 Inference Providers 文件中承諾一個固定的「學生 API token」或教育 credits。Free User 的 USD 0.10 是一般帳戶的 monthly credit，而不是因為學生身分就可多拿的配額。不要冒用學生、學校或研究者身份，不要收集同學帳號，不要把一把 token 貼給全班使用。

建立最小 routed chat canary

第一個 canary 只驗證五件事：token permission、model availability、Hugging Face routed billing、短 prompt 的 response、usage／cost read-back。使用公開或 synthetic fixture、短 context、低 max_tokens、一次一請求、固定 timeout，不開 image、file、tool、streaming 或 side effect。canary 失敗時保存 status、error、route policy 與查核時間，不把錯誤 prompt 直接重送很多次。

curl -sS "https://router.huggingface.co/v1/chat/completions" \
  -H "Authorization: Bearer ${HF_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"model":"'"${HF_MODEL_ID}"'","messages":[{"role":"user","content":"Summarize this public fixture in two short points."}],"max_tokens":120}'

本文不執行這個 curl，HF_TOKEN 與 HF_MODEL_ID 都是環境變數 placeholder。正式使用前由 owner 在自己的 Hugging Face settings 建立最小 token、確認 Inference Providers permission、選定當日 model 與 provider route，再從 billing page 讀回 monthly credits。成功的 response 只證明這個帳戶、model、route 和當下 credits 可用，不證明下一次仍相同。

Usage ledger 要區分來源與費用

每一個 job 需要保存查核日期、account type、monthly credit snapshot、route type、provider policy、model、task、prompt／completion token、estimated cost、actual cost、HTTP status、response id、是否 UI 消耗、是否使用 custom key 與 owner handoff。不要只記一個「HF 免費」欄位，因為 API、Playground、widget 和 Data Studio 都可能碰到同一個 credit balance。

若 billing dashboard 尚未更新，標記 pending，不要用舊餘額繼續加大批次。若 response 的 usage 與 dashboard 讀數不一致，先停止並記錄差異；不要直接把較樂觀的數字當真。Free User 額度很小，任何未解釋的差異都足以讓下一個 job 進入 paid route 或失敗。

function recordHfInference(response, ledger) {
  return {
    provider: response.provider || 'ROUTE_READBACK_REQUIRED',
    model: response.model,
    promptTokens: response.usage?.prompt_tokens ?? null,
    completionTokens: response.usage?.completion_tokens ?? null,
    totalTokens: response.usage?.total_tokens ?? null,
    status: response.status,
    source: ledger.source,
    costState: 'BILLING_READBACK_REQUIRED',
  };
}

Batch 與 interactive agent 分開治理

USD 0.10 不適合背景批次掃描大型資料集。批次開始前先建立 manifest，列出 fixture count、model、provider policy、max_tokens、預估 cost、最大 attempts、deadline、輸出位置與人工驗收者；完成小批次後才讀 usage，再決定是否繼續。遇到 credits 不足、429、model drift、provider failover 或 token permission 變更，保留已完成結果並停止，不為了湊完批次自動換帳戶或購買 credits。

互動 agent 只允許短 prompt、短 output、read-only tools 和人可檢查的 response。長上下文、多輪 function call、image input、audio、embedding 或大批次都要重新估算成本與資料流。若要讓 agent 做發布、寄信、部署、付款、刪除或 repository write，Inference Providers 只負責產生建議；side effect 仍要由人批准。

429、timeout 與 provider failover

429 可以來自 Hugging Face Hub rate limit 或下游 inference provider；timeout 也不一定表示 request 沒有執行。若 request 可能已完成，盲目重送會造成重複 cost 或重複結果。純 read-only canary 可以有限退避一次，再用 response id、usage、billing 和 job id 做 read-back；有外部副作用的 action 不應直接由 retry 觸發。

function retryHfCanary(error, attempt, hasSideEffect) {
  if (hasSideEffect) return 'NO_AUTOMATIC_RETRY';
  if (error.kind === 'CREDITS_EXHAUSTED') return 'CREDIT_STOP';
  if (error.kind === 'TOKEN_PERMISSION') return 'TOKEN_REVIEW_STOP';
  if (error.status === 429 && attempt === 0) return 'ONE_HEADER_GUIDED_BACKOFF';
  if (error.kind === 'TIMEOUT' && attempt === 0) return 'READBACK_BEFORE_RETRY';
  return 'STOP_AND_RECORD';
}

Free User、organization 與 bill_to 不要混用

Hugging Face 文件把個人 Free User、PRO、Team 與 Enterprise organization 分開計算。Team 或 Enterprise 的 included credits 可以由 organization 成員共用，但那不代表普通 Free User 可以把自己的 credits 任意轉給同學；InferenceClient 的 bill_to 也需要相應的 Enterprise organization。學生 agent 預設只操作 owner 自己的帳戶，不設定陌生 organization、不冒用學校 billing、不將個人與團體 usage 混成一筆。

若學校真的要提供課程燃料，責任組織應自行建立合法的 organization、成員權限、usage owner、spend cap、資料政策與離校撤銷流程，再由 owner 讓 agent 使用明確授權的 route。主要 agent 不代建立 organization、不邀請學生、不配置付款，也不把 Team／Enterprise 的 credits 宣傳成每位 Free User 都能取得的免費 token。

Hugging Face 不加價不代表 provider 免費

官方 Pricing 文件說 Hugging Face 對 routed requests 以 provider rates 透傳、不加額外 markup；這只說明 billing pass-through 的方式，不代表所有 provider、model 或 task 都是零成本。Free User 每月 USD 0.10 只是先抵扣符合條件的 routed usage，超過後仍可能需要額外 credits，某些 provider 也可能有自己的 availability、模型授權、輸入限制與計費邏輯。

因此 cost ledger 至少記 Hugging Face route、實際 provider、model、tokens、provider price、credit deduction 和 billing read-back。若只看到模型頁上的「可用」或 Hugging Face 的統一 API，就沒有足夠證據宣稱成本可預測。課程應使用短 fixture 做單次測量，再決定是否值得保留該 model，而不是一次開很多 provider 來碰運氣。

Monthly credit 的查核與停止時間

官方文件只應被解讀為「每月提供目前列出的 credits」，不應自行補上一個未經官方說明的 UTC reset 日期、月底結轉規則或固定發放時間。主要 agent 每次 session 讀取 billing page 的 current balance、account／organization context、credit source、最近使用紀錄與是否已出現 additional credits prompt；讀不到就停止，不用舊 snapshot 繼續跑。

月度邊界附近尤其要避免大批次：credits 可能尚未同步，provider usage 也可能延遲。保留 safety reserve、一次只跑一個 canary、保存 response id 與查核時間，等 billing read-back 確認後再決定下一步。這種保守做法讓學生看到真正的 account budget 狀態，也避免把「每月」誤解成可以無限累積或立即重置。

如果 billing page 顯示 credit source、account context 或 provider breakdown 不明，先停止 routing；不要用另一個個人帳戶重試，也不要把原本的 request 改成 custom key。這些切換會破壞費用歸屬，讓 owner 無法分辨究竟是免費 credits、provider billing 還是 UI surface 消耗。完成一次可解釋的 read-back，比得到更多未分類 response 更重要。

當月額度真的用完時，保留 ledger、錯誤碼、最後一次成功的 response 與停止時間，等下一次 fresh check；不要宣稱「下個月一定會恢復多少」，因為官方金額本身標示可能變動。這也是持續捕獲機制的必要紀律：捕獲規格更新與停止訊號，而不是捕獲可疑帳號或未授權憑證。

停止時也要清楚標記剩餘工作、owner、最後查核時間、原因與下一步，讓下一次啟用能從同一份證據恢復，而不是重新猜測費用、模型與權限。

洩漏 token 的處置邊界

如果學生在 notebook、聊天、公開 repository 或 CI log 露出 HF token，第一步是停止該 token 的使用與相關 job，通知 owner，並由 token owner 在 Hugging Face settings delete 或 refresh。接著檢查 repository、Hub activity、billing、Inference Providers usage 與 logs，建立新 token 時縮小 permission。不要把洩漏的 token 貼到文章、掃描工具的公開 issue 或讓主要 agent 代為測試。

如果看到網路上別人的 token，不能拿來驗證、保存、分享或輪換帳戶。正確做法是把發現交給服務方或帳戶 owner 的安全流程，並讓真正的 owner 撤銷。本文的持續捕獲只捕獲官方免費方案的規格，不捕獲任何 credential。

每次啟用前的 fresh read-back

每次啟用 Hugging Face routed fuel 前，先重新讀 Pricing and Billing，確認 Free User monthly amount、subject to change、credits scope 與 additional credits 行為；再讀 Hub integration，確認 UI surfaces 是否共用 credits；讀 token 文件確認 fine-grained／Inference Providers permission；讀 task、model page 與 provider policy 確認 route；最後讀 billing、rate limit、security 與 terms。文章或舊 manifest 只能作為入口。

若官方文件、dashboard、model page 或 response read-back 衝突，以當日官方文件與帳戶 read-back 為準；保留差異並標成 RECHECK_REQUIRED。若 Free User credits 的金額、使用範圍、custom key 行為、token permission 或資料政策改變，就更新分類，不沿用舊的「免費」標籤。

function requireFreshHfReadback(readback, now) {
  if (!readback.checkedAt || !readback.accountType || !readback.creditScope) {
    return 'FRESH_READBACK_REQUIRED';
  }
  const ageHours = (Date.parse(now) - Date.parse(readback.checkedAt)) / 3600000;
  if (ageHours > 24 || readback.pricingChanged || readback.routeChanged) {
    return 'STALE_MANIFEST_STOP';
  }
  return 'READBACK_CURRENT_FOR_CANARY';
}

主要 agent 的 Hugging Face manifest

最小 manifest 要把 account type、monthly credits、route、token reference、model、provider policy、task、data class、max tokens、timeout、retry、spend approval 與 stop conditions 分開。不能只寫 free: true，因為 routed／custom key、UI consumption、provider failover、monthly reset、rate limit 與 model license 都會影響可用性。

const huggingFaceStudentManifest = {
  provider: 'HUGGINGFACE_INFERENCE_PROVIDERS',
  accountType: 'FREE_USER',
  monthlyCreditsUsd: 0.10,
  creditsSubjectToChange: true,
  route: 'HUGGINGFACE_ROUTED',
  customProviderKey: false,
  dataClass: 'PUBLIC_OR_SYNTHETIC',
  tokenStorage: 'SERVER_SIDE_ONLY',
  maxTokens: 120,
  maxAttempts: 1,
  autoPurchase: false,
  accountRotation: false,
  humanReviewBeforeSideEffect: true,
  stopOn: ['CREDIT_EXHAUSTED', '429', '403', 'TOKEN_LEAK', 'ROUTING_DRIFT'],
};

這篇文章的未做事項

本次沒有登入 Hugging Face、建立帳號、建立或取得 User Access Token、讀取任何人的 token、設定 Inference Providers permission、購買 credits、設定 custom provider key、呼叫 router endpoint、使用 Playground、使用 widget、送出 prompt、讀取 billing、建立 organization、部署模型或進行任何外部 publication。文章內的 HF_TOKEN、HF_MODEL_ID 與 shell／Python 範例都是 placeholder。

本篇完成的是 Free User 每月 USD 0.10 的官方分類、routed／custom key billing 分界、token permission、OpenAI-compatible chat endpoint、InferenceClient、provider selection、UI 共用 credits、Hub rate limits、429、security logs、下游 provider data policy、model license、學生帳號邊界、usage ledger、paid stop 與 fresh read-back。這足以讓合資格 owner 自行開始極小 canary，但不表示任何學生目前已取得 Hugging Face token 或免費 credits。

結論：每月十美分的小額 proxy 型 API fuel

Hugging Face Inference Providers Free User monthly credits 是目前值得收錄的條件式 API fuel：官方目前列每月 USD 0.10，可經 HF routing 使用多個 provider，學生不一定要另外建立 provider account，且可以用統一 token 與 SDK 做很小的模型、路由與 cost 實驗。但 credits 可能變動，額度是美元而不是固定 token；custom provider key 不套用 HF credits，超額後購買補充 credits 會進入 paid route，Hub rate limits 與下游 provider limits 也另行計算。

主要 agent 的放行條件是 owner 的 Free User account、最小 Inference Providers token scope、Hugging Face routed billing、當日 model／provider／license read-back、短 public／synthetic fixture、usage ledger、有限 retry、no auto-purchase 和人工 review。只有 owner 明確核准並建立獨立 paid manifest 時，才研究 additional credits 或 custom provider key。下一次官方 recheck 若 USD 0.10、credits scope、routing、permission、rate limits 或資料政策改變，就更新分類。