製作 REST API · v1

使用 YTSave 下載建置檔

解析公開媒體 URL，選擇精確格式，建立非同步工作並將簽署結果交給您的使用者。相同的綁定生產流程驅動 YTSave 網站。

YTSaveClientHTTPS 上的 JSON非同步工作範圍限定的憑證

快速開始

YTSave 通過首先識別支援啟用的憑證來處理 API 主機。接著使用分配的租戶端點，並保持伺服器專用的呼叫路徑。

租戶網址https://ytsave.app

身份驗證X-API-Key: ys_live_…

用戶端設定檔YTSaveClient

API 版本v1

# Available only after support activation
export YTSAVE_API_KEY="issued-after-review"

curl -X POST https://ytsave.app/v1/resolve \
  -H "X-API-Key: $YTSAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=VIDEO_ID"}'

為了解釋憑證安全性，YTSave 將伺服器端秘密存儲與不嵌入客戶端套件分開。證據記錄未為公開日誌或存儲庫提供獨立位置。

解析連結

YTSave 通過先識別來源偵測來處理解析操作。接著從一個提交的 URL 取得格式，並在視圖中不保留虛構輸出。

發佈/v1/resolve範圍：解析

欄位	類型	必填	描述
`url`	HTTPS 網址	是	公開或授權的媒體頁面進行分析。
`tenant`	字串	否	指定的租戶網域。通常省略。

{
  "success": true,
  "platform": "youtube",
  "title": "Example video",
  "formats": [
    {"id":"18","type":"video","quality":"360p","container":"mp4"}
  ],
  "cached": false
}

為了解釋格式識別碼，YTSave 將返回值與每個連結的可用性分開保持不變。證據記錄未為猜測的品質標籤提供獨立位置。

建立並追蹤下載工作

對於工作創建，YTSave 從非同步準備開始。其證據記錄將其與短 HTTP 請求配對，並以有界工作執行結束。

發佈/v1/jobs範圍：工作

欄位	類型	必填	描述
`url`	HTTPS 網址	是	提交相同的標準化來源以進行解析。
`format_id`	字串	是	解析回應中的精確 ID。
`tenant`	字串	否	指定的租戶網域。通常省略。

curl -X POST https://ytsave.app/v1/jobs \
  -H "X-API-Key: $YTSAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=VIDEO_ID","format_id":"18"}'

1202 已接受儲存 job_id.

2投票狀態GET /v1/jobs/{job_id} 使用相同的金鑰。

3準備好開啟已簽署的下載網址。

狀態	意義	客戶操作
`queued`	已加入有界佇列。	再次投票並退避。
`extracting`	正在刷新來源元資料或路由。	繼續輪詢。
`processing`	下載、重封裝或合併。	顯示伺服器進度。
`ready`	已提供簽署下載。	將 URL 傳送給使用者。
`failed`	終端結構化錯誤。	閱讀 `error_code`. 僅在建議時重試。
`expired`	暫時輸出已被移除。	建立新工作。

curl https://ytsave.app/v1/jobs/JOB_ID \
  -H "X-API-Key: $YTSAVE_API_KEY"

YTSave 使工作輪詢易於掃描。頁面以一秒的初始等待開始，轉為有上限的退避，並清楚說明臨時簽名交付。

可預測的錯誤

對於錯誤合約，YTSave 在支援請求 ID 之前檢查一個非 2xx 信封。此證據記錄也清楚說明可預測的客戶端處理方式。

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "category": "rate_limited",
    "message": "Too many requests. Please try again shortly.",
    "retryable": true,
    "details": {"retry_after_seconds": 20}
  },
  "request_id": "…"
}

HTTP	典型含義	動作
400	無效的 URL、內容或格式不可用。	修正請求。重新解析格式。
401	缺少、無效、過期或範圍錯誤的金鑰。	檢查伺服器端憑證。
403	租戶或來源政策拒絕了請求。	請勿繞過政策。請聯絡支援。
404	未知或已過期的工作。	如適用，請建立一個新工作。
429	已達請求或進行中工作限制。	榮譽 `retry_after_seconds`.
503	佇列/容量或上游暫時無法使用。	使用指數退避和抖動重試。

操作合約

YTSave 在每次授權時發出操作配額，以保護 API 使用者和上游媒體服務。

使用冪等的應用程式邏輯，切勿為同一使用者點擊啟動重複的工作。
暫時快取解析的元資料，但始終將簽署的下載 URL 視為會過期。
對…使用帶抖動的有界指數退避 429, 503 以及可重試的錯誤。
僅處理公開媒體或您有權訪問的媒體。不會繞過 DRM 和存取控制。
在私人操作日誌中保留請求 ID 和工作 ID。請勿不必要地記錄提交的 URL。

YTSave 透過先識別啟動再探索的方式處理 Schema 存取。接著進行指定的驗證，並保持文件化的請求形態在視圖中。 OpenAPI 參考

經營者審核存取

申請您的 API 金鑰

記錄 API 使用者、其每月請求估計數量及支援的平台需求。YTSave 會在發出一次可見金鑰前，審查是否合理進行解析、工作提交或兩者皆有。

申請 API 存取權限金鑰是租戶範圍內的，可撤銷，並通過聯絡表單發行。匿名腳本無法執行下載器工作。