Clarifai $5 Welcome Credits 怎麼用？gpt-oss-120b 學生 Agent 敲門路線

本篇是系列第 72 篇本機草稿，介紹 Clarifai Pay-As-You-Go 帳戶的一次性 $5 welcome credits，作為學生 AI agent 的條件式模型推理燃料。Clarifai 官方帳務文件目前寫明，切換到新方案後，完成手機驗證可以 Claim credits，取得一次性免費 $5 credits；這筆 bonus 30 天到期，個人帳戶與組織帳戶各最多一筆。它是美元 credit，不是固定 token grant，也不是每月自動刷新。

本篇分類為 CONDITIONAL_CLARIFAI_5_USD_WELCOME_CREDIT_30_DAY_EXPIRY。Clarifai 可直接跑模型，也提供 OpenAI-compatible endpoint，因此適合作為主要 agent 的短期 canary、影像／文字 sidecar 或模型比較 route；但 Pay-As-You-Go 是付費計畫，Free $5 只是一筆 promotion。用完或到期後不能靜默充值，必須停止、轉本地 fallback 或由 owner 明確承擔付費。

本系列的「持續捕獲」代表持續讀取官方帳務、quickstart、認證、rate limits、status codes、privacy、terms 和 plan read-back，不代表替學生驗證手機、建立帳戶、取得 PAT、加入 payment method 或分享 key。本文不登入 Clarifai、不做 live inference、不上傳圖片、文字、音訊或影片，也不替任何人接受條款。

主要 agent 的資料分類、secret 與 fallback 可延伸閱讀 YOLO LAB AI Agent 常見問題。下面會把 $5 credit、模型價格、PAT、API key、個人／組織帳戶、手機驗證、30 天期限、15 RPS、資料保存、年齡、付款和學生 queue 分開說明，避免把一筆 welcome bonus 寫成可供全班共享的免費 token 池。

Clarifai welcome credit 官方現況

Clarifai 官方 Account and Billing 文件目前說明：新 plan 是單一 Pay-As-You-Go，沒有最低月承諾；切換後在通知列選 Claim credits，完成 phone verification 可以取得一次性免費 $5 credits，這筆 welcome bonus 30 天到期。文件還說，一個 user 最多可取得兩筆 welcome bonus：一筆 personal account、一筆 organization account。

這段官方文字需要拆成三個狀態：一、帳戶是否已經在新 plan；二、owner 是否完成自己的手機驗證並看到 Claim credits；三、credit 是否仍在 30 天有效期內。公開文件能證明方案規則，但不能證明某個學生帳戶已收到 $5。文章只把它列為條件式候選，不把新註冊、手機號碼或 organization account 當成可由主 agent 代辦的工作。

function classifyClarifaiWelcome(snapshot, now) {
  if (snapshot.provider !== 'CLARIFAI') return 'ROUTE_NOT_APPROVED';
  if (snapshot.plan !== 'PAY_AS_YOU_GO') return 'PLAN_READBACK_REQUIRED';
  if (snapshot.welcomeClaimed !== true) return 'OWNER_CLAIM_REQUIRED';
  if (snapshot.phoneVerified !== true) return 'OWNER_PHONE_REVIEW';
  if (!snapshot.expiresAt || new Date(snapshot.expiresAt) <= new Date(now)) {
    return 'WELCOME_CREDIT_EXPIRED';
  }
  if (snapshot.remainingUsd <= 0) return 'WELCOME_CREDIT_EMPTY';
  if (snapshot.postZeroAction !== 'BLOCKED') return 'BILLING_STOP_REQUIRED';
  return 'OWNER_CANARY_REVIEW';
}

這是美元 credit 不是固定 token

$5 credit 的消耗取決於所選 model、input、output、影像或其他 modality 的價格和 request 方式。不能在文章中承諾「$5 等於某個固定 token 數」，也不能把不同模型的單價平均後當成學生可用額度。正確的 ledger 會保存 model URL、價格查核時間、input／output usage、estimated cost、實際 balance 和停止狀態。

Clarifai 官方 quickstart 示範使用 gpt-oss-120b，也說可在 Community platform 找 model；這只說明模型選擇方式，不代表所有 Community model 都能使用同一筆 welcome credit、都能在同一 region 運作或都適合學生資料。每次 job 都要重新確認 model URL、授權 scope、價格、資料類型和 license。

function classifyClarifaiFuel(usage) {
  if (usage.provider !== 'CLARIFAI') return 'PROVIDER_MISMATCH';
  if (usage.creditKind !== 'WELCOME_USD_CREDIT') return 'FUEL_SCOPE_ERROR';
  if (!Number.isFinite(usage.estimatedUsd) || usage.estimatedUsd < 0) {
    return 'COST_READBACK_REQUIRED';
  }
  if (usage.llmTokensClaimed === true) return 'DO_NOT_CONVERT_TO_FIXED_TOKENS';
  if (!usage.modelUrl || !usage.pricingAsOf) return 'MODEL_PRICE_MISSING';
  return 'USD_CREDIT_LEDGER_READY';
}

手機驗證與 personal／organization 分界

官方帳務文件說 Claim credits 需要 phone verification；同一手機號碼最多可以驗證三個 Clarifai accounts，但只有一個 personal account 和一個 organization account 有資格取得 $5 bonus。這是防濫用和資格規則，不是鼓勵建立三個帳戶。學生 agent 不應收集同學手機號碼、不應輪換個人與組織帳戶、不應把組織 bonus 當成班級共享 key。

學生是否已達法定年齡也很重要。Clarifai Terms of Service目前寫明服務不是提供給未達所在地法定成年年齡者，使用者需表示自己已滿 18 歲或達所在地 age of majority。因此未成年學生不能由主 agent 自動繞過此條件；學校或監護人若要提供學習 route，必須由適用的成人 owner 依學校政策處理。

function acceptClarifaiOwner(owner) {
  if (owner.ageEligibility !== 'ADULT_OR_LOCAL_MAJORITY') {
    return 'AGE_ELIGIBILITY_REVIEW';
  }
  if (owner.phoneVerification !== 'OWNER_CONFIRMED') return 'PHONE_REVIEW';
  if (!['PERSONAL', 'ORGANIZATION'].includes(owner.accountType)) {
    return 'ACCOUNT_TYPE_UNKNOWN';
  }
  if (owner.bonusCountForType >= 1) return 'WELCOME_BONUS_ALREADY_USED';
  if (owner.sharedCredential === true) return 'KEY_SHARING_FORBIDDEN';
  return 'OWNER_SCOPE_CONFIRMED';
}

Pay-As-You-Go 不是永久免費方案

Clarifai 目前把新使用者導向 Pay-As-You-Go，文件說這個 plan 沒有最低月承諾，並可用於 serverless model access、dedicated deployment、Reasoning Engine 和其他功能；同一頁也提供 Add a Credit Card、Recharge 與 Auto recharge。這表示 $5 welcome credit 與 plan billing 是兩個不同狀態：promotion 可以暫時抵銷使用量，但不會把 Pay-As-You-Go 變成永久零費用。

官方文件另列 Pay-As-You-Go 每月 maximum spend limit 為 $100，需更高上限要聯絡 Clarifai。這不是學生應該用來消耗的預算，而是重要的風險訊號。main agent 預設不允許加入 payment method、不允許開啟 auto recharge、不允許 request 更高上限；若 owner 明確要升級，必須離開本篇免費 route 另做付款審核。

function decideClarifaiBilling(state) {
  if (state.plan !== 'PAY_AS_YOU_GO') return 'PLAN_REVIEW';
  if (state.autoRecharge === true) return 'AUTO_RECHARGE_BLOCKED';
  if (state.paymentMethodPresent === true) return 'PAYMENT_OWNER_REVIEW';
  if (state.remainingUsd <= 0) return 'STOP_FREE_ROUTE';
  if (state.postZeroAction !== 'BLOCKED') return 'POST_ZERO_POLICY_MISSING';
  return 'WELCOME_ROUTE_ALLOWED';
}

Clarifai PAT 與 App-Specific API Key

Clarifai authentication docs目前把 API 存取分成 Personal Access Token、App-Specific API Key、Environment Secrets 和 fine-grained scopes。PAT 可以存取 owner 自己資源及 app scope 之外的資源；App-Specific API Key 則限制在建立時指定的範圍。對學生 route，應優先使用最小 scope 的 app key 或由 owner 控制的 PAT，不要把帳戶密碼交給 worker。

Quickstart 指示把 PAT 放在 CLARIFAI_PAT 環境變數，這個名稱可以寫進 adapter，但實際 secret 不可以寫入 repo、文章、issue、prompt、queue 或前端。key 版本、owner、scope 和建立時間可以記入治理 ledger；secret 內容只能留在 secret manager，遺失或外洩時由 owner 撤銷並重新建立。

const CLARIFAI_PAT = process.env.CLARIFAI_PAT;

function buildClarifaiAuth(state) {
  if (!state.ownerApproved || state.keyScope !== 'MODEL_INFERENCE_ONLY') {
    return { action: 'BLOCK', reason: 'OWNER_OR_SCOPE_NOT_APPROVED' };
  }
  if (!CLARIFAI_PAT) return { action: 'OWNER_SECRET_MISSING' };
  return {
    headers: {
      Authorization: `Key ${CLARIFAI_PAT}`,
      'Content-Type': 'application/json'
    },
    secretForwardedToStudent: false
  };
}

process.env.CLARIFAI_PAT只是 adapter 的環境變數名稱。若選用 OpenAI-compatible client，Clarifai quickstart 仍把 PAT 放入 client 的 api_key，而 base URL 是 https://api.clarifai.com/v2/ext/openai/v1；相容層不代表 key scope、model URL、billing、資料保存或錯誤碼與 OpenAI 完全相同。

當日敲門模型：gpt-oss-120b

截至 2026-08-25，Clarifai 官方 Quick Start With API 仍以 gpt-oss-120b 作為文字 request 範例，完整 model URL 是 https://clarifai.com/openai/chat-completion/models/gpt-oss-120b。本篇把它標成當日第一個文字 canary，而不是永久最佳或永久免費 allowlist：owner 仍要在送出前重新確認 model URL、狀態、license、region、價格、PAT scope、welcome credit 是否可用與 post-zero stop。直接的 model page 若無法讀回，就維持 local-only，不用文章快照硬送 request。

OpenAI-compatible endpoint 與 model URL

官方 Quick Start With API示範 OpenAI client 指向 https://api.clarifai.com/v2/ext/openai/v1，model 欄位使用完整的 Clarifai model URL，例如 Community 上的 chat-completion model。這很適合讓主要 agent 以 adapter 切換 provider，但 request 的 model id、PAT 權限、response schema、usage 欄位、模型 license 和價格仍要由 Clarifai 的當日 read-back 決定。

function buildClarifaiChat(job, state) {
  if (state.creditReady !== true) return { action: 'BLOCK', reason: 'CREDIT_NOT_READY' };
  if (state.model.status !== 'CURRENT') return { action: 'BLOCK', reason: 'MODEL_REFRESH_REQUIRED' };
  if (state.dataClass !== 'PUBLIC_SYNTHETIC') return { action: 'BLOCK', reason: 'DATA_CLASS_BLOCKED' };
  return {
    baseURL: 'https://api.clarifai.com/v2/ext/openai/v1',
    model: state.model.url,
    messages: job.messages,
    max_tokens: Math.min(job.maxTokens, state.policy.maxOutputTokens),
    stream: false
  };
}

不應把 gpt-oss-120b 或其他範例 model URL 寫成永久 allowlist。Community model 可能由不同 owner 維護，模型版本、可用 region、tool 支援和 terms 會變；學生的第一個 canary 要選一個 owner 已核准、價格與資料政策都能讀回的文字模型，影像或音訊另開 route。

API base URL 與 REST 邊界

Clarifai API Overview 說平台可經由 HTTPS 存取，base 是 https://api.clarifai.com，支援 POST、PATCH、GET 和 DELETE。學生 agent 的 welcome-credit route 只批准必要的 inference request，不批准 DELETE、帳戶變更、付款設定、organization 管理或修改他人資源。API 方法多不代表學生可以把 PAT 當成管理員 token。

function admitClarifaiMethod(request, policy) {
  if (request.method !== 'POST') return 'METHOD_NOT_ALLOWED_FOR_CANARY';
  if (!request.url.startsWith('https://api.clarifai.com/')) {
    return 'BASE_URL_NOT_APPROVED';
  }
  if (request.path.includes('/billing') || request.path.includes('/account')) {
    return 'GOVERNANCE_PATH_BLOCKED';
  }
  if (policy.inferenceOnly !== true) return 'POLICY_INCOMPLETE';
  return 'INFERENCE_METHOD_ALLOWED';
}

預設 15 requests per second 與 plan 上限分流

Clarifai 官方 Rate Limits 文件目前列出所有使用者預設 15 requests per second，若需要 customized limit 要聯絡 Clarifai。這是 API request rate，不是每模型免費 token 額度，也不是每個學生都各有 15 RPS。班級共用的 worker 必須把所有學生 job 合併到一個 provider budget，不能以多個前端或多個 project 把限制假裝放大。

同一份官方 Account and Billing 文件又把 Pay-As-You-Go plan 描述為最高 100 requests per second；這是 plan feature，不應覆蓋 rate-limit reference 對所有使用者的預設 15 RPS。學生 route 以兩者較小的 15 RPS 作本地 cap，直到合法 owner 從帳戶與 response headers 讀回實際 effective limit；不能把 100 當成免費額度或每個學生獨立配額。

官方文件示範被限流時可等待 15 秒再重試；主要 agent 會採更保守的單次 retry 和 local fallback。重試必須保留原始 job id、attempt、等待秒數和 credit 對帳狀態；如果 request 是否扣款不明，就停止，不以連續重試追求一個回答。

function decideClarifaiRetry(state, error) {
  if (state.attempts >= 1) return 'LOCAL_FALLBACK';
  if (error.code === 'CONN_THROTTLED' && state.creditReconciled) {
    return state.waitSeconds <= 15 ? 'ONE_RETRY_AFTER_WAIT' : 'LOCAL_FALLBACK';
  }
  if (error.code === 'CONN_TOKEN_INVALID' || error.code === 'CONN_KEY_INVALID') {
    return 'OWNER_SECRET_REVIEW';
  }
  return 'NO_RETRY';
}

Clarifai status codes 與停止分流

官方 Status Codes把 account 或 plan 問題列為 CONN_ACCOUNT_ISSUES，invalid token 是 CONN_TOKEN_INVALID，過 hourly／monthly limit 有 CONN_EXCEED_HOURLY_LIMIT 與 CONN_EXCEED_MONTHLY_LIMIT，throttling 是 CONN_THROTTLED，account limits 是 CONN_EXCEEDS_LIMITS，scope、key invalid 和 key not found 也各有代碼。這些狀態不能都用「再試一次」處理。

function classifyClarifaiError(status) {
  const stop = new Set([
    'CONN_ACCOUNT_ISSUES', 'CONN_EXCEED_HOURLY_LIMIT',
    'CONN_EXCEED_MONTHLY_LIMIT', 'CONN_EXCEEDS_LIMITS',
    'CONN_INSUFFICIENT_SCOPES', 'CONN_KEY_INVALID', 'CONN_KEY_NOT_FOUND'
  ]);
  if (status === 'CONN_THROTTLED') return 'BOUNDED_RETRY';
  if (stop.has(status)) return 'STOP_AND_OWNER_REVIEW';
  if (status === 'TRY_AGAIN') return 'ONE_RETRY_THEN_LOCAL';
  return 'NO_AUTOMATIC_RETRY';
}

帳戶問題和額度問題都要先回到 owner。學生不能自行建立第二個 PAT、修改 scope、切換 organization、加信用卡或要求提高限流；那會把一個免費 canary 變成未審核的帳務與權限變更。

30 天 expiry 與 credit ledger

Welcome bonus 的 30 天期限要以 Clarifai 帳戶實際 issuedAt／expiresAt read-back 為準。不要只保存「本月有 $5」；ledger 應將 personal 或 organization bonus、claim time、phone verification state、issuedAt、expiresAt、model、input／output usage、remainingUsd、payment state 和 post-zero action 分開保存。組織 bonus 也不能被當成個人 bonus 的第二次重試。

function admitClarifaiCredit(credit, now) {
  if (credit.provider !== 'CLARIFAI') return 'CREDIT_PROVIDER_ERROR';
  if (!['PERSONAL', 'ORGANIZATION'].includes(credit.accountType)) return 'ACCOUNT_SCOPE_UNKNOWN';
  if (!credit.issuedAt || !credit.expiresAt) return 'EXPIRY_READBACK_MISSING';
  if (new Date(credit.expiresAt) <= new Date(now)) return 'CREDIT_EXPIRED';
  if (credit.bonusCountForType > 1) return 'BONUS_COUNT_INVALID';
  if (credit.remainingUsd <= 0) return 'CREDIT_EMPTY';
  return 'CREDIT_CANARY_ELIGIBLE';
}

如果帳戶頁顯示 bonus 已過期但 local ledger 仍有餘額，以帳戶與官方 billing read-back 為準並停止。不要以刪除帳戶、換手機、建立相似 organization 或其他身份方式重新取得 bonus；那不符合本系列的合法捕獲邊界。

Model 清單與 license review

Clarifai Quick Start 建議從 Community 找到 model 並複製完整 model URL。這讓學生可以學習文字、視覺或多模態 inference，但 model URL 的可用性和授權仍須另外檢查。不同 Community Content 可能由 Clarifai 或第三方維護，條款與 model license 不會因為 welcome credit 免費而消失。

function admitClarifaiModel(model, job) {
  if (!model.url.startsWith('https://clarifai.com/')) return 'MODEL_URL_REVIEW';
  if (model.status !== 'CURRENT') return 'MODEL_STATUS_REVIEW';
  if (!model.licenseReviewed) return 'MODEL_LICENSE_REVIEW';
  if (job.production === true && model.productionApproved !== true) {
    return 'PRODUCTION_SCOPE_BLOCKED';
  }
  if (job.dataClass !== 'PUBLIC_SYNTHETIC') return 'DATA_CLASS_BLOCKED';
  return 'MODEL_CANARY_READY';
}

學生先用公開、合成、短 prompt 做比較；不要把未公開教材、病歷、客戶文件或密鑰送進 Community model。需要圖片、音訊或影片時，先確認檔案權利、模型輸入限制、保存期限和是否會進入 prediction history，再由 owner 批准。

Clarifai 的資料保存預設

Clarifai Data Privacy and Security 文件目前說明，送到 application 的 inputs 與 resulting predictions 預設會安全保存，方便在 Portal 檢視、搜尋與管理；文件同時說 private data 不會用來訓練平台模型，除非使用者明確把 inputs 和 annotations 分享到 Community。這不等於可以隨意傳送敏感資料：保存本身就是資料處理，仍需 owner 的目的、期限和權限。

文件也說會記錄 billing、platform monitoring 和 compute usage 所需的 non-sensitive metadata；官方 Privacy Policy 則涵蓋帳戶、個資、服務內容、保留和第三方分享。學生 route 預設只送 public／synthetic／去識別化資料，response 只保存必要欄位，並在本地設定 retention。若不能說清楚誰能讀 prediction history，就不啟用 live route。

function admitClarifaiData(job, policy) {
  if (!['PUBLIC', 'SYNTHETIC', 'DEIDENTIFIED'].includes(job.dataClass)) {
    return 'DATA_CLASS_BLOCKED';
  }
  if (job.containsSecret || job.containsPersonalData) return 'REDACTION_REQUIRED';
  if (policy.retentionDays > policy.maxRetentionDays) return 'RETENTION_TOO_LONG';
  if (policy.predictionHistoryOwner !== 'AUTHORIZED_OWNER') return 'ACCESS_REVIEW';
  return 'DATA_ROUTE_ALLOWED';
}

Terms 與 content 使用責任

Clarifai Terms 要求使用者遵守適用法律，且由使用者負責提交內容所需的權利、release、consent 和 permission。條款也允許 Clarifai 為提供、維護、改善服務、安全、法律遵循或其他列明目的處理內容，並保留暫停或終止帳戶與服務的權利。免費 $5 不會縮小這些責任，也不會讓學生取得第三方資料的再利用權。

因此 queue policy 要把 input ownership、model license、output use、public／private data、production／education scope 和撤銷流程寫清楚。工具呼叫只批准 local mock 或 owner 核准的 read-only action；部署、付款、刪除、修改 organization、上傳資料和對外發佈需人工接手。

function validateClarifaiPolicy(policy) {
  if (policy.shareCredential === true) return 'CREDENTIAL_SHARING_FORBIDDEN';
  if (policy.submitUnownedData === true) return 'DATA_RIGHTS_REVIEW';
  if (policy.communityPublish === true) return 'COMMUNITY_PUBLISH_REVIEW';
  if (policy.enableAutoRecharge === true) return 'AUTO_RECHARGE_FORBIDDEN';
  if (policy.deleteOrModifyResources === true) return 'DESTRUCTIVE_ACTION_REVIEW';
  return 'POLICY_VALID';
}

學生 age 與校園導入方式

由於 Terms 目前要求 18 歲或所在地法定成年年齡，未成年學生不應自行建立 Clarifai 帳戶使用本篇 route。較安全的校園做法是由符合資格的學校或教師 owner 管理單一受控帳戶，學生透過校內 job queue 提交 public／synthetic 任務；學生不接觸 PAT，不取得帳戶登入，不直接改 billing，也不以組織 bonus 建立個別共享帳戶。

即使學生已成年，也要由本人決定是否完成手機驗證與接受條款；主 agent 只能解釋官方流程與風險，不能代填身份、代收 SMS、代為 Claim credits 或代替本人同意 Privacy Policy。校園若要長期使用，需另外確認校方資料處理、保存、家長通知和模型輸出評量規則。

學生 job 的最小 inference workflow

一個安全的學生 job 可以是：學生提交明確學習目標；worker 做資料分類和年齡／owner scope 檢查；確認 $5、期限、model、license、rate 和 local budget；送一個短 public prompt；保存遮罩後 usage 與 response；由學生檢視輸出並標註模型、時間和限制。worker 不應默默把失敗 job 轉成付費 request，也不應在沒有新批准時替學生換模型。

function runClarifaiStudentJob(job, state) {
  const owner = acceptClarifaiOwner(state.owner);
  if (owner !== 'OWNER_SCOPE_CONFIRMED') return { state: owner };
  const credit = admitClarifaiCredit(state.credit, state.now);
  if (credit !== 'CREDIT_CANARY_ELIGIBLE') return { state: credit };
  const data = admitClarifaiData(job, state.policy);
  if (data !== 'DATA_ROUTE_ALLOWED') return { state: data };
  const model = admitClarifaiModel(state.model, job);
  if (model !== 'MODEL_CANARY_READY') return { state: model };
  return { state: 'ONE_SYNTHETIC_INFERENCE_READY', studentReceives: ['jobId', 'result', 'redactedUsage'] };
}

本機 simulator 先於 live canary

工作區沒有授權 Clarifai 帳戶，所以先在本地 simulator 測試 $5、30 天 expiry、personal／organization bonus count、PAT scope、model license、15 RPS、status code、auto recharge block、資料分類與 fallback。simulator 的成功只代表 policy 能在已知輸入下正確停機，不代表帳戶已完成手機驗證，不代表 credit 已入帳，也不代表 live response schema 已通過。

function simulateClarifai(state) {
  return {
    credit: admitClarifaiCredit(state.credit, state.now),
    billing: decideClarifaiBilling(state.billing),
    data: admitClarifaiData(state.job, state.policy),
    rate: state.requestsInSecond <= 1 ? 'QUEUE_SAFE' : 'QUEUE_WAIT',
    externalRequestSent: false,
    secretRead: false
  };
}

owner 日後若批准 live canary，只使用一個 public synthetic prompt、一個已核准 model URL、短 output、server-side secret 和一個 job。canary 需記錄 status code、response shape、usage、credit remaining、expiresAt、prediction history policy 和撤銷步驟；任一項讀回不一致就停用 route。

Usage ledger 與費用估算

Clarifai 官方 pricing 會依模型與 modality 顯示計費方式，welcome credit 也可能用在 serverless model access 或 dedicated deployment。每次 job 要記錄 endpoint、model URL、input／output token 或 media unit、pricing snapshot、estimatedUsd、dashboard usage、remainingUsd 和是否仍在 bonus window。若官方頁或 dashboard 沒有回傳足夠 usage，就標記 USAGE_UNRESOLVED，不把估算當成已結算。

function recordClarifaiUsage(grant, usage, now) {
  if (!grant.issuedAt || !grant.expiresAt) return { state: 'GRANT_DATES_MISSING' };
  if (!Number.isFinite(usage.estimatedUsd) || usage.estimatedUsd < 0) {
    return { state: 'USAGE_UNRESOLVED' };
  }
  const remainingUsd = Math.max(0, grant.remainingUsd - usage.estimatedUsd);
  return {
    state: remainingUsd > 0 ? 'USAGE_RECORDED' : 'CREDIT_STOP',
    at: now,
    remainingUsd,
    modelUrl: usage.modelUrl,
    inputUnits: usage.inputUnits,
    outputUnits: usage.outputUnits,
    dashboardReadBack: usage.dashboardReadBack === true
  };
}

local cap 應低於 $5，保留平台同步、模型價格和 rounding 的誤差。若使用多模態或 dedicated deployment，先要求 owner 確認它是否適用 welcome credit；不要以「帳戶還有餘額」推導所有 Compute 功能都能免費使用。

Prediction history 與 retention stop

Clarifai 預設保存 inputs 與 predictions，這對學習比較有用，卻也會擴大資料責任。學生 agent 應在送出前顯示資料類別、預計保存位置和刪除責任；不能把一次課堂的原始 prompt 和輸出無限期留在 Clarifai application 或本地 log。需要保留的證據可採短摘要、model URL、日期和遮罩結果，原始資料依校方政策處理。

function decideClarifaiRetention(state) {
  if (state.dataClass !== 'PUBLIC_SYNTHETIC') return 'RETENTION_OWNER_REVIEW';
  if (state.predictionHistoryEnabled !== true) return 'HISTORY_POLICY_UNKNOWN';
  if (state.retentionDays > 30) return 'RETENTION_TOO_LONG_FOR_CANARY';
  if (state.deleteOwner !== 'AUTHORIZED_OWNER') return 'DELETE_OWNER_MISSING';
  return 'RETENTION_CANARY_ALLOWED';
}

Local fallback 與模型比較

Clarifai welcome route 的最佳用法是短期比較與教學：同一個 synthetic prompt 可在本地模型、Clarifai model 和另一個已批准 provider 間比較輸出品質、延遲、引用需求和成本。比較結果要保留 model、日期、prompt class 和限制，不能只挑最好的回答宣稱某個 provider 永遠較強。

function chooseClarifaiFallback(state) {
  if (state.localModelReady) return 'USE_LOCAL_MODEL';
  if (state.approvedSecondaryReady && state.ownerApproved) return 'SECONDARY_REVIEW';
  if (state.canAskStudentToNarrow) return 'NARROW_JOB';
  if (state.humanReviewerReady) return 'HUMAN_REVIEW';
  return 'NO_EXTERNAL_INFERENCE';
}

當 $5 用完、30 天到期、15 RPS 被打滿、PAT scope 不足、model 不可用或資料 policy 不明時，fallback 必須是明示狀態。主 agent 回覆學生「本次沒有核准的外部燃料」比靜默觸發 auto recharge 更安全，也讓課程能教學生理解資源限制。

Terms 的帳戶與內容責任

Clarifai Terms 要求使用者判斷適用法律、年齡和帳戶資格，且對提交到服務的 Your Content 具備必要權利與同意。條款也允許在安全、支援、服務改善、法律或違規調查等情況處理內容，並可因違規暫停或終止帳戶。學生 route 不能以「只是免費試用」降低這些責任。

function validateClarifaiSubmission(job) {
  if (job.ownerConsent !== true) return 'OWNER_CONSENT_REQUIRED';
  if (job.contentRights !== 'CONFIRMED') return 'CONTENT_RIGHTS_REVIEW';
  if (job.ageEligibility !== 'CONFIRMED') return 'AGE_REVIEW';
  if (job.dataClass === 'PRIVATE' || job.dataClass === 'PII') return 'SENSITIVE_DATA_BLOCKED';
  if (job.communityShare === true) return 'COMMUNITY_SHARE_REVIEW';
  return 'SUBMISSION_ALLOWED_FOR_CANARY';
}

工具呼叫與 production boundary

即使 Clarifai platform 提供 Agents、Pipelines、Reasoning Engine 和部署能力，本篇只批准 inference canary。工具呼叫先用 local mock；若將來要讓模型呼叫外部工具，需額外設定 read-only、domain allowlist、人工批准、timeout、輸出驗證和 audit log。production write、刪除、付款、部署 GPU、修改 organization 和發布結果都不屬於免費 credit 文章的自動範圍。

function gateClarifaiToolCall(call, state) {
  if (call.mode === 'LOCAL_MOCK') return 'TOOL_MOCK_ALLOWED';
  if (state.ownerApproved !== true) return 'OWNER_APPROVAL_REQUIRED';
  if (call.mutatesExternalState === true) return 'PRODUCTION_WRITE_BLOCKED';
  if (!state.allowedDomains.includes(call.domain)) return 'DOMAIN_BLOCKED';
  if (call.timeoutMs > 10000) return 'TIMEOUT_TOO_LARGE';
  return 'READ_ONLY_TOOL_REVIEW';
}

持續監測的官方欄位

持續捕獲應在每次啟用前重新查核 Account and Billing 的 bonus 金額與期限、plan、payment method、auto recharge、monthly spend limit；Quickstart 的 model URL 與 OpenAI endpoint；Authentication 的 PAT／key scope；Rate Limits 的 RPS；Status Codes；Privacy Security 的保存預設；Terms 的年齡與內容責任。每個 snapshot 保存查核日期與頁面 URL，不能只保存一個「Clarifai free=true」。

function compareClarifaiSnapshot(previous, current) {
  const fields = ['bonusUsd', 'expiresAt', 'rps', 'autoRecharge', 'spendLimitUsd'];
  const changed = fields.filter((key) => previous[key] !== current[key]);
  if (!current.officialPagesReachable) return { state: 'SOURCE_UNAVAILABLE' };
  if (changed.length) return { state: 'REVIEW_REQUIRED', changed };
  if (current.paymentMethodPresent) return { state: 'PAYMENT_REVIEW' };
  return { state: 'NO_MATERIAL_CHANGE' };
}

帳戶內的 balance、issuedAt、expiresAt、bonus count、key scope 和 prediction history 仍要由合法 owner read-back。公開文件和文章 snapshot 不能替代 private account evidence；兩者不一致時採較保守的 blocked 狀態，等 owner 重新確認。

本機驗收與未執行項目

本篇本機驗收會檢查中文字數、H2、官方 URL、站內連結、Gutenberg block 成對、JavaScript 範例可解析、真實 secret、技術殘留和零寬字元。因為工作區沒有授權 Clarifai 帳戶，驗收不包含註冊、手機驗證、Claim credits、建立 PAT、payment、live inference、檔案上傳、model deployment、organization bonus 或 WordPress 寫入。

function assertClarifaiDraft(report) {
  if (report.han < 4000) throw new Error('HAN_TEXT_TOO_SHORT');
  if (report.h2 < 20) throw new Error('H2_COVERAGE_TOO_SMALL');
  if (report.officialUrls < 3) throw new Error('OFFICIAL_EVIDENCE_TOO_SMALL');
  if (report.internalLinks < 1) throw new Error('INTERNAL_LINK_MISSING');
  if (!report.blocksBalanced || report.jsErrors.length) throw new Error('MARKUP_INVALID');
  if (report.secret || report.residue || report.zeroWidth) throw new Error('DRAFT_SAFETY_FAILED');
  return 'DRAFT_ACCEPTED';
}

主要 agent 的啟用閘門

只有當 owner eligibility、age、phone verification、plan、$5 balance、30 天 expiresAt、model URL、license、PAT scope、15 RPS、data retention、local budget、auto recharge disabled、post-zero hard stop、fallback 和撤銷路徑都已讀回，Clarifai route 才能進入單次 synthetic canary。任何未知都標記 blocked，不以 marketing 語句或學生的口頭說明補足。

function enableClarifaiRoute(state) {
  const gates = [
    state.ownerVerified,
    state.ageConfirmed,
    state.phoneVerified,
    state.creditReconciled,
    state.expiryKnown,
    state.modelApproved,
    state.keyScopeApproved,
    state.rateKnown,
    state.dataPolicyApproved,
    state.autoRecharge === false,
    state.postZeroAction === 'BLOCKED',
    state.fallbackReady,
    state.revocationReady
  ];
  return gates.every(Boolean) ? 'CANARY_ALLOWED' : 'ROUTE_BLOCKED';
}

帳戶 read-back 與公開文件分層

本篇的官方帳務文件證明的是 Clarifai 公開提供一筆 $5、30 天 welcome bonus，以及 personal／organization 的資格規則；它不證明某一個帳戶今天已完成 phone verification、不證明 bonus 還剩多少，也不證明指定 model 目前可以用這筆 credit。主 agent 要把公開 snapshot 與 owner 私有 read-back 分開保存：前者包含查核日期、官方 URL 和條款版本，後者只保存遮罩後的 plan、credit、expiresAt、scope 和 payment state。

當兩層證據不一致時，採較保守的 blocked。比如公開文件仍寫 $5，但 owner dashboard 顯示 bonus 已失效；或 PAT 能登入但 model request 回傳 scope insufficient；或 local ledger 估算仍有餘額、billing read-back 卻顯示 auto recharge。這些都不是要學生自行修正的錯誤，而是要 owner 重新確認帳戶、模型和付款責任的訊號。

課堂成本分配與輸出評量

若教師要把一筆 $5 用在課堂，不應用「每個學生都分到固定 token」的說法，因為不同 model 和 input／output 長度會產生不同成本。可以改成每組固定一個合成任務、最多一次 canary、固定輸出上限和本地 budget；學生評量重點放在 prompt 設計、錯誤辨識、來源與 license、資料分類、輸出驗證和停止條件，而不是誰消耗最多 credit。

教師或 owner 可在不暴露 PAT 的情況下分享遮罩後的 response、model URL、時間、status、估算成本和人工註解。學生要知道模型輸出只是候選答案，應與課本、官方文件或可驗證資料比較；遇到幻覺、過時資訊、偏見或不適合的內容，應記錄問題並停止擴大，不用更多免費 request 盲目投票。

function scoreClarifaiLesson(result) {
  const checks = [
    result.promptClassified,
    result.modelRecorded,
    result.outputCited,
    result.limitObserved,
    result.costRecorded,
    result.stopRuleRespected
  ];
  return checks.every(Boolean) ? 'LESSON_EVIDENCE_COMPLETE' : 'LESSON_REVIEW_REQUIRED';
}

OpenAI 相容不代表風險相同

OpenAI-compatible endpoint 只降低 client adapter 的改寫成本，不會把 Clarifai 的 PAT scope、Community model URL、prediction history、$5 expiry、status codes、model license 或 Pay-As-You-Go billing 變成 OpenAI 的規則。主要 agent 應在 provider adapter 層保留 provider、model、plan、creditKind、dataPolicy 和 error namespace，禁止把一家的 retry 或 billing 假設直接複製到另一家。

這個分層也有助於日後替換模型：學生 job 只要求「文字摘要、最大輸出、公開資料」，adapter 再依 Clarifai model contract 產生 request。若 model 不支援某個參數、工具或多模態輸入，回傳 unsupported，而不是默默刪掉參數後繼續執行。錯誤透明比表面上的相容更適合教學和長期監測。

本篇結論與下一篇規則

截至 2026-08-25，Clarifai welcome credit 是可以放入學生主要 agent 候選的官方條件式入口：Pay-As-You-Go plan 內，一次性 $5，需 owner 完成手機驗證，30 天到期，personal 與 organization 各最多一筆。它適合短期文字或多模態模型 canary、教學比較與受控 inference，不是每月刷新、可共享或可永久使用的免費 token。

最重要的停止線是：未達 age eligibility、owner 未批准、bonus 未 read-back、expiry 不明、PAT scope 不足、model license 不明、資料不適合、15 RPS 超限、credit 用完、payment method 或 auto recharge 出現時，立即停在本地。學生不代驗證手機、不拿 key、不分享帳戶、不建立多個 bonus、不充值、不繞過 status code。

下一篇只接受另一個能由官方頁面重新證明免費 credit、免費 token、免費模型配額或學生方案的未收錄候選。若只有舊文件、第三方列表、需要付費才能開始、沒有清楚的資料政策或無法讀回額度，就保留為排除項，不為了湊篇數寫成燃料。

本篇工作邊界：未進行 Clarifai 註冊、登入、手機驗證、Claim credits、建立或取得 PAT／API key、付款、live inference、檔案上傳、model deployment、外部 publication 或 WordPress 寫入；所有 secret 僅以環境變數名稱表示，學生只使用經 owner 核准的 job、結果與遮罩後 usage。