Video Data API 教程：从解析到下载（Windows / Python）

这篇文章用教程风格带你完整跑通 Video Data API：
从解析视频格式、创建下载任务，到拿到最终下载链接并保存文件。

平台地址：

• https://video-api.privateproxy.me/dashboard

---

一、注册与流量说明

根据实测：

• 注册只需邮箱（临时邮箱也可）
• 默认可用流量：1024MB
• 完成社区任务可申请额外 1TB（需管理员手动验证）

---

二、调用流程总览（4 步）

整个流程固定为 4 步：

1. GET /api/formats：获取可用格式
2. POST /api/download：创建下载任务，拿 task_id
3. GET /api/status/{task_id}：轮询任务进度
4. GET /api/download/{task_id}：获取最终 download_url

---

三、准备工作：Authorization

接口使用 Basic 鉴权：

Authorization: Basic xxxxxxxxx

xxxxxxxxx 是你的 Base64 凭据（username:password 编码结果）。

---

四、步骤 1：查询可用格式

PowerShell 命令

curl.exe --location "https://gate.apiscrape.net:16262/api/formats?video_url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DmACO9BhP3ok" --header "Authorization: Basic 你的Base64"

返回里会有大量 format_id，常见例如：

• 140：m4a 音频（中码率）
• 250：webm 音频（低码率）
• 18：mp4 360p（含音频+视频）
• 137：1080p 视频流（通常仅视频）

---

五、步骤 2：创建下载任务

选择一个 format_id（例如 140）并提交任务：

curl.exe --location "https://gate.apiscrape.net:16262/api/download" --header "Content-Type: application/json" --header "Authorization: Basic 你的Base64" --data "{\"url\":\"https://www.youtube.com/watch?v=mACO9BhP3ok\",\"format_id\":\"140\"}"

示例响应：

{
  "status": "queued",
  "task_id": "1deb8710-9883-4641-a0ab-ee64d246cff2"
}

---

六、步骤 3：查询任务状态

curl.exe --location "https://gate.apiscrape.net:16262/api/status/1deb8710-9883-4641-a0ab-ee64d246cff2"

示例响应：

{
  "download_url": "/api/download/1deb8710-9883-4641-a0ab-ee64d246cff2",
  "progress": 100,
  "site": "youtube",
  "status": "completed"
}

当 status = completed 后，进入下一步。

---

七、步骤 4：获取最终下载链接

curl.exe --location "https://gate.apiscrape.net:16262/api/download/1deb8710-9883-4641-a0ab-ee64d246cff2" --header "Authorization: Basic 你的Base64"

示例响应：

{
  "download_url": "http://s3.xxx...带签名的临时链接..."
}

然后保存到本地：

curl.exe -L "上一步返回的download_url" -o output.m4a

---

八、为什么后台会显示多次下载与多段流量？

如果你创建了多个任务（例如一次 format_id=250，一次 format_id=140），后台会分别计入：

• 每个任务一次下载记录
• 每个任务对应的文件流量

所以就算最后只保留了一个文件，也可能看到多条记录和累计流量。

---

九、是否可以直接用 formats 里的 YouTube 直链下载？

formats 返回的数据里通常包含 YouTube/Googlevideo 直链。
这些链接常常是临时签名链接，可能过期、受 IP/地区限制，不适合作为稳定流程。

推荐做法：

• 始终走任务接口，最终使用 /api/download/{task_id} 返回的 download_url。

---

十、Windows 常见报错与处理

1）'--header' 不是内部或外部命令

原因：把参数单独敲成了一条命令。
解决：整条 curl 写成一行。

---

2）curl: (3) URL rejected: Bad hostname

原因：PowerShell 换行续写不规范（反引号后有空格）或命令拆坏了。
解决：尽量使用单行命令。

---

3）405 Method Not Allowed

原因：调用 /api/download 时没带 --data，请求变成 GET。
解决：确保 POST + JSON body。

---

4）schannel: failed to receive handshake

原因：Windows curl 偶发 TLS 握手问题。
解决：通常重试即可恢复。

---

十一、Python 一键脚本（推荐）

import time
import requests

BASE = "https://gate.apiscrape.net:16262"
AUTH = "Basic 你的Base64"

video_url = "https://www.youtube.com/watch?v=mACO9BhP3ok"
format_id = "140"  # 可改为 250 / 18 等

headers = {
    "Authorization": AUTH,
    "Content-Type": "application/json",
}

# 1) 创建任务
resp = requests.post(
    f"{BASE}/api/download",
    headers=headers,
    json={"url": video_url, "format_id": format_id},
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["task_id"]
print("task_id:", task_id)

# 2) 轮询状态
while True:
    s = requests.get(f"{BASE}/api/status/{task_id}", timeout=30)
    s.raise_for_status()
    data = s.json()
    print("status:", data.get("status"), "progress:", data.get("progress"))
    if data.get("status") == "completed":
        break
    if data.get("status") in ("failed", "error"):
        raise RuntimeError(data)
    time.sleep(2)

# 3) 获取最终下载链接
d = requests.get(
    f"{BASE}/api/download/{task_id}",
    headers={"Authorization": AUTH},
    timeout=30,
)
d.raise_for_status()
download_url = d.json()["download_url"]
print("download_url:", download_url)

# 4) 下载文件
r = requests.get(download_url, timeout=120)
r.raise_for_status()
with open("output.m4a", "wb") as f:
    f.write(r.content)

print("saved: output.m4a")

---

十二、实践建议

• 先查 formats，确认目标格式后再创建任务，减少流量浪费
• 对同视频同格式做本地缓存，避免重复创建任务
• 不要在公开博客里暴露完整鉴权信息（建议打码）
• 如果凭据曾公开，建议后台重置

---

结语

这套 API 的使用方式很标准：解析 -> 建任务 -> 轮询 -> 下载。
只要把流程封装成脚本，就能稳定批量处理视频/音频下载任务。