本指南依據 Cloudflare 目前的模型文件與發布示例。BIG CHANGE 未執行此 API，也未測量它在支援票單上的準確度。
模型 ID 為 @cf/cloudflare/clef-omni，位於 Workers AI。這是決策模型：呼叫端定義具型別的問題與允許的選項，接著取得這些選項的分數。它不會撰寫支援回覆。Cloudflare 也發布了開放權重，但以下步驟使用其託管端點。Cloudflare 對速度與基準測試的數據是其自身主張，不能證明此工作流程在你的票單上會有多好。
準備存取權與有限範圍的問題集
你需要具備 Workers AI 存取權的 Cloudflare 帳戶、帳戶 ID、Workers AI API 權杖，以及安裝了 requests 的 Python，或能發出相同 HTTP 請求的工具。Cloudflare REST 設定指南說明如何在控制台複製帳戶 ID 並建立權杖。手動建立的權杖需要 Workers AI - Read 與 Workers AI - Edit 權限。請勿將權杖放進票單或原始碼控制。
傳送真實票單或附件，代表將客戶內容傳送給 Cloudflare 處理。Cloudflare Workers AI 資料使用頁面表示，未經明確同意，不會使用該內容訓練 Workers AI 提供的模型或改善服務；頁面也指出，若 Workers AI 搭配 R2 或 KV 等儲存服務，內容可能會被儲存。傳送客戶票單前，請檢查適用的 Cloudflare 合約及組織的客戶資料規範，並在可行時減少或遮蔽個人資訊。Cloudflare 的不訓練聲明本身，不能證明你有權傳送特定客戶資料。
先從文字開始，這樣你可以在加入媒體前檢查回應。Cloudflare 自己的支援示例使用狀態 Checkout has been failing for every customer for the last hour，並提出三個問題：是否緊急（noul，是／否型別）、應由哪個團隊處理（choice），以及影響程度為何（score）。這是文件中的示例，不是實際觀察到的事件。API 接受字串或結構化物件／陣列作為 state。questions 對照表必須包含 1 至 64 個問題 ID；每個項目都有型別與指示，而 choice 與 score 則使用 criteria 定義允許的回答。
傳送文字請求
在環境中設定 CLOUDFLARE_AUTH_TOKEN，並替換下方的帳戶 ID。此 Python 請求改編自 Cloudflare 模型示例中的確切端點與欄位：
import os
import requests
account_id = "your-account-id"
token = os.environ["CLOUDFLARE_AUTH_TOKEN"]
payload = {
"model": "clef-omni",
"state": "Checkout has been failing for every customer for the last hour.",
"questions": {
"urgent": {
"type": "noul",
"instructions": "Is this support request urgent?",
},
"team": {
"type": "choice",
"instructions": "Which team should handle this request?",
"criteria": {
"billing": "Payments, invoices, and refunds",
"technical": "Outages, errors, and configuration",
"sales": "Plans and upgrades",
},
},
"severity": {
"type": "score",
"instructions": "How severe is the customer impact?",
"criteria": ["No impact", "Minor", "Major", "Critical"],
},
},
}
response = requests.post(
f"https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/cloudflare/clef-omni",
headers={"Authorization": f"Bearer {token}"},
json=payload,
timeout=60,
)
response.raise_for_status()
print(response.json())成功檢查時，請查看 answers 中位於相同 urgent、team 與 severity ID 下的回應項目。Cloudflare 將第一項描述為緊急程度的機率，第二項描述為帶有各選項機率的所選團隊，第三項則是最低等級為零、按機率加權的分數。API 也記載了 model 與 usage 回應欄位。在將結果對應到應用程式前，請檢查帳戶收到的完整 JSON。機率是模型針對所提供問題與狀態的輸出，不保證真實票單應歸入該佇列。採取行動前，應由人員將票單及附件與建議路由比對。
加入照片、錄音或影片
Cloudflare 的發布請求將選擇性媒體放在獨立的 images、audio 與 videos 陣列，內含嵌入式 base64 data: URL。例如，其範例使用 data:image/png;base64,...、data:audio/mpeg;base64,... 與 data:video/mp4;base64,...。若要在執行 requests.post 前將一個本機檔案加入 Python payload，請先編碼，再將資料 URL 附加到相應陣列：
import base64
from pathlib import Path
def add_media(payload, field, file_path, mime_type):
raw = Path(file_path).read_bytes()
encoded = base64.b64encode(raw).decode("ascii")
payload.setdefault(field, []).append(f"data:{mime_type};base64,{encoded}")
# Examples: use only the files present in the ticket, with their real MIME types.
# add_media(payload, "images", "photo.png", "image/png")
# add_media(payload, "audio", "recording.mp3", "audio/mpeg")
# add_media(payload, "videos", "clip.mp4", "video/mp4")在 POST 前執行 add_media。保持 state 客觀，並描述各附件內容；只詢問可由現有票單與媒體回答的問題。Cloudflare 的發布示例使用一張設備照片、一段錄音與一段風扇影片，詢問三個關於可見和可聽細節的是非題。支援應用程式可以在 state 保留自己的票單欄位，在 criteria 保留自己的允許佇列，但應以實際工作流程檢查這些定義。服務不接受遠端媒體 URL。
編碼前先檢查限制。模型頁面允許最多四張 PNG、JPEG 或 WebP 圖片，每張最多 4 MiB、16 百萬像素，解碼後圖片總量為 8 MiB。最多允許四段音訊，每段最多 8 MiB、300 秒；以及兩段影片，每段最多 16 MiB、60 秒。音訊與影片合計的解碼後限制為 16 MiB。影片每秒取樣兩個影格；若請求中的每段影片都有音軌，則會將音軌與影格一併使用。附件過大或過長時，請由人員選取相關的較小片段，或改用純文字檢查並另行檢視原始媒體。裁切或縮短的檔案不能視為完整證據。
檢查成本、上下文與失敗處理
Cloudflare 目前列出的 Clef-omni 價格為 每百萬輸入 token 0.15 美元，並表示不對輸出 token 收費。媒體會按此費率轉換為輸入 token。模型頁面描述音訊每分鐘約 780 token；最高解析度影片每分鐘最多約 15,400 token，若影片有聲音還會加計音訊 token。圖片成本取決於縮放後的圖片，每張上限為 1,024 token。這些是計費規則，不是每個附件的固定價格。
託管模型的上下文長度為 64,000 token。媒體與問題都會計入。若超出此視窗，Cloudflare 表示請求會失敗；否則 state 中的長文字可能會被截斷以符合長度限制。因此，收到答案並不能證明模型考量了長票單的每一行。請求失敗時，檢查 HTTP 錯誤，並在文件限制內減少或移除附件後重試。成功時，確認預期問題 ID 都存在，保留原始票單供檢視，並將建議路由與證據比對。模型機率或可協助審查者集中注意力，但服務保證或安全的自動化門檻，必須以你自己的標記票單評估。
重大變化
Cloudflare 10 月 9 日的發布，將音訊與影片加入原本已用於文字與圖片型問題的託管 Clef 決策模型路徑。開發者可透過單一 Workers AI 請求提交一份含支援媒體的票單狀態，並取得依固定 schema 編列的答案。應用團隊仍須決定 schema 中要放哪些問題、以自己的票單測試效能，並在回覆或路由動作前要求人工核准。
來源與延伸閱讀
- Cloudflare Clef-omni 模型文件，於 2026 年 10 月 10 日查閱。託管模型 ID、API 欄位與示例、媒體與上下文限制、回應格式及標示價格的主要參考資料。文件描述服務行為；BIG CHANGE 未執行該請求。
- Cloudflare 的 Clef-omni 發布文章，2026 年 10 月 9 日。確認發布日期並提供內嵌媒體請求示例。效能與基準測試數據是 Cloudflare 自身主張。
- Cloudflare Workers AI REST 設定，最後更新於 2026 年 9 月 15 日，並於 10 月 10 日查閱。說明如何取得帳戶 ID 與 API 權杖，以及手動建立權杖所需的權限。
- Cloudflare Workers AI 資料使用，最後更新於 2026 年 4 月 21 日，並於 10 月 10 日查閱。說明 Cloudflare 如何處理客戶內容、其聲稱未經明確同意不會用於訓練或改善服務、使用獨立儲存服務時可能儲存內容，以及適用的合約界線。此資料不判定開發者是否可提交特定票單或錄音。
