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。驗證僅抽樣讀取少量位元組，不代表完整檔案已驗證。連結與代理工作階段獨立到期，分離音訊與視訊須自行合併。

身分驗證

請求與字幕任務

回應

字幕任務

範圍與限制

介面參考

錯誤

來源