---
title: "推荐：使用自带固定出口代理获取下载链接 / Recommended: download URLs with your fixed-exit proxy"
method: POST
path: "/api/v1/youtube/web_v2/get_video_streams_v3"
tags: ["YouTube-Web-V2-API"]
---

# 推荐：使用自带固定出口代理获取下载链接 / Recommended: download URLs with your fixed-exit proxy

`POST /api/v1/youtube/web_v2/get_video_streams_v3`

## Request

- Base URL: `https://api.tikhub.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.tikhub.io/api/v1/youtube/web_v2/get_video_streams_v3`
- Auth: HTTP bearer

# [中文]
### 用途
获取指定 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 表示参数或链接获取失败，不计费。代理凭据不会在响应参数中回显，
  本接口不提供公开的响应缓存链接。

### 请求示例
```json
{
  "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.

## Request body

- VideoStreamsV3Request
  - `video_id` string, required: 11 位 YouTube 视频 ID / 11-character YouTube video ID
  - `proxy_url` string, password, required: 固定公网出口的 HTTP 代理，必须包含端口 / HTTP proxy with a fixed public exit and explicit port
  - `itags` string[]: 所需格式编号，1–4 个不重复的数字字符串 / 1–4 unique numeric format IDs
  - `verify_download` boolean: 是否尝试读取各流前 1 KiB；不代表完整下载验证 / Probe up to 1 KiB per stream, not the full file

## Response `200`

Successful Response

- ResponseModel
  - `code` integer: HTTP status code | HTTP状态码
  - `request_id` string, nullable: Unique request identifier | 唯一请求标识符
  - `message` string: Response message (EN-US) | 响应消息 (English)
  - `message_zh` string: Response message (ZH-CN) | 响应消息 (中文)
  - `support` string: Support message | 支持消息
  - `time` string: The time the response was generated | 生成响应的时间
  - `time_stamp` integer: The timestamp the response was generated | 生成响应的时间戳
  - `time_zone` string: The timezone of the response time | 响应时间的时区
  - `docs` string, nullable: Link to the API Swagger documentation for this endpoint | 此端点的 API Swagger 文档链接
  - `cache_message` string, nullable: Cache message (EN-US) | 缓存消息 (English)
  - `cache_message_zh` string, nullable: Cache message (ZH-CN) | 缓存消息 (中文)
  - `cache_url` string, nullable: The URL to access the cached result | 访问缓存结果的 URL
  - `router` string: The endpoint that generated this response | 生成此响应的端点
  - `params` unknown
  - `data` unknown

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-08** `96a122a5f220`: 2 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status
- **2026-09-21** `861c84855bd9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi/changes/api/v1/youtube/web_v2/get_video_streams_v3/post.md)

---

[API](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi.md) - [All operations](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi/llms.txt) - [OpenAPI document](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi/revisions/86a3483c705a?raw)