# 字幕抽出

このワークフローを使用して、動画から字幕ファイルを作成します。Weydub は、次の2つの抽出方法をサポートしています。

- 動画フレーム内にすでに表示されているハードコード字幕を対象とする OCR 抽出。
- 音声トラック内の発話を対象とする ASR 抽出。

実装前に出力品質を確認したい場合は、対応する Weydub の Web ワークフローである[字幕を生成](https://weydub.com/subtitle-generator/)をお試しください。

時間軸を考慮した Video OCR、シーンテキストのフィルタリング、字幕作成に適した ASR セグメンテーションについてシステムレベルの説明を確認するには、[Video OCR と ASR を使用した AI 字幕生成](https://weydub.com/technology/ai-subtitle-generation-video-ocr-asr/)を参照してください。

## エンドポイント

```text
POST /v-w-c/gateway/ve/work/free
```

字幕抽出は非同期で行われます。`body.idProject` と `body.dataList[].id` を保存し、ポーリング、コールバック、再試行動作、コールバック署名には[非同期タスクモデル](./async-task-model.md)を使用してください。

## アクセスと制限

| ルール | 要件 |
| --- | --- |
| アカウントアクセス | コア動画 API へのアクセスが有効になっている必要があります。OCR/ASR 抽出は通常、動画タスクファミリーの一部ですが、アカウントポリシーによってバッチサイズや高度なオプションが制限される場合があります。 |
| ソース動画 | 安定した公開 HTTPS URL を使用してください。現在の動画の厳格な上限は、1ファイルあたり 15 分、かつ1ファイルあたり 1000 MBです。 |
| 課金 | 動画ワークフローは 30 秒単位で課金されます。30 秒未満のクリップは 30 秒として計算されます。 |
| 失敗したタスク | 最終的に `processStatus > 1` となった場合、クレジットは一切差し引かれません。 |
| 保持期間 | 字幕ファイルとレンダリング済みアセットには、Weydub の Web 保持ルールが適用されます。デフォルトでは、直近 30 日間のソースアセットとレンダリング済みアセットが保持されます。コールバック後に永続保存用のコピーをダウンロードしてください。 |

## OCR または ASR の選択

| モード | 使用する場面 | 必須シグナル | 一般的な出力 |
| --- | --- | --- | --- |
| OCR ハードコード字幕抽出 | 字幕が画像に焼き付けられており、通常はフレーム下部に表示されている場合。 | `needChineseOcclude: 14`、`videoInpaintMasks`、`videoInpaintLang`、`lang`。 | `srcSrtUrl`、`tgtSrtUrl`。 |
| ASR 発話抽出 | 音声トラックに会話があり、タイムスタンプ付きの文字起こしが必要な場合。 | `needWanyin: 1`、`wyTaskType: "ONLY_ASR"`、`wyNeedText: 0`。 | `srcSrtUrl`、`tgtSrtUrl`。 |

発話のみを含む動画の文字起こしに OCR を使用しないでください。音声を伴わないハードコード字幕の読み取りに ASR を使用しないでください。

## OCR 字幕抽出ペイロード

字幕がすでに動画の映像に埋め込まれている場合は、OCR を使用します。

```json
{
  "urls": ["https://example.com/video.mp4"],
  "needChineseOcclude": 14,
  "videoInpaintLang": "en",
  "lang": "en",
  "videoInpaintMasks": "[{\"type\":\"trans_only_ocr\",\"region\":[[0,0.8],[1,0.8],[1,1],[0,1]]}]",
  "extraOptions": "{\"extra_inpaint_config\":{\"auto_correct_on\":false,\"strip_last_punct_on\":true,\"scene_filter_on\":false}}",
  "callback": "https://your-domain.example/webhooks/weydub"
}
```

注記:

- `needChineseOcclude` は `14` でなければなりません。
- `videoInpaintMasks` は OCR 抽出に必須であり、署名前にコンパクトな JSON 文字列にすることを推奨します。
- `type` は `trans_only_ocr` にすることを推奨します。
- 翻訳が不要な場合は、`lang` を `videoInpaintLang` と同じ値に設定します。
- 座標は `0` から `1` の範囲に正規化され、左上、右上、右下、左下の順に並べます。

## OCR マスク

表示される字幕領域が分かっている場合は、1つ以上のマスクを使用します。時間範囲を限定したマスクは、一時的なストーリーのヒントや登録テキストが台詞として抽出されるのを防ぐのに役立ちます。

| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `type` | string | はい | OCR 字幕抽出には `trans_only_ocr` を使用します。 |
| `region` | array | はい | 正規化された4点: `[[x1,y1],[x2,y2],[x3,y3],[x4,y4]]`。 |
| `start` | number | いいえ | 開始時刻（秒）。マスクを冒頭から適用する場合は、省略するか `0` を使用します。 |
| `end` | number | いいえ | 終了時刻（秒）。マスクをイントロにのみ適用する場合に便利です。 |
| `to_end` | number | いいえ | 動画終了の何秒前かを示す秒数。既知の場合は、明示的な `end` の使用を推奨します。 |

よく使用される領域:

| シナリオ | 領域 |
| --- | --- |
| 縦型 16:9 の字幕帯 | `[[0,0.56],[1,0.56],[1,0.76],[0,0.76]]` |
| 水平方向の標準字幕領域 | `[[0,0.8],[1,0.8],[1,1],[0,1]]` |
| カスタム下部帯 | `[[0,0.7],[1,0.7],[1,0.95],[0,0.95]]` |

## OCR オプション

`extraOptions.extra_inpaint_config` で OCR のクリーンアップ処理を調整できます:

| オプション | 型 | 説明 |
| --- | --- | --- |
| `auto_correct_on` | boolean | 認識された字幕テキストを自動修正するかどうか。 |
| `strip_last_punct_on` | boolean | 各字幕行から末尾の句読点を削除するかどうか。 |
| `scene_filter_on` | boolean | セリフ以外のシーンテキストをフィルタリングするかどうか。画面に表示されるすべての字幕テキストを抽出する場合、英語やその他の非CJK言語の字幕抽出では無効にすることがよくあります。 |

アカウント契約に別段の定めがない限り、公開 API ペイロードでは `extraOptions` をコンパクトな JSON 文字列として保持してください。

## ASR 字幕抽出ペイロード

動画に音声があり、タイムコード付きの文字起こしが必要な場合は ASR を使用します。

```json
{
  "urls": ["https://example.com/video.mp4"],
  "needWanyin": 1,
  "sourceLang": "en",
  "lang": "en",
  "wyTaskType": "ONLY_ASR",
  "needWyEdit": 0,
  "wyNeedText": 0,
  "extraOptions": "{\"asr_speaker_detect_on\":true,\"extra_video_translate_config\":{\"remove_last_punct_on\":true}}",
  "callback": "https://your-domain.example/webhooks/weydub"
}
```

注記:

- `wyTaskType` は `ONLY_ASR` である必要があります。
- `wyNeedText: 0` は、字幕を新しい動画にレンダリングしないことを意味します。
- `needWyEdit: 0` は、この抽出ジョブの手動編集/プロドラフト動作を無効にします。
- `sourceLang` は音声で話されている言語です。`lang` は字幕の出力言語です。翻訳が不要な場合は同じコードを使用してください。

## ASR オプション

| オプション | 型 | 説明 |
| --- | --- | --- |
| `asr_speaker_detect_on` | boolean | サポートされている場合に話者検出を有効にします。複数話者による会話に便利です。 |
| `extra_video_translate_config.remove_last_punct_on` | boolean | 生成された字幕行から末尾の句読点を削除します。 |

## パラメーター

| パラメータ | OCR | ASR | 説明 |
| --- | --- | --- | --- |
| `urls` | 必須 | 必須 | 公開動画のURL。本番環境では、安定したHTTPS URLを使用してください。 |
| `needChineseOcclude` | `14` | 使用しない | OCR字幕抽出モード。 |
| `videoInpaintLang` | 必須 | 使用しない | 表示されている字幕テキストの言語。 |
| `videoInpaintMasks` | 必須 | 使用しない | OCR領域を記述するコンパクトなJSON文字列。 |
| `extraOptions` | 任意 | 任意 | OCRのクリーンアップまたはASRオプション用のコンパクトなJSON文字列。 |
| `needWanyin` | 使用しない | `1` | ASRの音声処理を有効にします。 |
| `sourceLang` | 任意 | 必須 | 音声の言語／ソース言語。 |
| `lang` | 必須 | 必須 | 出力字幕の言語。翻訳が不要な場合は、ソース言語と同じ値を使用してください。 |
| `wyTaskType` | 使用しない | `ONLY_ASR` | ASR専用のタスクタイプ。 |
| `needWyEdit` | 使用しない | `0` | 抽出時の手動編集／プロドラフトのフローを無効にします。 |
| `wyNeedText` | 使用しない | `0` | 字幕を新しい動画にレンダリングしません。 |
| `callback` | 任意 | 任意 | 非同期完了通知用のWebhook URL。 |
| `uid` | 任意 | 任意 | アカウントでサブユーザー追跡を使用する場合の、ユーザー／顧客の識別子。 |

## 出力

正常に完了した抽出タスクでは、次の値が返される場合があります。

- `srcSrtUrl`
- `tgtSrtUrl`
- `processStatus`
- `processProgress`
- `paidPoint`
- 返されたワークアイテム内のタスクメタデータ

OCR と ASR の抽出では、新しい動画をレンダリングする必要はありません。`srcSrtUrl` または `tgtSrtUrl` を読み取る前に、`processStatus === 1` になるまでポーリングしてください。

コールバックでは、ポーリング応答で使用される外側の `code` / `msg` / `body` ラッパーを介さず、ワークアイテムのペイロードが直接送信されます。

## エージェント向けの注意事項

- 焼き付けられた字幕テキストには OCR を、音声による会話には ASR を選択してください。
- 署名する前に、`videoInpaintMasks` と `extraOptions` をコンパクト化して文字列化してください。
- アカウント契約にその旨が明記されている場合を除き、OCR のマスク配列をネイティブ配列として送信しないでください。
- 列挙型クエリ（`POST /v-w-c/enum/query2`）を使用して、現在サポートされている `sourceLang` および `Lang` の値を取得してください。この列挙型エンドポイントでは署名は必要ありません。
- `srcSrtUrl` または `tgtSrtUrl` を読み取る前に、`processStatus` が `1` になるまでポーリングしてください。
- 保持期間に基づくクリーンアップが行われる前に、字幕ファイルを保存してください。