---
title: research youtube
description: YouTubeの公開動画と字幕を調べる。
canonical_url: https://orchestor.io/docs/cli/research/youtube
markdown_url: https://orchestor.io/docs/cli/research/youtube.md
contentType: reference
---

# research youtube

`orc research youtube` は、YouTubeのチャンネル・動画を検索し、公開情報や字幕を取得するコマンドです。動画の公開日時・長さ・地域などで検索を絞り込み、複数の動画IDから字幕をまとめて取得できます。

認証済みのCLIと、アクセス可能なWorkspaceが必要です。`--workspace` で今回の対象を指定できます。

## 使い方

```bash title="terminal"
orc research youtube videos search --query "生成AI" --workspace <workspace-id> --json
```

*公開動画を検索する。*

## サブコマンド

### `channels get`

`UC` で始まるチャンネルIDまたは `@` を除いたhandleでチャンネルを取得します。表示名は使いません。

```bash title="terminal"
orc research youtube channels get [options]
```

#### 固有のオプション

##### `--channel-id`

YouTube channel ID, starting with UC; not a display name.

型: `string`。任意。

```bash title="terminal"
orc research youtube channels get --channel-id <value>
```

##### `--handle`

Channel handle without @.; max 100 chars

型: `string`。任意。

```bash title="terminal"
orc research youtube channels get --handle <value>
```

### `channels videos list`

チャンネルの公開Videosタブを取得します。`--sort` で新しい順または人気順を選び、`--include-extras true` で追加の公開日時や反応を取得できます。

```bash title="terminal"
orc research youtube channels videos list [options]
```

#### 固有のオプション

##### `--channel-id`

YouTube channel ID, starting with UC; not a display name.

型: `string`。任意。

```bash title="terminal"
orc research youtube channels videos list --channel-id <value>
```

##### `--handle`

Channel handle without @.; max 100 chars

型: `string`。任意。

```bash title="terminal"
orc research youtube channels videos list --handle <value>
```

##### `--sort`

Order the public Videos tab by recency or popularity. Omission sends no sort override.; enum: latest|popular

型: `string`。任意。

```bash title="terminal"
orc research youtube channels videos list --sort <value>
```

##### `--include-extras`

Request enriched publication dates, descriptions and engagement with true. Send the literal query string true or false. Omission sends no extras override.; enum: true|false

型: `string`。任意。

```bash title="terminal"
orc research youtube channels videos list --include-extras <value>
```

### `channels search`

`--query` の語句でチャンネルを検索します。続きは返されたカーソルで取得します。

```bash title="terminal"
orc research youtube channels search [options]
```

#### 固有のオプション

##### `--query`

Search text.; max 500 chars

型: `string`。必須。

```bash title="terminal"
orc research youtube channels search --query <value>
```

### `videos search`

動画を検索し、チャンネル、公開日時、長さ、言語、地域、並び順で絞り込めます。`--include-extras true` は長さと反応の追加取得で、1ページに5 provider creditsが加算されます。

```bash title="terminal"
orc research youtube videos search [options]
```

#### 固有のオプション

##### `--query`

Search text.; max 500 chars

型: `string`。必須。

```bash title="terminal"
orc research youtube videos search --query <value>
```

##### `--channel-id`

YouTube channel ID, starting with UC; not a display name.

型: `string`。任意。

```bash title="terminal"
orc research youtube videos search --channel-id <value>
```

##### `--published-after`

Lower publication-time bound in ISO 8601 with a timezone. Must precede published_before when both are supplied. Omission adds no date cutoff.

型: `string`。任意。

```bash title="terminal"
orc research youtube videos search --published-after <value>
```

##### `--published-before`

Upper publication-time bound in ISO 8601 with a timezone. Must follow published_after when both are supplied. Omission adds no upper date bound.

型: `string`。任意。

```bash title="terminal"
orc research youtube videos search --published-before <value>
```

##### `--order`

Requested provider sort key. When omitted, Orchestor sends no order override.; enum: date|relevance|viewCount|rating|title

型: `string`。任意。

```bash title="terminal"
orc research youtube videos search --order <value>
```

##### `--max-results`

Requested page size from 1 to 50. The provider may return fewer rows. Omission sends no page-size override.

型: `number`。任意。

```bash title="terminal"
orc research youtube videos search --max-results <value>
```

##### `--duration`

Provider video-duration category. any requests no duration restriction; omission sends no override. Category boundaries are determined by the provider.; enum: short|medium|long|any

型: `string`。任意。

```bash title="terminal"
orc research youtube videos search --duration <value>
```

##### `--language`

Two-letter preferred language. Caption behavior differs between single and batch endpoints.

型: `string`。任意。

```bash title="terminal"
orc research youtube videos search --language <value>
```

##### `--region`

Two-uppercase-letter region code forwarded to the provider, for example JP or US. Omission sends no regional override.

型: `string`。任意。

```bash title="terminal"
orc research youtube videos search --region <value>
```

##### `--include-extras`

Adds duration and engagement at an additional provider cost of 5 credits per page.; enum: true|false

型: `string`。任意。

```bash title="terminal"
orc research youtube videos search --include-extras <value>
```

### `transcripts get`

1〜20件の重複しない動画IDを `--ids` へ渡し、字幕を一括取得します。字幕の形式は `--export-format`、CLI出力の形式は `--format` で指定します。

```bash title="terminal"
orc research youtube transcripts get [options]
```

#### 固有のオプション

##### `--export-format`

Requested caption representation. Defaults to timed segments with millisecond timing; text requests combined caption text.; enum: text|segments

型: `string`。任意。

```bash title="terminal"
orc research youtube transcripts get --export-format <value>
```

##### `--ids`

(required) One to twenty distinct video IDs. Correlate results using each row index and target.; csv

型: `string`。任意。

```bash title="terminal"
orc research youtube transcripts get --ids <value>
```

##### `--language`

Two-letter preferred language. Caption behavior differs between single and batch endpoints.

型: `string`。任意。

```bash title="terminal"
orc research youtube transcripts get --language <value>
```

### `videos get`

watch・Shorts・live・youtu.beの公開動画URLを指定して動画情報を取得します。

```bash title="terminal"
orc research youtube videos get [options]
```

#### 固有のオプション

##### `--url`

YouTube watch, Shorts, live or youtu.be URL.; max 2048 chars

型: `string`。必須。

```bash title="terminal"
orc research youtube videos get --url <value>
```

##### `--language`

Two-letter preferred language. Caption behavior differs between single and batch endpoints.

型: `string`。任意。

```bash title="terminal"
orc research youtube videos get --language <value>
```

### `videos transcript get`

公開動画URLから字幕を取得します。音声からのAI文字起こしや翻訳は行いません。

```bash title="terminal"
orc research youtube videos transcript get [options]
```

#### 固有のオプション

##### `--url`

YouTube watch, Shorts, live or youtu.be URL.; max 2048 chars

型: `string`。必須。

```bash title="terminal"
orc research youtube videos transcript get --url <value>
```

##### `--language`

Two-letter preferred language. Caption behavior differs between single and batch endpoints.

型: `string`。任意。

```bash title="terminal"
orc research youtube videos transcript get --language <value>
```

## 使用例

### 2つの動画の字幕をテキストで取得する。

```bash title="terminal"
orc research youtube transcripts get --ids abcdefghijk,lmnopqrstuv --export-format text --workspace <workspace-id> --json
```

*2つの動画の字幕をテキストで取得する。*

## 出力と継続

継続できる一覧ではAPIのトップレベル `pagination.next_cursor` を `--cursor` に渡し、条件を維持します。CLIのJSON出力からは `data.pagination.next_cursor` を取り出してください。取得内容の内部にある `data.next_cursor` は継続に使いません。`has_more: null` は不明を意味し、完了ではありません。`--page-all` は使えません。

`--json` ではAPIレスポンス全体をCLIの `data` に保持します。取得内容は `data.data`、継続情報は `data.pagination`、取得元情報は `data.source` です。`--raw` はCLIの外枠を外し、`--field data` はAPIのデータだけを選択します。欠損値やnullを0として扱わないでください。

`data.usage.provider_credits` は取得元の単位で、Orchestorの請求単位とは異なります。

## 字幕の取得と部分成功

`transcripts get` はPOSTですがreadスコープです。`--ids` は1〜20件の重複しない動画IDをカンマ区切りで指定します。`--export-format text` は字幕の形式、`--format json` はCLI出力形式です。segmentsの時刻はミリ秒です。公開字幕・自動字幕を取得し、音声からのAI文字起こしや翻訳は行いません。HTTP 200でも部分成功があるため、各行の `status` と `summary` を確認し、成功済みの行を再送しないでください。

## 必要な権限

APIキーではreadスコープが必要です。 プロバイダーのキーはサーバー側で管理します。

## グローバルオプション

`orc research youtube` では、次の[グローバルオプション](https://orchestor.io/docs/cli/global-flags.md)を使用できます。

- [`--help`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%98%E3%83%AB%E3%83%97)
- [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%AF%E3%83%BC%E3%82%AF%E3%82%B9%E3%83%9A%E3%83%BC%E3%82%B9)
- [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-%E5%87%BA%E5%8A%9B)
- [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-%E5%87%BA%E5%8A%9B)
- [`--format`](https://orchestor.io/docs/cli/global-flags.md#%E5%87%BA%E5%8A%9B%E5%BD%A2%E5%BC%8F)
- [`--field`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%95%E3%82%A3%E3%83%BC%E3%83%AB%E3%83%89%E3%81%AE%E6%8A%BD%E5%87%BA)
- [`--fields`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%95%E3%82%A3%E3%83%BC%E3%83%AB%E3%83%89%E3%81%AE%E6%8A%BD%E5%87%BA)
- [`--raw`](https://orchestor.io/docs/cli/global-flags.md#%E5%80%A4%E3%81%A0%E3%81%91%E3%82%92%E5%87%BA%E5%8A%9B)
- [`--output`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%81%B8%E3%81%AE%E5%87%BA%E5%8A%9B)
- [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%9A%E3%83%BC%E3%82%B8%E9%80%81%E3%82%8A)
- [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E3%81%AE%E4%BA%8B%E5%89%8D%E7%A2%BA%E8%AA%8D)
- [`--yes`](https://orchestor.io/docs/cli/global-flags.md#%E7%A2%BA%E8%AA%8D%E3%81%AE%E7%9C%81%E7%95%A5)
- [`--cursor`](https://orchestor.io/docs/cli/global-flags.md)
- [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#%E6%A8%99%E6%BA%96%E5%85%A5%E5%8A%9B)
- [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#%E6%A8%99%E6%BA%96%E5%85%A5%E5%8A%9B)
- [`--timing`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E6%99%82%E9%96%93)

各オプションの詳細と使用例は、[グローバルオプション](https://orchestor.io/docs/cli/global-flags.md)を参照してください。

## 関連項目

- 調査CLIの概要
- [グローバルオプション](https://orchestor.io/docs/cli/global-flags.md)

---

[Documentation index](https://orchestor.io/docs/llms.txt)