把事實查核，
接進你的應用。

01 / 開始呼叫

第一個查核請求

下方範例供本站前端使用，也可在本站頁面的開發者工具 Console 執行。將 text 換成你要查核的具體主張；呼叫前，服務維運者需先完成模型設定。

const response = await fetch("/api/fact-check", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    text: "非學校型態學生，國中小以下目前沒有普遍補助"
  })
});
const result = await response.json();
console.log(result);

POST 必須來自本站相同協定、主機與連接埠；Origin 由瀏覽器自動附上。 跨來源、缺少 Origin 或 Origin 為 null 都回 403，不開放跨來源 CORS 預檢。

內容較長或包含敏感資訊時，建議使用 POST，避免文字出現在網址歷史或 access log。請勿在呼叫端傳入 OpenRouter 金鑰。

curl --get 'https://check.vtaiwan.tw/api/fact-check' \
  --data-urlencode 'text=非學校型態學生，國中小以下目前沒有普遍補助'

curl --get 'https://check.vtaiwan.tw/api/fact-check' \
  --data-urlencode 'text=非學校型態學生，國中小以下目前沒有普遍補助' \
  --data-urlencode 'url=https://civic.vtaiwan.tw/issues/7'

02 / 輸入參數

一段文字，一個選填網址

POST 使用 Content-Type: application/json，請求本文上限為 128,000 bytes。沒有網址時請省略 url，不要傳空字串或 null。

03 / 讀懂回應

判斷結果，也保留證據脈絡

以下是「證據不足」的格式示例，並非對範例主張的實際查核結果。completed 表示流程完成，仍可能得到 insufficient_evidence。

{
  "text": "非學校型態學生，國中小以下目前沒有普遍補助",
  "status": "completed",
  "moderation": {
    "decision": "allow",
    "categories": []
  },
  "factuality": 0.7,
  "confidence": 0.4,
  "verdict": "mostly_supported",
  "related_checks": [],
  "feedback": "查無相關查核資料，以下為常識判斷：此主張與常見制度描述大致相符，請自行查證。",
  "meta": {
    "request_id": "example-request-id",
    "cofacts_candidates": 0,
    "cofacts_relevant": 0,
    "cofacts_human_checks": 0,
    "cofacts_ai_checks": 0,
    "url_context_used": false,
    "url_context_allowlisted": false,
    "no_relevant_evidence": true,
    "warnings": []
  }
}

factuality

0～1，表示證據支持主張的程度。它不是主張為真的機率；無證據時的 0.5 表示無法判定。

confidence

0～1，表示判斷所依據的證據是否充分、可靠且一致。應與 factuality 一起閱讀。

feedback

繁體中文說明，補充證據限制、適用範圍與需要進一步查證之處。

related_checks

相關查核陣列，以 cofacts_human／cofacts_ai 區分人工與 AI 回覆。每筆包含查核文字與 Cofacts 原文 url；有引文時另附 reference_url／reference_urls。

meta

包含 request ID、候選及證據數量、是否使用 URL 背景，以及 warnings 警告。

六種判斷結果

兩種分數各有用途：retrieval_score 只是 Cofacts 搜尋排序；relevance_score 是 0～1 的語意相關程度。兩者都不代表真假，不能直接換算 factuality。

04 / 狀態與錯誤

先看 HTTP，再看 status

HTTP 200 包含以下三種情況。串接時，請一併檢查 JSON 的 status 與 meta.warnings。

completed

查核流程完成；證據不足也是有效結果。

partial

部分上游服務失敗，根據仍可取得的證據完成綜整。警告會列出失敗階段。

blocked

安全層停止查核；factuality、confidence 與 verdict 為 null，related_checks 為空陣列。

安全分類 allow 會繼續；review 也會繼續，但保留旗標。引用待查言論、新聞、公共政策及學術討論等情境，會納入查核例外考量。

Gemma（證據綜整）失敗回 502。Safeguard 暫時失敗時跳過安全分類，並將 moderation.decision 標記為 skipped，以 partial 狀態繼續查核；只有缺少金鑰 （OPENROUTER_API_KEY）等設定錯誤才回 502。Cofacts 搜尋或語意初篩失敗時一律回 502。單篇詳細證據失敗則保留其他資料。

查核回應附有 X-Request-Id 與 Cache-Control: no-store。GET /health 只確認服務能回應，不代表外部模型與資料來源皆正常。

05 / 查核如何進行

先找相關證據，再綜整判斷

1. 1

   安全分類

   OpenRouter Safeguard 判斷內容是否能進入查核流程。

2. 2

   搜尋候選內容

   Cofacts 召回最多 15 篇候選文章；選填 URL 的抓取在此階段平行進行。

3. 3

   篩出真正相關的文章

   Workers AI gpt-oss-20b 批次判斷語意相關性，最多保留 5 篇。此階段不判真假。

4. 4

   取得詳細證據

   只讀取通過初篩文章的人工與 AI 查核回覆，並保留來源連結。

5. 5

   綜整結果

   Gemma 根據整理後的證據產生判斷；查無相關 Cofacts 查核資料時（包括只附網址、沒有任何查核回覆的情況），改以模型常識推估，回傳的信心值上限 0.5，證據不足時回傳證據不足。