YouTube 批次下載任務資訊 API

/download/info/batch API 端點允許您查詢批次下載任務的狀態與詳細資訊。

API 詳細資訊

端點 POST https://dlapi.abcproxy.com/download/info/batch

說明

此 API 用於擷取 YouTube 視頻批次下載任務的詳細資訊，包括每一筆下載的狀態，以及已完成項目的視頻中繼資料。

---

請求

HTTP 請求

---

cURL

curl -X POST "https://dlapi.abcproxy.com/download/info/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_id": "aa3aba32-796f-4449-929e-3809d366f72c"
  }'

Python

Node.js

HTTP

參數

請求主體（Request Body）

名稱	類型	必填項	說明	範例
batch_id	字符串	是	欲查詢之批次下載任務的 ID	"aa3aba32-796f-4449-929e-3809d366f72c"

---

回應

成功 200

回應主體 - 完成範例

{
  "code": 200,
  "msg": "Success",
  "data": {
    "batch_id": "edcdce7d-9e17-4094-a25f-3c6a14f22a30",
    "status": "completed",
    "total_job_count": 2,
    "completed_job_count": 2,
    "failed_job_count": 0,
    "job_list": [
      {
        "job_id": "1785515f-fb26-4a22-b656-e40da7856f49",
        "video_id": "knGEaQk0slc",
        "status": "completed",
        "error": "",
        "video_info": {
          "url": "https://www.youtube.com/watch?v=knGEaQk0slc",
          "video_id": "knGEaQk0slc",
          "download_url": "http://s3-service.abcproxy.net/files/youtube/videos/knGEaQk0slc_17ce85bfe28ff7040ed5e168ee164e48.mp4",
          "title": "ai video",
          "duration": 721,
          "resolution": "640x360"
        }
      },
      {
        "job_id": "ae21c52c-2f95-47b0-9a8c-a44739ee8754",
        "video_id": "26ZDFX-t8jE",
        "status": "completed",
        "error": "",
        "video_info": {
          "url": "https://www.youtube.com/watch?v=26ZDFX-t8jE",
          "video_id": "26ZDFX-t8jE",
          "download_url": "http://s3-service.abcproxy.net/files/youtube/videos/26ZDFX-t8jE_a002bfbf16e9989fae3eec9321561972.mp4",
          "title": "GPT-4o",
          "duration": 595,
          "resolution": "640x360"
        }
      }
    ]
  }
}

回應主體 - 等待中範例

{
  "code": 200,
  "msg": "Success",
  "data": {
    "batch_id": "25ba9534-bb83-4496-ac5b-6bc94f83e963",
    "status": "pending",
    "total_job_count": 2,
    "completed_job_count": 0,
    "failed_job_count": 0,
    "job_list": [
      {
        "job_id": "3283017f-c4bf-45e9-9f33-0021c1bd1cf3",
        "status": "pending",
        "error": "",
        "video_info": null
      },
      {
        "job_id": "dc773dd5-57d7-435b-8a5d-aff9d536adb3",
        "status": "pending",
        "error": "",
        "video_info": null
      }
    ]
  }
}

回應主體 - 部分完成範例

{
  "code": 200,
  "msg": "Success",
  "data": {
    "batch_id": "7c2130b9-a43e-44d9-8548-39b99394f6e2",
    "status": "partial",
    "total_job_count": 2,
    "completed_job_count": 1,
    "failed_job_count": 1,
    "job_list": [
      {
        "job_id": "8c7c1d1c-d82c-443f-b209-a098c8d2ec24",
        "video_id": "fSs51c45515ddfm5Lk",
        "status": "failed",
        "error": "Download failed",
        "video_info": {}
      },
      {
        "job_id": "cc1be69b-b9f6-4cc6-bbbf-ce4950aa88ff",
        "video_id": "ONZZvc_IqQg",
        "status": "completed",
        "error": "",
        "video_info": {
          "url": "https://www.youtube.com/watch?v=ONZZvc_IqQg",
          "video_id": "ONZZvc_IqQg",
          "download_url": "https://abcproxy.oss-us-west-1.aliyuncs.com/youtube/videos/ONZZvc_IqQg_eaae2b6c7321ab7e86ea2b426e5f8bc1.mp4",
          "title": "Rust and Linux",
          "duration": 729,
          "resolution": "640x360"
        }
      }
    ]
  }
}

回應主體 - 失敗範例

{
  "code": 200,
  "msg": "Success",
  "data": {
    "batch_id": "7c2130b9-a43e-44d9-8548-39b99394f6e2",
    "status": "failed",
    "total_job_count": 2,
    "completed_job_count": 0,
    "failed_job_count": 2,
    "job_list": [
      {
        "job_id": "8c7c1d1c-d82c-443f-b209-a098c8d2ec24",
        "video_id": "fSs51c45515ddfm5Lk",
        "status": "failed",
        "error": "Download failed",
        "video_info": {}
      },
      {
        "job_id": "cc1be69b-b9f6-4cc6-bbbf-ce4950aa88ff",
        "video_id": "ONZZvc_IqQg",
        "status": "failed",
        "error": "Download failed",
        "video_info": {}
      }
    ]
  }
}

回應欄位

欄位名稱	類型	說明
code	整數型	回應代碼（成功為 200）
msg	字符串	回應訊息
data.batch_id	字符串	批次任務的 ID
data.status	字符串	批次總體狀態（pending、completed、partial、failed）
data.total_job_count	整數型	批次中影片總數
data.completed_job_count	整數型	成功下載的影片數量
data.failed_job_count	整數型	下載失敗的影片數量
data.job_list	數組	各影片的下載任務列表
job_list[].job_id	字符串	個別影片任務 ID
job_list[].status	字符串	任務狀態（pending、completed、failed）
job_list[].error	字符串	若任務失敗，顯示錯誤訊息
job_list[].video_info	對象/空值	已完成任務的影片中繼資料
video_info.url	字符串	原始 YouTube 網址
video_info.video_id	字符串	YouTube 影片 ID
video_info.download_url	字符串	已下載檔案的本地路徑或 URL
video_info.title	字符串	影片標題
video_info.duration	整數型	影片長度（秒數）
video_info.resolution	字符串	影片解析度（格式為寬度x高度）

狀態值說明

• pending：所有任務尚在處理中

• completed：所有任務已成功完成

• partial：部分任務成功、部分失敗

• failed：所有任務失敗

---

錯誤回應

常見錯誤

HTTP 狀態碼	錯誤代碼	描述
400	Invalid batch ID	提供的批次 ID 無效或缺失
404	Batch not found	查無指定的批次任務
500	Internal server error	處理請求時發生內部錯誤

錯誤回應範例

{
  "code": 404,
  "msg": "Batch not found",
  "data": null
}

---

備註

1. 回應中的 download_url 可能為以下其中之一：

   • 本地檔案路徑（若儲存於伺服器）

   • 雲端儲存 URL（若在建立批次任務時已設定）

2. 若任務處於 pending 狀態，則 video_info 欄位將為空值（null）。

3. 若任務失敗，error 欄位將包含詳細的失敗原因，可能包含來自 YouTube 的錯誤訊息。