公開 API

介面約定與鑑權

依端點辨識鑑權、回應包裝和錯誤正文。

呼叫公開 API 前,先確認對應端點的鑑權方式和回應結構。

欄位

型別

欄位

型別

成功回應依端點解析:目錄、查詢、/me 和同步狀態使用 data;釋出、whoami、刪除使用 result;標題匹配直接回傳 version、decision、candidates。番劇預覽使用頂層 previewUrl。

標題匹配的 candidates[].matchScore 只能比較大小,不是百分比。evidenceSummary.matchClass 為 exact、structured_exact、compact、base 時分別為 100、95、90、80;只由召回(strict_recall、fuzzy_recall)找到的候選為 1–70,有拼寫差異或忽略了一個詞時更低;只因系列補全加入的候選為 0。召回候選同分時由 textMatch 區分先後,它同樣只能比較大小。

應用程式 JSON 錯誤包含 ok: false 和 error.code、error.message、error.requestId;reason、retryable、retryAfterMs、details 為選填欄位。缺少 retryable 不表示可以重試。公開 RSS 錯誤通常是純文字;Torznab 協定錯誤是 XML,HTTP 仍可能為 200;邊緣攔截可能回傳 HTML。先檢查 HTTP 狀態與 Content-Type,再解析正文。

釋出前用 GET 同一路徑核驗 groupSlug 與 scopes。釋出回執只保證 releaseId、revision,可能包含 torrentObjectId,不包含字幕組身份或 fileSize。資源 ID 使用端點要求的 rel_* 或 orel_*;字幕組通常用 slug,但其他類 RSS 的 groupId 使用組織 ID。

釋出重試與刪除後重新釋出

一般釋出的同一次請求建議使用 Idempotency-Key。同一 API Key、同一釋出端點重試相同內容時,保留原值;該值去除首尾空白後須為 1–256 字元。未提供或為空時視為新命令,不能依賴命令回放。超過 256 字元時回傳 422 VALIDATION_ERROR,error.details 為 { "header": "Idempotency-Key", "maxLength": 256 };伺服器不讀取請求本文,也不會釋出。跨站瀏覽器預檢目前不允許此請求標頭;需要此保證的用戶端應從伺服器呼叫。

成功命令的重試回傳原 releaseId 與 revision,不會重新釋出。即使原資源已刪除,同一個命令仍回傳舊回執,不會恢復資源;刪除後確實要使用同一種子重新釋出時,應使用新的 Idempotency-Key。

自首次受理起,Idempotency-Key 會綁定完整請求。切換釋出與預覽,或變更資源內容、Nyaa 選項、明確指定的釋出時間、上傳檔案時,應使用新鍵。上傳完成或已有回執無法略過已儲存的綁定;同鍵變更參數會回傳 409 CONFLICT。

升級前已上傳但尚未完成的請求,若缺少完整綁定,會回傳 409 CONFLICT,error.reason 為 legacy_request_binding_missing。此時請使用新鍵重新提交完整請求。已完成的舊請求仍依原回執重播。

本組在同一番劇下已經有集數鍵、版本、字幕類型、解析度、語言都相同,且種子相同的資源時,再次釋出會回傳 409 CONFLICT,error.reason 為 RELEASE_VERSION_EXISTS。這表示這份種子已經以同一版本釋出過,換新鍵重試也不會成功。

一個已儲存的種子只能用於一筆資源。JSON 請求的 torrentStorageId 指向的種子已被另一筆番劇資源、其他類資源或他人未逾期的預覽使用時,釋出和預覽都會回傳 409 CONFLICT,error.reason 為 TORRENT_IN_USE,不寫入任何內容;請改用 multipart 上傳種子檔案。同一釋出者重新釋出內容相同的番劇資源時仍回傳既有資源;自己預覽過的種子可以直接正式釋出,正式釋出後這個種子的預覽隨即失效。

字幕組狀態不是「活躍」(為「不活躍」或「已停用」),或 Key 在請求處理期間被撤銷時,釋出會回傳 403 FORBIDDEN。

成員離開或被移出字幕組時,他在該組的 API Key 同時撤銷,之後使用這些 Key 的請求回傳 401;即使再次加入字幕組,這些 Key 也不會恢復,需要新建。變更成員角色不影響 Key。

請求裡的磁力連結須包含 v1 infohash:xt=urn:btih: 後接 40 位十六進位或 32 位 base32。xt 鍵不區分大小寫,XT=urn:btih:… 同樣接受;同時帶 urn:btmh 的混合磁力連結,urn:btmh 寫在 urn:btih 前面也接受。

以下請求回傳 422 VALIDATION_ERROR,error.message 說明違反的規則:

  • 集數鍵為空;
  • episode 與 episodeKey 不一致;
  • 磁力連結沒有 xt=urn:btih,或其中不是有效的 v1 infohash,或種子的磁力連結裡沒有 infohash;
  • 沒有種子,又缺少大於 0 的檔案大小或 infohash;
  • torrentStorageId 不存在或不屬於本組;
  • 欄位超過長度上限,error.details.fieldErrors 列出超限的欄位。

這些請求原樣重試或換新鍵重試都不會成功。

數字集數鍵依規範寫法儲存:去掉前導零,小數再去掉末尾的零。05.5 和 5.50 都存為 5.5,01 存為 1,01-13 存為 1-13。

番劇釋出未傳 resolution 時,只從標題裡寫明解析度的片段辨識:1080p、1080P、1080i,1920x1080、3840x2160 這樣的寬 × 高,以及獨立成詞的 4K。2160p 與 3840x2160 辨識為 2160p,寫明 4K 時才是 4K。集數、不帶 p 或 i 的裸數字(如 1080、720、2160)、校驗碼裡的數字,以及黏在單字裡的 4K(如 Show4Kids)都不算解析度:[Group] One Piece - 1080 [720p].mkv 辨識為 720p。標題裡辨識不出時,依同樣的規則讀取種子內部名稱,仍辨識不出時為 1080p。

釋出端點的 POST 與 GET(whoami)在校驗 Key 之前就依來源計數,Key 無效的請求同樣計數;超出額度時直接回傳 429,不會校驗 Key。whoami 單獨計數,不占用釋出的額度。額度見限流與參數上限。

收到 429 RATE_LIMIT_EXCEEDED 時,依 Retry-After 的秒數等待。釋出暫時忙碌、限流服務暫時無法計數或上傳結果待確認時,可回傳 503 SERVICE_UNAVAILABLE;限流服務無法計數時 Retry-After 固定為 15。503 帶 Retry-After 時依它等待,再用原 key 重試同一請求;沒有此標頭時先核查現有釋出並保留 error.requestId。失敗或連線中斷不代表未寫入,不要立即批次重試,也不要為一次不確定的結果反覆更換新 key。

刪除被拒絕時的回應

DELETE /api/releases/{releaseId} 在資源不存在、屬於其他字幕組,或普通成員的 Key 刪除同組其他成員釋出的資源時,回傳 404 NOT_FOUND,error.message 為 Release not found;這幾種情況的回應完全相同。普通成員的 Key 只能刪除自己釋出的資源,owner/admin 的 Key 可以刪除本組所有資源。

字幕組狀態不是「活躍」(為「不活躍」或「已停用」),或 Key 在請求處理期間被撤銷時,刪除會回傳 403 FORBIDDEN,資源不會被刪除。成員離開或被移出字幕組後,他在該組的 Key 已撤銷,刪除請求回傳 401。

本頁目錄