# 動画文字起こし API

> 動画または音声コンテンツから、話者分離（speaker diarization、話者ラベル付与）付きの単語レベル文字起こしを抽出します。

## 動画文字起こし API

動画または音声ファイルを送信すると、話者分離（各セグメントに検出された話者ラベルが付与されます）付きの単語レベル文字起こしを取得できます。主要プラットフォームの動画および、ローカルアップロードの動画・音声ファイルに対応し、言語設定にも対応しています。

## 対応動画ソース

YouTube、Vimeo、Dailymotion、Kick、Twitch、TikTok、Facebook、Zoom、Rumble など。

[アップロードしたローカルの音声・動画ファイル](https://wayin.ai/ja/api-docs/upload/)も文字起こしできます — ローカルアップロードには **Starter** サブスクリプションプラン以上が必要です。

### ワークフロー

1. **送信**：動画 URL から文字起こしタスクを送信します
2. **ポーリング**：`SUCCEEDED` になるまで結果を取得し続けます

---

## 文字起こしタスクの送信

```
POST https://wayinvideo-api.wayin.ai/api/v2/transcripts
```

### リクエストボディ

| パラメータ | 型 | 必須 | デフォルト | 説明 |
|----------|-----|------|----------|------|
| `video_url` | string | はい | — | ソース動画/音声の URL またはファイル識別子 |
| `source_lang` | string | いいえ | `null` | 動画のソース言語。`null` の場合は自動検出。 |
| `target_lang` | string | いいえ | `null` | 文字起こしの目標言語。`null` の場合は翻訳なし。ソース言語と異なる場合は自動翻訳されます。 |

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/transcripts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -d '{"video_url": "https://www.youtube.com/watch?v=example", "target_lang": "en"}'
```

```python
import requests

requests.post(
    "https://wayinvideo-api.wayin.ai/api/v2/transcripts",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "x-wayinvideo-api-version": "v2",
    },
    json={
        "video_url": "https://www.youtube.com/watch?v=example",
        "target_lang": "en",
    },
)
```

```javascript
await fetch("https://wayinvideo-api.wayin.ai/api/v2/transcripts", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "x-wayinvideo-api-version": "v2",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    video_url: "https://www.youtube.com/watch?v=example",
    target_lang: "en",
  }),
});
```

### レスポンス

```json
{"data": {"id": "trans_proj_001", "name": "sample project name", "status": "CREATED"}}
```

---

## 使用例

代表的な文字起こしのシナリオです。`YOUR_API_KEY` は [API ダッシュボード](https://wayin.ai/wayinvideo/api-dashboard) で取得したキーに置き換えてください。

### YouTube 動画を文字起こしする

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/transcripts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -H "Content-Type: application/json" \
  -d '{"video_url": "https://www.youtube.com/watch?v=EXAMPLE"}'
```

### 複数の話者を含むポッドキャストを文字起こしする

任意のポッドキャスト音声 URL（または [アップロード済みファイル識別子](https://wayin.ai/ja/api-docs/upload/)）を渡すだけで、話者分離は自動的に行われ、レスポンスの各セグメントに `speaker` ラベルが付与されます。

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/transcripts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -H "Content-Type: application/json" \
  -d '{"video_url": "https://www.youtube.com/watch?v=EXAMPLE"}'
```

### 英語以外の文字起こしを英語に翻訳する

`target_lang` を指定するとオンザフライで翻訳されます。ソース言語が分かっている場合は `source_lang` と併用できます。

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/transcripts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.youtube.com/watch?v=EXAMPLE",
    "source_lang": "ja",
    "target_lang": "en"
  }'
```

---

## 文字起こし結果の取得

```
GET https://wayinvideo-api.wayin.ai/api/v2/transcripts/results/{id}
```

```bash
curl -X GET https://wayinvideo-api.wayin.ai/api/v2/transcripts/results/trans_proj_001 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2"
```

### レスポンス

```json
{
  "data": {
    "status": "SUCCEEDED", "cost_usage": 27.0,
    "transcript": [
      {"text": "Welcome to today's presentation", "language": null, "start": 200, "end": 4500, "speaker": "Speaker 1"},
      {"text": "Thanks for coming", "language": null, "start": 5000, "end": 8200, "speaker": "Speaker 2"}
    ]
  }
}
```

### レスポンスフィールド

| フィールド | 型 | 説明 |
|----------|-----|------|
| `status` | string | `CREATED`, `QUEUED`, `ONGOING`, `SUCCEEDED`, `FAILED` |
| `error_message` | string | エラーの理由（`FAILED` のときのみ） |
| `cost_usage` | number | 消費した API ユニット数 |
| `transcript` | array | 文字起こしセグメントのリスト |

### 文字起こしセグメント

| フィールド | 型 | 説明 |
|----------|-----|------|
| `text` | string | 文字起こしされたテキスト |
| `language` | string \| null | 検出された言語コード。検出できない場合は `null` |
| `start` | integer | 開始時刻（ミリ秒） |
| `end` | integer | 終了時刻（ミリ秒） |
| `speaker` | string | 話者ラベル（例：`"Speaker 1"`） |


---

## FAQ

### 動画の最大長さは？

長さの厳密な制限はありません。本 API は短いクリップから長尺の動画・音声コンテンツまで、対応しているソースプラットフォーム上で処理できます。

### API は単語レベルのタイムスタンプを返しますか？

はい。各文字起こしセグメントには、ミリ秒単位の `start` と `end` タイムスタンプ、文字起こしされた `text`、検出された `language`、話者分離で付与された `speaker` ラベルが含まれます。

### 話者分離はどのように動作しますか？

話者は自動的に検出され、セグメントごとにラベル（`Speaker 1`、`Speaker 2`、…）が付与されます。設定は不要です — 話者分離はすべての文字起こしタスクで実行されます。

### 対応している音声・動画フォーマットは？

ソース URL は YouTube、Vimeo、Dailymotion、Kick、Twitch、TikTok、Facebook、Zoom、Rumble などに対応しています。ローカルアップロードでは `mp4`、`mov`、`webm`、`avi` を送信できます（音声のみのファイルはいずれかのコンテナにミックスしてください）。

### 文字起こしを別の言語に翻訳できますか？

はい — `target_lang` パラメーターを指定してください。`target_lang` がソース言語と異なる場合に翻訳が行われます。言語コードの全リストは [対応言語](https://wayin.ai/ja/api-docs/supported-languages/) を参照してください。