# Trích xuất phụ đề

Sử dụng quy trình này để tạo tệp phụ đề từ video. Weydub hỗ trợ hai phương thức trích xuất:

- Trích xuất bằng OCR cho phụ đề đã được ghi cứng và hiển thị trong khung hình video.
- Trích xuất bằng ASR cho lời thoại trong rãnh âm thanh.

Bạn muốn kiểm tra chất lượng đầu ra trước khi bắt tay xây dựng? Hãy thử quy trình web Weydub tương ứng: [Tạo phụ đề](https://weydub.com/subtitle-generator/).

Để xem phần giải thích ở cấp hệ thống về Video OCR theo thời gian, việc lọc văn bản trong cảnh và phân đoạn ASR phù hợp để tạo phụ đề, hãy đọc [Tạo phụ đề bằng AI với Video OCR và ASR](https://weydub.com/technology/ai-subtitle-generation-video-ocr-asr/).

## Điểm cuối

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

Việc trích xuất phụ đề diễn ra không đồng bộ. Lưu `body.idProject` và `body.dataList[].id`, sau đó sử dụng [Mô hình tác vụ không đồng bộ](./async-task-model.md) để thăm dò trạng thái, xử lý callback, cơ chế thử lại và ký callback.

## Quyền truy cập và giới hạn

| Quy tắc | Yêu cầu |
| --- | --- |
| Quyền truy cập tài khoản | Phải bật quyền truy cập API video cốt lõi. Việc trích xuất OCR/ASR thường thuộc nhóm tác vụ video, nhưng chính sách tài khoản vẫn có thể giới hạn quy mô lô hoặc các tùy chọn nâng cao. |
| Video nguồn | Sử dụng một HTTPS URL công khai, ổn định. Giới hạn cứng hiện tại đối với video là 15 phút cho mỗi tệp và 1000 MB cho mỗi tệp. |
| Thanh toán | Các quy trình video được tính phí theo đơn vị 30 giây. Các clip ngắn hơn 30 giây được tính là 30 giây. |
| Tác vụ không thành công | Nếu `processStatus > 1` khi tác vụ kết thúc, sẽ không bị trừ tín dụng nào. |
| Lưu giữ | Tệp phụ đề và tài nguyên đã kết xuất tuân theo quy tắc lưu giữ trên web của Weydub. Theo mặc định, tài nguyên nguồn/đã kết xuất trong 30 ngày gần nhất được giữ lại. Hãy tải xuống các bản sao để lưu giữ lâu dài sau callback. |

## Chọn OCR hoặc ASR

| Chế độ | Khi nào nên dùng | Tín hiệu bắt buộc | Đầu ra thường gặp |
| --- | --- | --- | --- |
| Trích xuất phụ đề ghi cứng bằng OCR | Phụ đề được ghi cứng vào hình ảnh, thường ở phía dưới khung hình. | `needChineseOcclude: 14`, `videoInpaintMasks`, `videoInpaintLang`, `lang`. | `srcSrtUrl`, `tgtSrtUrl`. |
| Trích xuất lời nói bằng ASR | Lời thoại có trong rãnh âm thanh và bạn cần bản chép lời có mốc thời gian. | `needWanyin: 1`, `wyTaskType: "ONLY_ASR"`, `wyNeedText: 0`. | `srcSrtUrl`, `tgtSrtUrl`. |

Không sử dụng OCR để chép lời các video chỉ có lời nói. Không sử dụng ASR để đọc phụ đề ghi cứng không kèm âm thanh.

## Dữ liệu yêu cầu trích xuất phụ đề OCR

Sử dụng OCR khi phụ đề đã được nhúng trong hình ảnh video.

```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"
}
```

Lưu ý:

- `needChineseOcclude` phải là `14`.
- `videoInpaintMasks` là bắt buộc để trích xuất OCR và nên là một chuỗi JSON thu gọn trước khi ký.
- `type` nên là `trans_only_ocr`.
- Đặt `lang` bằng `videoInpaintLang` khi không cần dịch.
- Tọa độ được chuẩn hóa từ `0` đến `1`, theo thứ tự: góc trên bên trái, góc trên bên phải, góc dưới bên phải, góc dưới bên trái.

## Mặt nạ OCR

Sử dụng một hoặc nhiều mặt nạ khi đã biết vùng phụ đề hiển thị. Mặt nạ giới hạn theo thời gian giúp tránh trích xuất các gợi ý cốt truyện tạm thời hoặc văn bản đăng ký và coi chúng là lời thoại.

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `type` | string | Có | Sử dụng `trans_only_ocr` để trích xuất phụ đề OCR. |
| `region` | array | Có | Bốn điểm được chuẩn hóa: `[[x1,y1],[x2,y2],[x3,y3],[x4,y4]]`. |
| `start` | number | Không | Thời gian bắt đầu tính bằng giây. Bỏ trường này hoặc sử dụng `0` khi mặt nạ được áp dụng ngay từ đầu. |
| `end` | number | Không | Thời gian kết thúc tính bằng giây. Hữu ích khi mặt nạ chỉ áp dụng cho phần mở đầu. |
| `to_end` | number | Không | Số giây trước thời điểm video kết thúc. Ưu tiên sử dụng `end` tường minh khi đã biết. |

Các vùng thường dùng:

| Tình huống | Vùng |
| --- | --- |
| Dải phụ đề dọc 16:9 | `[[0,0.56],[1,0.56],[1,0.76],[0,0.76]]` |
| Vùng phụ đề tiêu chuẩn theo chiều ngang | `[[0,0.8],[1,0.8],[1,1],[0,1]]` |
| Dải phía dưới tùy chỉnh | `[[0,0.7],[1,0.7],[1,0.95],[0,0.95]]` |

## Tùy chọn OCR

`extraOptions.extra_inpaint_config` có thể điều chỉnh quá trình làm sạch kết quả OCR:

| Tùy chọn | Kiểu | Mô tả |
| --- | --- | --- |
| `auto_correct_on` | boolean | Có tự động sửa văn bản phụ đề được nhận dạng hay không. |
| `strip_last_punct_on` | boolean | Có xóa dấu câu ở cuối mỗi dòng phụ đề hay không. |
| `scene_filter_on` | boolean | Có lọc văn bản trong cảnh không phải lời thoại hay không. Tùy chọn này thường bị tắt khi trích xuất phụ đề tiếng Anh và các ngôn ngữ không thuộc CJK khác nếu bạn muốn giữ lại toàn bộ văn bản phụ đề hiển thị. |

Giữ `extraOptions` dưới dạng chuỗi JSON thu gọn cho các payload API công khai, trừ khi hợp đồng tài khoản của bạn quy định khác.

## Dữ liệu yêu cầu trích xuất phụ đề ASR

Sử dụng ASR khi video có lời nói và bạn cần bản chép lời có mốc thời gian.

```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"
}
```

Lưu ý:

- `wyTaskType` phải là `ONLY_ASR`.
- `wyNeedText: 0` có nghĩa là không kết xuất phụ đề vào một video mới.
- `needWyEdit: 0` vô hiệu hóa hành vi chỉnh sửa thủ công/pro-draft cho tác vụ trích xuất này.
- `sourceLang` là ngôn ngữ lời nói. `lang` là ngôn ngữ đầu ra của phụ đề; sử dụng cùng một mã khi không cần dịch.

## Tùy chọn ASR

| Tùy chọn | Kiểu | Mô tả |
| --- | --- | --- |
| `asr_speaker_detect_on` | boolean | Bật tính năng phát hiện người nói khi được hỗ trợ. Hữu ích cho lời thoại có nhiều người nói. |
| `extra_video_translate_config.remove_last_punct_on` | boolean | Xóa dấu câu ở cuối các dòng phụ đề được tạo. |

## Tham số

| Tham số | OCR | ASR | Mô tả |
| --- | --- | --- | --- |
| `urls` | Bắt buộc | Bắt buộc | URL video công khai. Sử dụng các URL HTTPS ổn định trong môi trường sản xuất. |
| `needChineseOcclude` | `14` | Không sử dụng | Chế độ trích xuất phụ đề OCR. |
| `videoInpaintLang` | Bắt buộc | Không sử dụng | Ngôn ngữ của văn bản phụ đề hiển thị. |
| `videoInpaintMasks` | Bắt buộc | Không sử dụng | Chuỗi JSON thu gọn mô tả các vùng OCR. |
| `extraOptions` | Tùy chọn | Tùy chọn | Chuỗi JSON thu gọn dùng để làm sạch kết quả OCR hoặc thiết lập các tùy chọn ASR. |
| `needWanyin` | Không sử dụng | `1` | Bật tính năng xử lý lời nói cho ASR. |
| `sourceLang` | Tùy chọn | Bắt buộc | Ngôn ngữ lời nói/ngôn ngữ nguồn. |
| `lang` | Bắt buộc | Bắt buộc | Ngôn ngữ đầu ra của phụ đề. Sử dụng cùng giá trị với ngôn ngữ nguồn khi không cần dịch. |
| `wyTaskType` | Không sử dụng | `ONLY_ASR` | Loại tác vụ chỉ dành cho ASR. |
| `needWyEdit` | Không sử dụng | `0` | Vô hiệu hóa quy trình chỉnh sửa thủ công/pro-draft cho việc trích xuất. |
| `wyNeedText` | Không sử dụng | `0` | Không kết xuất phụ đề vào một video mới. |
| `callback` | Tùy chọn | Tùy chọn | Webhook URL để thông báo hoàn tất không đồng bộ. |
| `uid` | Tùy chọn | Tùy chọn | Mã định danh người dùng/khách hàng của bạn khi tài khoản sử dụng tính năng theo dõi người dùng phụ. |

## Đầu ra

Các tác vụ trích xuất thành công có thể trả về:

- `srcSrtUrl`
- `tgtSrtUrl`
- `processStatus`
- `processProgress`
- `paidPoint`
- siêu dữ liệu tác vụ trong mục công việc được trả về

Việc trích xuất OCR và ASR không cần kết xuất video mới. Hãy thăm dò cho đến khi `processStatus === 1` rồi mới đọc `srcSrtUrl` hoặc `tgtSrtUrl`.

Các callback gửi trực tiếp payload của mục công việc, không có lớp bao `code` / `msg` / `body` bên ngoài được sử dụng trong phản hồi thăm dò.

## Ghi chú dành cho tác nhân

- Chọn OCR cho văn bản phụ đề được ghi cứng vào video; chọn ASR cho lời thoại.
- Giữ `videoInpaintMasks` và `extraOptions` ở dạng chuỗi thu gọn trước khi ký.
- Không gửi các mảng mặt nạ OCR dưới dạng mảng gốc, trừ khi hợp đồng tài khoản của bạn quy định như vậy.
- Sử dụng truy vấn enum (`POST /v-w-c/enum/query2`) để lấy thông tin hỗ trợ hiện tại cho `sourceLang` và `Lang`; endpoint enum này không yêu cầu ký.
- Thăm dò cho đến khi `processStatus` bằng `1` rồi mới đọc `srcSrtUrl` hoặc `tgtSrtUrl`.
- Lưu trữ các tệp phụ đề trước khi quá trình dọn dẹp theo chính sách lưu giữ diễn ra.