YouTube 数据 API

# YouTube Data API

Query YouTube videos, channels, Shorts, comments, community posts, search results and stream metadata through 34 authenticated endpoints: 32 GET and 2 POST.

## Authentication

Use your API Hop API key in the authorization header. Availability depends on enabled gateways and API key permissions; documentation alone does not confirm production availability.

```http
Authorization: Bearer YOUR_API_KEY
```

## Requests and caption tasks

GET operations use query parameters without a request body. Stream V3 uses POST with an application/json body and no query parameters; send proxy_url only in that body. The version segment selects the YouTube interface version. Unknown or duplicate fields are rejected. Keep identifiers and pagination cursors as strings, including values larger than JavaScript can safely represent as numbers.

```bash
curl --get "https://api.apihop.ai/v1/youtube/web/channels/id" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "channel_name=LinusTechTips"
```

## Responses

Synchronous endpoints preserve the native JSON response. Caption endpoints return success, data.id, data.status, data.result and requestId. The examples below are illustrative, not live results.

```json
{"code":200,"data":{"channel_id":"UCXuqSBlHAE6Xw-yeJA0Tunw"}}
```

## Billing and pagination

For synchronous requests: Prices are per successful request, not per returned item. Every page is a separate request. Most operations cost $0.001. The two V2 search variants cost $0.002; the V2 stream variant costs $0.004. See each endpoint below. Account-specific prices take precedence. Supplier volume discounts are not automatically passed through. Failed upstream calls release the reservation; settlement failures return an error and do not trigger a second upstream request.

## Caption tasks

POST https://api.apihop.ai/v1/youtube/web-v2/videos/captions returns HTTP 202 and a platform task ID, with Location: /v1/jobs/\{id\}. Query GET https://api.apihop.ai/v1/youtube/web-v2/videos/captions/result?job_id=\{id\} every 2–5 seconds. Only the owning tenant can read the task. Result queries are free; creation costs $0.008 at the list price. No-caption results are successful and billable. The format is fixed at creation (default srt); an optional result format must match or returns HTTP 400. data.result is null until COMPLETED; tasks may end as FAILED. These endpoints retrieve existing captions, not AI transcriptions.

If submission acceptance is uncertain, the request is not replayed and its reservation may remain held until the 30-minute task deadline. A supplier result may remain pending while settlement is reconciled. A transient polling error is not a terminal task failure.

```json
{"success":true,"data":{"id":"9007199254740993001","status":"PROCESSING","result":null},"requestId":"example"}
```

## Scope and limitations

The web and web-v2 paths select the upstream interface family. Stream V3 supports POST retrieval with your own fixed-exit HTTP proxy. Stream endpoints return metadata and URLs, not media files or guaranteed downloads. Channel descriptions may require a second separately billed request using continuation_token. No automatic retries are made.

Stream V3 uses POST JSON over HTTPS and costs $0.003 per successful request. Provide video_id and proxy_url (http:// with an explicit port and public host); private, loopback and link-local destinations are forbidden. URL-encode reserved characters in credentials. Use a fixed exit or sticky proxy session. itags defaults to ["137", "140"]; unavailable formats fail without substitution. verify_download defaults to false. Download through the same proxy session and actual public exit IP with streams[].download_headers. Successful URL extraction (HTTP 200) is billable even when all_selected_streams_verified or streams[].verified is false. Verification samples small byte ranges, not the complete file. URLs and proxy sessions expire independently; merge separate audio/video streams yourself.

## Reference

Select an endpoint and send only its documented fields. When alternatives are listed, provide at least one field from each group. Pagination values must come from the preceding response; there is no automatic pagination.

[Complete reference](https://apihop.ai/en/docs/api-reference/youtube/reference)

## Errors

Platform errors use HTTP 400 for invalid parameters, 401 for invalid authentication, 402 for insufficient credit, 403 for denied gateway access, 429 for rate limits, and 5xx for service or supplier failures. Keep X-Request-Id for troubleshooting. Do not treat an upstream HTTP 200 with a failed business code as success.

## Sources

The endpoint list and prices were checked against the official schema and live price metadata on 2026-10-31. Live metadata takes precedence over conflicting prose prices.

[TikHub](https://docs.tikhub.io/4592766m0) · [OpenAPI](https://api.tikhub.io/openapi.json) · [Prices](https://api.tikhub.io/api/v1/tikhub/user/get_all_endpoints_info)

通过 34 个需要鉴权的接口查询 YouTube 视频、频道、Shorts、评论、社区帖子、搜索结果与媒体流元数据，其中 32 个为 GET，2 个为 POST。

鉴权

请在鉴权请求头中发送 API Hop API Key。可用性取决于已启用的网关和 API Key 权限；文档不代表生产环境已开放。

http

Authorization: Bearer YOUR_API_KEY

请求与字幕任务

GET 接口使用查询参数，不接受请求体。V3 媒体流接口使用 POST application/json 请求体，不接受查询参数；proxy_url 只能放在请求体中。版本路径选择 YouTube 接口版本。未知字段或重复字段会被拒绝。用户标识和分页游标须保留为字符串，包括超出 JavaScript 安全整数范围的值。

bash

curl --get "https://api.apihop.ai/v1/youtube/web/channels/id" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "channel_name=LinusTechTips"

响应

同步接口保留上游原始 JSON 响应。字幕接口返回 success、data.id、data.status、data.result 和 requestId。下方示例仅作说明，不是实时结果。

json

{"code":200,"data":{"channel_id":"UCXuqSBlHAE6Xw-yeJA0Tunw"}}

计费与分页

同步请求的计费规则：按成功请求次数计费，不按返回条数计费；每一页单独计费。多数接口为 $0.001；两个 V2 搜索变体为 $0.002，V2 媒体流变体为 $0.004。具体价格见各接口。账户专属价格优先。供应商按用量提供的折扣不会自动转为客户折扣。上游调用失败会释放预扣，结算失败返回错误且不会再次调用上游。

字幕任务

POST https://api.apihop.ai/v1/youtube/web-v2/videos/captions 返回 HTTP 202、平台任务 ID 和 Location: /v1/jobs/\{id\}。每隔 2–5 秒调用 GET https://api.apihop.ai/v1/youtube/web-v2/videos/captions/result?job_id=\{id\} 查询，仅任务所属租户可读取。结果查询免费；创建请求的目录价为 $0.008。无字幕也是成功结果，正常计费。格式在创建时固定，默认 srt；查询时可选的 format 必须一致，否则返回 HTTP 400。任务达到 COMPLETED 前 data.result 为 null，也可能以 FAILED 结束。接口仅获取已有字幕，不提供 AI 转写。

提交是否被上游接受无法确认时，不会重放请求，预扣可能保留至 30 分钟任务期限。上游已返回终态时，平台仍可能等待结算对账后再完成任务。临时轮询错误不代表任务最终失败。

json

{"success":true,"data":{"id":"9007199254740993001","status":"PROCESSING","result":null},"requestId":"example"}

范围与限制

web 和 web-v2 路径选择上游接口系列。V3 支持通过 POST 使用自带固定出口 HTTP 代理获取媒体流链接。媒体流接口返回元数据和 URL，不返回媒体文件，也不保证下载成功。频道描述可能需要使用 continuation_token 再发起一次单独计费的请求。不会自动重试。

V3 媒体流通过 HTTPS 使用 POST JSON，每次成功请求为 $0.003。提供 video_id 和 proxy_url（http://、显式端口及公网地址）；禁止内网、回环及链路本地地址，凭据中的保留字符须 URL 编码。使用固定出口或粘性代理会话。itags 默认 ["137", "140"]；所选格式不存在时失败，不自动替换。verify_download 默认为 false。下载须使用同一代理会话和实际公网出口 IP，并携带 streams[].download_headers。成功获取链接的 HTTP 200 会计费，即使 all_selected_streams_verified 或 streams[].verified 为 false。验证仅抽样读取少量字节，不代表完整文件已验证。链接和代理会话独立过期，分离音视频须自行合并。

鉴权

请求与字幕任务

响应

字幕任务

范围与限制

接口参考

错误

来源