核心概念

本頁說明本服務的核心功能與重點機制的設計。

物件模型與可變性（Mutability）

Loading diagram...

在本服務的物件中，擁有三種不同的可變性：

版本化且不可變：需作為 AI 批閱基礎參照的資源（如題目、評分標準等），以及學生提交本身。每次更新都將產生新版本，舊版本無法變更。
部分不可變：考試。考試的題目清單 questions 在建立當下固定，無法變更。其餘欄位則可更新。
可變：學生名冊等，不影響提交與批閱任務的其他資源。對其修改將可立即生效。

版本鎖定

平台資源或物件彼此引用時，將需要使用版本化參照，以指定引用的版本。

建立考試時，questions 中的參照會被解析成明確版本並儲存。例如使用 "q_abc:latest" 時，該題目會在當下解析為最新版本（例如 "q_abc:2"）並儲存。
題目引用共用評分標準時，scoring.rubric_ref 在題目寫入時即解析為明確版本，例如使用 rub_fhz:1。
此後，不論題庫如何演進，該些引用資源的版本均會固定，且不受該些引用資源更新影響。例如，發布 rub_fhz:2 將不影響任何已引用 rub_fhz:1 的題目及其考試。

因此：

考試內容不能編輯。 PATCH /exams/{id} 只接受標籤欄位（name、description、custom_id、metadata），送出 questions 欄位將得到 409 ERR_EXAM_LOCKED 錯誤。若要以不同內容批閱，請建立新的考試。
提交時不需傳送任何版本參數。 因 exam_id 引用的批閱對象與評分標準均為包含確切版本的參照。
封存不影響解析。 封存題目僅退出題庫的列表端點、且不能再被新考試引用。已引用的考試將照常接受提交。

非同步批閱

所有 AI 批閱均為非同步工作。提交將回應狀態碼 201（批次提交為 200），代表請求已受理並排入批閱，但不代表批閱完成。

AI 對每筆題目作答（學生對單一題目的回答）均獨立進行批閱，因此可能會有同一份考試提交之中，每筆題目作答批閱進度不一致的狀況。

每筆題目作答將各自經歷 pending → processing → completed | failed 的狀態變化，考試提交則在每一筆作答都到達終態時變為 completed。考試提交的狀態不會提示「部分完成」。

若要查看一份考試提交內，逐筆題目作答的批閱進度，請讀取考試提交端點 GET /submissions/{id}。其回應中每一筆題目作答 responses 物件中，都會內嵌其批閱狀態（status）及預計完成的時間（eta）。

批閱「完成但 0 分」與「失敗」的區別

在相對少見的特殊狀況中，AI 批閱可能會產生 0 分的結果。但此結果不必然代表 AI 批閱過程中系統產生錯誤。請依照下表獨立分別：

情況	作答狀態	是否有批閱結果	處理方式
正常批閱	`completed`	有，`outcome: graded`	—
空白作答、敏感內容	`completed`	有，0 分，`outcome` 說明原因	有異議時請提交覆核
批閱逾時、內部錯誤	`failed`	沒有	於 Studio 重新排程

冪等性

所有建立資源的 POST 端點均接受冪等鍵（POST /submissions 端點則為強制要求）。建議您永遠都設置冪等鍵，確保相同請求重送時，可以正確識別並去重。

單筆建立使用 Idempotency-Key 請求標頭。
批次建立提交端點，則改使用每筆項目內的 idempotency_key 內容欄位，不使用標頭。

冪等鍵保留 24 小時，期間內的行為如下。

情況	結果
首次請求	正常處理
同鍵、同內容	重播先前存下的回應，不重新處理
同鍵、不同內容	回應 `409 ERR_DUPLICATE_TXID` 錯誤

在首次請求的 24 小時以後，原有冪等鍵將過期且可以重用。使用該冪等鍵的請求將視為全新的請求。

請注意，若您獲得 409 ERR_DUPLICATE_TXID 時，不應視為請求成功。 它表示同一把鍵送出了不同的內容。

若這確實是新的操作，請產生新的鍵；若原意是重送，則問題出在客戶端於兩次請求之間改動了請求內容，請重新檢閱請求，不應視為「已處理完成」而略過。

冪等鍵的取法

本服務的冪等鍵沒有格式限制，但建議您使用 UUIDv7 或其他結構化的字串，以便清楚易讀的辨識來源。例如一筆提交的冪等鍵可以設定為：

sub-{student_ref}-{exam_id}-{yyyymmdd}

API 共通的請求與回應規則

回應格式

{
    "data": ...
}

Webhook 事件的遞送則不適用以上格式，請參閱 Webhook 頁面的獨立說明。

分頁 Paginating

支援分頁的 API 均使用游標分頁（Cursor based pagination）。使用 limit 與 next_cursor 指定回應的單頁大小與頁數位置。 limit 預設 20、最大 100；帶入前一頁的 next_cursor 取得下一頁。游標是不透明權杖，請勿解析或自行組合。持續翻頁至 has_more 為 false 為止。

過濾 Filtering

支援過濾的 API 均使用扁平的物件參數，並給定物件 ID 或版本化參照。例如 ?exam_id=exam_abc123。

排序 Sorting

支援排序的 API 端點均使用 sort 參數指定排序方式，在該參數依序指定排序的欄位與冪等。

在欄位名稱前加上前綴 - 為遞減，+ 或無前綴為遞增。

排序支援多欄位，例如?sort=-created_at,status。但包含無法辨識的欄位時，該請求會被拒絕。

各項資源預設排序為：

批閱結果版本歷史：-version
覆核清單：-graded_at
其他資源：-created_at

時間數值

本服務所有時間戳記一律為 UTC 的 ISO 8601（"2026-03-02T09:30:00Z"）。

版本演進

主版本置於路徑（/v1）。破壞性變更會以新的路徑版本（/v2）發布，/v1 將持續運作，直至公告的日落日期。

在同一個版本內，API 規格將進行單調新增。未來將可能新增選填的請求欄位、回應欄位、端點、事件型態、列舉值與錯誤代碼；既有欄位在相同主版本內，不會被改名、移除、更改型別或用途。

客戶端實作時，必須容忍未知欄位，並可以正確忽略而不產生錯誤。

進入淘汰階段的版本，請求回應將另帶 Deprecation、Sunset 與 Link 標頭。