[中文]

用途

获取指定 YouTube 视频的音频或视频下载链接、格式信息和链接有效期。 本接口返回链接，不返回媒体文件，也不合并音视频。

请求方式

• 使用 POST + JSON，通过 Authorization: Bearer <API_TOKEN> 认证。
• 使用 HTTPS 调用；不要把代理密码放进 URL 查询参数。

代理要求（推荐下载入口）

• 必须在请求体提供 proxy_url；调用 TikHub API 本身无需让客户端经过该代理。 实际下载媒体文件时，下载程序必须继续使用本次提供的同一代理会话和公网出口 IP。
• 首选美国住宅代理的固定出口或粘性会话；固定公网出口的静态住宅/ISP 代理也适合。 数据中心代理不作为首选，仅在自行验证视频可访问且出口稳定时使用。
• 美国是常规起点，不是强制地区。如果视频仅在特定国家/地区可用， 选择该视频允许访问的地区，并确保获取链接与下载全过程保持同一实际公网出口。

参数

• video_id：必填，11 位视频 ID，例如 phlZ2J3x4hI。
• proxy_url：必填，http://用户名:密码@公网代理地址:端口。 支持 HTTP 代理，下载目标使用 HTTPS；不支持 SOCKS 或 HTTPS 代理协议。 用户名、密码中的 @、:、/ 等保留字符需要 URL 编码。 必须提供固定公网出口，或已配置粘性会话的完整代理地址。 仅指定国家不能保证出口 IP 固定。 代理不可指向内网、回环或链路本地地址。
• itags：可选，1–4 个不重复的数字字符串，默认 ["137", "140"]。 常见格式：137 为 1080p MP4 纯视频，140 为 M4A 音频； 并非每个视频都有这些格式，任一所选格式不可用时请求失败，不自动替换格式。
• verify_download：可选，默认 false。设为 true 时抽检各流起点、中间和末尾，每处最多 1 KiB， 会增加耗时及少量代理流量，不保证整个文件可下载。

下载要求

• 下载程序必须使用与本次请求相同的代理会话和实际公网出口 IP， 并携带 streams[].download_headers。仅国家或 session 字符串相同不够。
• 不要在未配置该代理的浏览器中直接打开链接，换出口可能返回 403。
• 下载开始前可核对当前代理公网 IP 是否等于 proxy_exit_ip。
• 链接在 expires_at 指定的 Unix 秒时间戳到期；expires_in_seconds 是响应时剩余秒数。 代理会话可能更早失效，不能将链接有效期视为会话有效期。
• 视频流和音频流通常分离；需要完整音画文件时由下载端分别下载后合并。 使用者承担自带代理的费用和下载流量费用。

返回值与计费

• streams：按所选格式返回 itag、url、媒体信息、请求头和有效期。
• proxy_exit_ip：本次请求的代理公网出口；same_proxy_required 为 true。
• proxy_exit_verified：本次请求的出口检查是否通过，不代表未来不会变更。
• download_verification_requested：本次是否请求小字节验证。
• streams[].verification：开启验证时包含 status、bytes_read、ok 和 duration_ms。 bytes_read 是实际采样读取字节数的总和；samples 提供逐范围的 byte_range、status、bytes_read、content_range 和 ok，失败时可包含 reason。 scope=sampled_ranges、full_file_verified=false 表示仅完成抽样，未验证整个文件。 streams[].verified / all_selected_streams_verified 为布尔值；未验证时为 null。
• HTTP 200 表示链接获取成功并按接口单价计费，包括小字节验证结果为 false 的响应。 请检查验证字段，HTTP 200 不等于完整文件下载成功。
• HTTP 400 表示参数或链接获取失败，不计费。代理凭据不会在响应参数中回显， 本接口不提供公开的响应缓存链接。

请求示例

{
  "video_id": "phlZ2J3x4hI",
  "proxy_url": "http://USERNAME:PASSWORD@proxy.example.com:1000",
  "itags": ["137", "140"],
  "verify_download": false
}

[English]

Purpose and request

Get selected video/audio download URLs, format metadata and expiration times. This endpoint does not return media files or merge audio and video. Send a POST JSON body over HTTPS with Authorization: Bearer <API_TOKEN>. Never put proxy credentials in URL query parameters.

Proxy requirements (recommended download endpoint)

• Provide proxy_url in the JSON body. The client does not need to route its TikHub API call through that proxy. The media downloader must use the same proxy session and actual public exit IP used for this request.
• Prefer a US residential proxy with a fixed exit or sticky session. A static residential/ISP proxy with a fixed public exit is also suitable. Datacenter proxies are not the first choice; use one only after confirming that the video is accessible and the exit remains stable.
• The US is a starting point, not a required country. For a region-limited video, choose a country/region where it is available and keep the same actual public exit throughout URL retrieval and download.

Parameters

• video_id: required, an 11-character YouTube video ID.
• proxy_url: required, http://USERNAME:PASSWORD@PUBLIC_HOST:PORT. Only HTTP proxies are supported; media destinations use HTTPS. URL-encode reserved characters in credentials. Private, loopback and link-local destinations are not allowed. Supply a fixed public exit or a fully configured sticky session. Selecting a country alone does not keep the exit IP fixed.
• itags: 1–4 unique numeric strings, default ["137", "140"]. Common formats: 137 is 1080p MP4 video-only; 140 is M4A audio-only. Availability varies by video. The request fails if any selected format is missing; formats are not silently substituted.
• verify_download: default false. If enabled, sample up to 1 KiB at the beginning, middle and end of each stream. This adds latency and small proxy traffic, and does not verify an entire file.

Download requirements

Use the same proxy session and actual public exit IP, together with each stream's download_headers. The same country or session name alone is insufficient. A browser or downloader using a different exit may receive HTTP 403. Before downloading, compare the proxy's current public IP with proxy_exit_ip. expires_at is a Unix timestamp in seconds; expires_in_seconds is the remaining URL lifetime at response time. The proxy session may expire sooner. Download separate audio/video streams and merge them locally when necessary. You pay your own proxy provider's connection and download traffic charges.

Response and billing

streams contains selected formats, URLs, headers and expiry values. same_proxy_required is true. proxy_exit_verified describes checks for this request, not a guarantee that the exit will remain unchanged. download_verification_requested indicates whether small-byte verification was requested. Each verification includes status, bytes_read, ok and duration_ms when enabled. bytes_read is the total bytes read across samples. Each samples entry includes byte_range, status, bytes_read, content_range and ok, with an optional failure reason. scope=sampled_ranges and full_file_verified=false mean the full file was not verified. verified and all_selected_streams_verified are null when verification is disabled. HTTP 200 means URL extraction succeeded and is charged, even if optional verification reports false. It does not guarantee a successful full-file download. HTTP 400 is not charged. Proxy credentials are not echoed, and no public response-cache link is provided. The JSON example above applies to both language sections.

{
  "itags": [
    "137",
    "140"
  ],
  "proxy_url": "http://USERNAME:PASSWORD@proxy.example.com:1000",
  "verify_download": false,
  "video_id": "phlZ2J3x4hI"
}