# 字幕擷取

使用此工作流程從影片建立字幕檔案。Weydub 支援兩種擷取方式：

- 對影片畫面中已顯示的硬編碼字幕進行 OCR 擷取。
- 對音軌中的口語對話進行 ASR 擷取。

想在建置前檢查輸出品質嗎？請試用對應的 Weydub 網頁工作流程：[產生字幕](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。目前影片的硬性限制為每個檔案 15 分鐘及 1000 MB。 |
| 計費 | 影片工作流程以 30 秒為計費單位。短於 30 秒的影片片段以 30 秒計費。 |
| 失敗的任務 | 若最終 `processStatus > 1`，則不扣除任何點數。 |
| 保留期限 | 字幕檔案與算繪資產遵循 Weydub 網頁保留規則。預設會保留最近 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 遮罩

已知可見字幕區域時，請使用一個或多個遮罩。限定時間範圍的遮罩有助於避免將暫時出現的劇情提示或註冊文字擷取為對話。

| 欄位 | 類型 | 必填 | 說明 |
| --- | --- | --- | --- |
| `type` | 字串 | 是 | 使用 `trans_only_ocr` 進行 OCR 字幕擷取。 |
| `region` | 陣列 | 是 | 四個正規化座標點：`[[x1,y1],[x2,y2],[x3,y3],[x4,y4]]`。 |
| `start` | 數值 | 否 | 開始時間（秒）。若遮罩從影片開頭開始套用，請省略或使用 `0`。 |
| `end` | 數值 | 否 | 結束時間（秒）。適用於僅在片頭套用遮罩的情況。 |
| `to_end` | 數值 | 否 | 影片結束前的秒數。若已知，建議使用明確的 `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` | 布林值 | 是否自動修正辨識出的字幕文字。 |
| `strip_last_punct_on` | 布林值 | 是否移除每行字幕末尾的標點符號。 |
| `scene_filter_on` | 布林值 | 是否篩除非對話的場景文字。若您需要所有可見的字幕文字，擷取英文及其他非 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` | 布林值 | 在支援此功能時啟用說話者偵測。適合用於多人對話。 |
| `extra_video_translate_config.remove_last_punct_on` | 布林值 | 移除產生的字幕行末尾的標點符號。 |

## 參數

| 參數 | 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 擷取不需要算繪新的影片。輪詢至 `processStatus === 1`，再讀取 `srcSrtUrl` 或 `tgtSrtUrl`。

回呼會直接傳送工作項目酬載，不包含輪詢回應所使用的外層 `code` / `msg` / `body` 封裝。

## 代理程式注意事項

- 已燒錄在畫面中的字幕文字請選擇 OCR；口說對白請選擇 ASR。
- 將 `videoInpaintMasks` 和 `extraOptions` 維持緊湊格式並字串化後，再進行簽章。
- 除非您的帳戶合約另有規定，否則請勿以原生陣列形式傳送 OCR 遮罩陣列。
- 使用列舉查詢（`POST /v-w-c/enum/query2`）取得目前對 `sourceLang` 和 `Lang` 的支援資訊；此列舉端點不需要簽章。
- 輪詢至 `processStatus` 為 `1`，再讀取 `srcSrtUrl` 或 `tgtSrtUrl`。
- 在執行保留期限清理前，先儲存字幕檔案。