> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# YouTube API

> YouTube を検索し、動画、コメント、チャンネル、チャンネルのアップロード、字幕を JSON で読み取ります。再生回数、高評価数、公開日時、チャプター、字幕テキストも受け取れます。

公開されている YouTube のデータを非同期タスク API で JSON として読み取ります。`taskType` `SOCIAL` に `platform` `youtube` を指定し、`action` で読み取る対象を選びます。完了したリクエスト 1 件につき **0.5 クレジット**です。

## リクエスト

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "SOCIAL", "payload": { "platform": "youtube", "action": "search", "query": "wireless earbuds review", "limit": 10 } }'
```

タスクを送信したあと、`GET /v1/async/task/{id}` をポーリングするか Webhook で受け取ります。[非同期タスク](https://docs.querying.ai/ja/concepts/async-tasks.md)を参照してください。

## アクション

| `action` | 読み取る内容 | 必須 |
| - | - | - |
| `search` (デフォルト) | YouTube の検索結果 | `query` |
| `recent` | 検索語句の最新アップロード (新しい順) | `query` |
| `video` | 1 本の動画の視聴ページ | `videoId` |
| `comments` | 動画のコメントと返信 | `videoId` |
| `channel` | チャンネルの詳細とリンク | `channel` |
| `channel_videos` | チャンネルの動画、ショート、ライブ配信 | `channel` |
| `transcript` | 動画の字幕 | `videoId` |

`videoId` には動画 ID か YouTube 動画の URL (視聴ページ、`youtu.be`、ショート、埋め込み) を指定します。`channel` にはチャンネル ID (`UC...`)、`@handle`、チャンネル URL を指定します。

## パラメータ

`search` と `recent`:

* `query`: 必須。検索語句です。
* `limit`: 任意の整数、1-50。デフォルトは 10 です。
* `type`: `video` (デフォルト)、`all`、`shorts`、`channel`、`playlist`、`movie` のいずれかです。
* `order`: `relevance` (デフォルト)、`viewCount`、`date`、`rating` のいずれかです。`date` は `recent` と同じく新しいアップロードから並べます。`rating` は YouTube の再生回数上位の結果を高評価数で並べ替えます。`channel` と `playlist` の検索は `relevance` か `viewCount` を受け付けます。
* `publishedAfter`: `2026-11-01T00:00:00Z` のような ISO 8601 の日時です。この日時より後に公開された動画を返します。
* `videoDuration`: `short` (3 分未満)、`medium` (3-20 分)、`long` (20 分超) のいずれかです。
* `features`: `live`、`4k`、`hd`、`subtitles`、`creative_commons`、`360`、`vr180`、`3d`、`hdr`、`location`、`purchased` から任意の値を、配列かカンマ区切りの文字列で指定します。
* `exactSpelling`: `true` にすると、YouTube のスペル補正なしで入力どおりに検索します。
* `pageToken`: 前のページの `nextPageToken` です。`publishedAfter` なしで `relevance` か `viewCount` で並べた動画検索がこの値を返し、各ページはそれまでのページが返した動画をすべて飛ばします。
* `regionCode` と `languageCode`: 検索する YouTube の地域 (`US`、`KR`、`JP`) と表示言語 (`en`、`ko`、`ja`) です。

`comments`:

* `limit`: 任意の整数、1-500。デフォルトは 100 です。返信も件数に含まれます。
* `order`: `relevance` (デフォルト、YouTube の評価順) か `time` (新しい順) です。
* `includeReplies`: 任意。デフォルトは `true` です。

`channel_videos`:

* `tab`: `videos` (デフォルト)、`shorts`、`streams` のいずれかです。
* `sort`: `latest` (デフォルト)、`popular`、`oldest` のいずれかです。
* `limit`: 任意の整数、1-50。デフォルトは 20 です。

`transcript`:

* `languages`: `["en", "ko"]` のように優先順に並べた字幕の言語です。指定しない場合は、動画のデフォルト字幕、英語、最初のトラックの順に読み取ります。
* `isGenerated`: `true` は自動生成字幕だけを、`false` はアップロード者の字幕だけを読み取ります。
* `trackName`: 読み取る字幕トラックの名前です。
* `translateTo`: 言語コードです。YouTube が字幕をその言語に翻訳します。
* `maxSegments`: 任意の整数、1-5,000。デフォルトは 2,000 です。

## レスポンス例

```json theme={"theme":"css-variables"}
{
  "platform": "youtube",
  "action": "search",
  "query": "wireless earbuds review",
  "order": "relevance",
  "totalResults": 4523475,
  "returnedCount": 1,
  "videos": [
    {
      "position": 1,
      "videoId": "YdJh6QdOGME",
      "url": "https://www.youtube.com/watch?v=YdJh6QdOGME",
      "title": "Earbuds Awards 2026 - Best Bluetooth Earbuds by Category!",
      "channelId": "UCZZ4ivUawsXRktLKej8d6Xw",
      "channelTitle": "Mike O'Brien",
      "channelHandle": "@MikeOBrienMedia",
      "channelIsVerified": true,
      "publishedAt": "2026-11-17T15:39:37Z",
      "publishedTimeText": "21 hours ago",
      "duration": "PT16M35S",
      "durationSeconds": 995,
      "viewCount": 62618,
      "likeCount": 957,
      "category": "Science & Technology",
      "badges": ["New"],
      "thumbnails": { "high": "https://i.ytimg.com/vi/YdJh6QdOGME/hqdefault.jpg" }
    }
  ],
  "nextPageToken": "eyJyIjpbIllkSmg2UWRPR01FIl19"
}
```

## 結果フィールド

* すべてのレスポンスは `platform` と `action` をそのまま返します。一覧には `returnedCount` があります。
* `search` と `recent` は `videos` を返します。各動画には `position`、`videoId`、`url`、`title`、`description`、チャンネルの `channelId`、`channelTitle`、`channelHandle`、`channelUrl`、`channelThumbnail`、`channelIsVerified`、`publishedAt`、`publishedTimeText`、`duration` (ISO 8601)、`durationSeconds`、`viewCount`、`likeCount`、`category`、`thumbnails`、`richThumbnail` (動くプレビュー)、`badges`、`isFamilySafe` があります。映画にはポスター、ジャンル、公開年、出演者、監督を含む `movie` が加わります。
* 検索は、結果ページに表示される `channels`、`playlists`、`shorts`、`shelves` と `totalResults` (YouTube の推定値) も返し、YouTube が検索語句を補正したときは `didYouMean` か `showingResultsFor` を返します。
* `video` は `tags`、`commentCount`、`subscriberCount`、`hasCaptions`、`chapters`、`mostReplayed`、`music`、`descriptionLinks`、`relatedVideos` を加えます。アップロード者のチャプターが先に来て、自動チャプターには `autoGenerated: true` が付きます。
* `comments` は `comments` を返します。各コメントには `commentId`、`parentId` (トップレベルのコメントでは `null`)、`text`、`authorDisplayName`、`authorChannelId`、`authorProfileImageUrl`、`authorIsVerified`、`authorIsChannelOwner`、`isPinned`、`isHearted`、`likeCount`、`replyCount`、`publishedAt`、`updatedAt` があります。`totalCount` は YouTube が表示する件数で、`topLevelCount` と `replyCount` は `returnedCount` の内訳です。
* `channel` は `channelId`、`title`、`handle`、`description`、`country`、`publishedAt`、`subscriberCount`、`videoCount`、`viewCount`、`isVerified`、`keywords`、`links`、`thumbnails`、`bannerUrl`、`rssUrl`、`uploadsPlaylistId` を返します。
* `channel_videos` は `sort` の順に並んだ `videos` と、チャンネルの `channelId`、`channelTitle` を返します。
* `transcript` は字幕の `text`、時刻付きの `segments` (`start` と `duration`、秒単位)、読み取った `language`、`availableLanguages` を返します。`truncated: true` は `maxSegments` で切り詰めた字幕を示します。
* 高評価数を非表示にした動画には `likesHidden: true`、コメントをオフにした動画には `commentsDisabled: true` が付きます。メンバー限定動画には `membersOnly: true` が付き、`viewCount` はありません。
* 存在しない動画、チャンネル、字幕トラックや、年齢制限付き動画のようにログインした視聴者にしか表示されないものは、タスクを `PAGE_UNAVAILABLE` で終了させます。組み合わせられないパラメータはタスクを `BAD_PAYLOAD` で終了させます。課金されるのは完了したリクエストだけです。

## 関連

* [Instagram](https://docs.querying.ai/ja/engines/instagram.md)
* [Threads](https://docs.querying.ai/ja/engines/threads.md)
* [エンジン一覧](https://docs.querying.ai/ja/engines/overview.md)
* [クレジットと上限](https://docs.querying.ai/ja/concepts/credits-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.