# Tài liệu tham khảo API

Tài liệu tham khảo này cung cấp cho các nhà phát triển và tác nhân tự động hóa một nơi tra cứu cô đọng về các endpoint Weydub API, kiểm tra quyền truy cập, cấu trúc yêu cầu, hành vi không đồng bộ, quy tắc thanh toán/lưu giữ và các dấu hiệu phục vụ việc khắc phục sự cố.

## Thông tin cơ bản về yêu cầu

| Hạng mục | Giá trị |
| --- | --- |
| URL cơ sở | `https://api.zhaoli.com` |
| Giao thức | HTTPS |
| Phương thức | `POST` cho các lệnh gọi API được nêu trong tài liệu |
| Mã hóa | UTF-8 |
| Loại nội dung | `application/json` |
| Xác thực | Các header `AppKey` và `AppSign`, ngoại trừ các endpoint được đánh dấu rõ ràng là không cần ký |

Một số tên cơ sở hạ tầng cũ vẫn có thể xuất hiện trong các tài nguyên demo công khai hoặc đường dẫn tài khoản cũ. Hãy coi tài liệu Weydub API này là quy ước hiện hành dành cho sản phẩm.

## Trước khi thực hiện lệnh gọi

| Kiểm tra | Nội dung cần xác nhận | Tại sao điều này quan trọng |
| --- | --- | --- |
| Quyền truy cập API | Tài khoản Weydub đã đăng nhập của bạn có thể kích hoạt quyền truy cập API miễn phí; hãy xác nhận các quyền dành riêng cho từng quy trình khi cần. | Một số nhóm tác vụ, đặc biệt là dịch hình ảnh và lồng tiếng giàu cảm xúc, có thể được cấp theo từng tài khoản. |
| Thông tin xác thực | Bạn có `AppKey` và `AppSecret`, được lưu trữ dưới dạng bí mật backend. | `AppSecret` tuyệt đối không được xuất hiện trong mã frontend, kho mã công khai, nhật ký, ảnh chụp màn hình hoặc prompt. |
| URL phương tiện | Các tệp nguồn có thể được truy cập công khai và duy trì ổn định trong suốt thời gian xử lý. | Các worker Weydub cần tải phương tiện nguồn xuống trước khi xử lý. |
| URL callback | Callback trong môi trường production chỉ trả về HTTP 200 cùng phần thân không rỗng sau khi dữ liệu đã được lưu trữ bền vững. | Tác vụ không đồng bộ có thể hoàn tất sau khi yêu cầu ban đầu đã trả về. |
| Lưu trữ kết quả | Dịch vụ của bạn lưu trữ ID công việc, ID tác vụ, trạng thái, URL kết quả và lỗi. | Các tài nguyên được tạo có thể chịu sự điều chỉnh của chính sách lưu giữ, vì vậy hãy nhanh chóng sao chép các tham chiếu bền vững. |

## Xác thực

Hầu hết các yêu cầu sử dụng các header:

```text
Content-Type: application/json
AppKey: $WEYDUB_APP_KEY
AppSign: md5(md5(request_body) + $WEYDUB_APP_SECRET)
```

Hãy ký chính xác phần thân JSON dạng thu gọn sẽ được gửi. Đọc [Xác thực và ký](./auth-and-signing.md) trước khi gỡ lỗi các trường hợp chữ ký không hợp lệ.

Ngoại lệ không cần ký:

```text
POST /v-w-c/enum/query2
```

Endpoint truy vấn enum được dùng cho các danh sách ngôn ngữ/trạng thái động và không yêu cầu ký.

## Danh mục endpoint

| Phương thức | Đường dẫn | Nhóm | Mục đích | Ghi chú về quyền truy cập |
| --- | --- | --- | --- | --- |
| `POST` | `/v-w-c/gateway/ve/work/free` | Video | Tạo hầu hết các tác vụ video: xóa phụ đề/văn bản, dịch video, trích xuất phụ đề OCR, trích xuất ASR và kết xuất phụ đề. | Yêu cầu quyền truy cập API cốt lõi. |
| `POST` | `/v-w-c/gateway/ve/work/status` | Video | Truy vấn trạng thái tác vụ video và các trường kết quả theo ID công việc. | Sử dụng sau khi tạo tác vụ hoặc làm phương án dự phòng cho callback. |
| `POST` | `/v-w-c/gateway/ve/work/list` | Video | Truy vấn lịch sử tác vụ video. | Hữu ích cho bảng điều khiển nội bộ và việc đối soát. |
| `POST` | `/v-w-c/gateway/ve/work/video/inpaint/redo` | Video | Thực hiện lại việc xóa văn bản/inpainting với các mặt nạ đã điều chỉnh. | Yêu cầu ngữ cảnh công việc/tác vụ hiện có. |
| `POST` | `/v-w-c/gateway/ve/work/translationPro/redo` | Video | Thực hiện lại việc dịch/lồng tiếng với phụ đề, thời gian hoặc cài đặt giọng nói đã điều chỉnh. | Yêu cầu ngữ cảnh tác vụ dịch hiện có. |
| `POST` | `/v-w-c/gateway/ve/work/voice/incorporate` | Video | Tạo các tác vụ nhân bản giọng nói và lồng tiếng giàu cảm xúc. | Xác nhận quyền được cấp cho tài khoản trước khi kết nối lưu lượng production. |
| `POST` | `/v-w-c/gateway/ve/image/translate` | Hình ảnh | Tạo tác vụ xóa văn bản khỏi hình ảnh hoặc dịch hình ảnh. | Có thể cần quyền sử dụng quy trình hình ảnh sau khi có quyền truy cập API miễn phí. |
| `POST` | `/v-w-c/gateway/ve/image/translate/redo` | Hình ảnh | Tạo lại tác vụ hình ảnh sau khi chỉnh sửa văn bản kết quả hoặc siêu dữ liệu về kiểu. | Yêu cầu ID tác vụ hình ảnh hiện có và JSON kết quả. |
| `POST` | `/v-w-c/ve/image/translate/task/launch` | Hình ảnh cũ/web | Tạo một tác vụ hình ảnh trong các luồng tài khoản hoặc web cũ. | Chỉ sử dụng khi đã xác nhận cho tài khoản đó. |
| `POST` | `/v-w-c/ve/image/translate/task/launch2` | Hình ảnh cũ/web | Tạo tác vụ hình ảnh theo lô trong các luồng tài khoản hoặc web cũ. | Xác nhận giới hạn theo lô và chính sách callback. |
| `POST` | `/v-w-c/ve/image/translate/task/query` | Hình ảnh cũ/web | Truy vấn một tác vụ hình ảnh trong các luồng tài khoản hoặc web cũ. | Thăm dò cho đến khi đạt trạng thái cuối trước khi đọc đầu ra. |
| `POST` | `/v-w-c/enum/query2` | Tiện ích | Truy vấn các enum động như trạng thái và danh sách ngôn ngữ. | Không yêu cầu chữ ký. |

## Tạo tác vụ video

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

Các quy trình phổ biến sử dụng endpoint này:

| Quy trình | Tín hiệu bắt buộc | Trang bắt đầu |
| --- | --- | --- |
| Xóa phụ đề/văn bản | `needChineseOcclude: 1`, `2` hoặc `3`; Advanced Lite/Pro thông qua `extraOptions.extra_inpaint_config` | [Xóa phụ đề và văn bản khỏi video](./video-subtitle-removal.md) |
| Dịch/lồng tiếng video | `needWanyin: 1`, `sourceLang`, `lang`, `wyTaskType` | [Dịch video](./video-translation.md) |
| Dịch văn bản trên màn hình | `needChineseOcclude: 11`, `sourceLang`, `lang`, `videoInpaintLang` | [Dịch video](./video-translation.md) |
| Trích xuất phụ đề OCR | `needChineseOcclude: 14`, `videoInpaintMasks`, `videoInpaintLang` | [Trích xuất phụ đề](./subtitle-extraction.md) |
| Trích xuất phụ đề ASR | `needWanyin: 1`, `wyTaskType: "ONLY_ASR"`, `wyNeedText: 0` | [Trích xuất phụ đề](./subtitle-extraction.md) |

Yêu cầu tối thiểu:

```json
{
  "urls": ["https://example.com/demo.mp4"],
  "needChineseOcclude": 1,
  "videoInpaintLang": "all",
  "callback": "https://your-domain.example/webhooks/weydub"
}
```

Các trường thường gặp trong phản hồi tạo tác vụ:

| Trường | Ý nghĩa |
| --- | --- |
| `idProject` | ID lô/dự án. |
| `dataList[].id` | ID công việc dùng để thăm dò trạng thái và đối chiếu callback. |
| `dataList[].url` | URL nguồn được chấp nhận để xử lý. |

## Truy vấn trạng thái video

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

```json
{
  "idWorks": [488026661]
}
```

Các giá trị trạng thái:

| `processStatus` | Ý nghĩa | Cách máy khách xử lý |
| --- | --- | --- |
| `< 1` | Đang xử lý. | Thăm dò lại sau hoặc chờ callback. |
| `1` | Thành công. | Đọc các URL kết quả và lưu trữ lâu dài. |
| `> 1` | Thất bại. | Hiển thị `errorDetail`. Các tác vụ thất bại không bị trừ tín dụng. |

Các tác vụ video thành công có thể bao gồm `videoUrl`, `coverUrl`, `srcSrtUrl`, `tgtSrtUrl`, `sourceVideoUrl`, `ttsMetaResult`, `wyVoiceParam` và siêu dữ liệu tác vụ.

## Tác vụ hình ảnh

Endpoint tạo công khai hiện tại:

```text
POST /v-w-c/gateway/ve/image/translate
```

Endpoint thực hiện lại:

```text
POST /v-w-c/gateway/ve/image/translate/redo
```

Yêu cầu dịch hình ảnh:

```json
{
  "srcLang": "en",
  "tgtLang": "es",
  "translateOn": 1,
  "synthesisOn": 1,
  "commodityFilterOn": 0,
  "downloadInfo": "{\"url\":\"https://example.com/product.png\",\"fileName\":\"product.png\",\"id\":12345,\"materialName\":\"product.png\"}",
  "app": "WD"
}
```

Yêu cầu xóa văn bản khỏi hình ảnh:

```json
{
  "srcLang": "en",
  "tgtLang": "en",
  "translateOn": 0,
  "synthesisOn": 1,
  "commodityFilterOn": 0,
  "downloadInfo": "{\"url\":\"https://example.com/banner.png\",\"fileName\":\"banner.png\",\"id\":12346,\"materialName\":\"banner.png\"}",
  "app": "WD"
}
```

Đọc [Dịch hình ảnh](./image-translation.md) trước khi triển khai tác vụ hình ảnh vì `downloadInfo`, `downloadInfos` và `result` khi thực hiện lại phải giữ nguyên định dạng chuỗi được nêu trong tài liệu.

## Truy vấn enum

```text
POST /v-w-c/enum/query2
```

Endpoint này không yêu cầu `AppSign`.

```json
{
  "text": "Lang"
}
```

Các tên enum phổ biến:

| `text` | Mục đích |
| --- | --- |
| `ProcessStatus` | Mã trạng thái tác vụ video. |
| `ImageTaskStatus` | Mã trạng thái tác vụ hình ảnh. |
| `sourceLang` | Danh sách ngôn ngữ nguồn cho dịch video. |
| `Lang` | Danh sách ngôn ngữ đích cho dịch video. |
| `musicRegion` | Danh sách khu vực dành cho nhạc thông minh, nếu được hỗ trợ. |

## Thanh toán, giới hạn và lưu giữ

| Chủ đề | Quy tắc |
| --- | --- |
| Thời lượng video | Giới hạn cứng hiện tại là 15 phút cho mỗi tệp video. Chia phương tiện dài hơn thành các phân đoạn ngắn hơn 15 phút, ví dụ 14:59, để tránh các vấn đề do làm tròn thời lượng. |
| Kích thước video | Giới hạn cứng hiện tại là 1000 MB cho mỗi tệp video. Nén các tệp quá lớn trước khi gửi. |
| Giới hạn hình ảnh | Tối đa `2000*2000 px`, tối đa `50 MB`, hỗ trợ các định dạng `png`, `jpeg`, `jpg`, `bmp`, `webp`; URL hình ảnh không được chứa ký tự tiếng Trung. |
| Đơn vị tính phí | Các quy trình video được tính phí theo đơn vị 30 giây. Video ngắn hơn 30 giây được tính là 30 giây. |
| Dịch vụ kết hợp | Việc kết hợp các dịch vụ như xóa văn bản và dịch giọng nói có thể làm cộng dồn chi phí. |
| Tác vụ thất bại | Các tác vụ đã thất bại ở trạng thái cuối cùng (`processStatus > 1`) không bị trừ tín dụng. |
| Lưu giữ | Dữ liệu do API tạo tuân theo các quy tắc lưu giữ trên web của Weydub. Theo mặc định, các tệp nguồn và đầu ra đã kết xuất trong 30 ngày gần nhất được lưu giữ. Hãy tải xuống và lưu trữ các tài nguyên quan trọng sau khi nhận callback. |
| CRF | CRF mặc định của video là `17`, gần như không suy hao về mặt thị giác đối với hầu hết hoạt động phân phối. Các giá trị thấp hơn như `15` hoặc `16` có thể khả dụng thông qua `extraOptions.write_options` và có thể làm phát sinh phí băng thông/lưu trữ. |

## Tóm tắt về callback

Truyền `callback` URL trong các yêu cầu tạo khi được hỗ trợ. Weydub gửi trực tiếp mục công việc đã hoàn tất đến máy chủ của bạn mà không có lớp bao bọc bên ngoài `code` / `msg` / `body` được dùng trong các phản hồi thăm dò.

Quy tắc xử lý callback:

- Xác minh `Callback-Sign` bằng phần thân thô của yêu cầu callback và `AppSecret` của bạn.
- Chỉ trả về HTTP 200 cùng phần thân không rỗng sau khi lưu trữ bền vững thành công.
- Thiết kế các trình xử lý có tính lũy đẳng theo ID công việc/tác vụ.
- Các callback thất bại đối với tác vụ được tạo trong vòng 24 giờ qua được thử lại khoảng 30 phút một lần.
- Nếu thao tác làm lại thay đổi nội dung video hoặc hình ảnh, URL đầu ra có thể thay đổi; hãy lưu lại URL mới nhất.

Đọc [Mô hình tác vụ bất đồng bộ](./async-task-model.md) để biết chi tiết về callback.

## Khắc phục sự cố

| Triệu chứng | Nguyên nhân có thể | Kiểm tra |
| --- | --- | --- |
| Lỗi chữ ký | Các byte của phần thân đã thay đổi sau khi ký, hoặc JSON dạng dễ đọc đã được ký nhưng JSON thu gọn được gửi đi. | Ghi log giá trị băm không bí mật của phần thân và so sánh các luồng mã thực hiện việc ký và gửi. |
| Đã tạo tác vụ nhưng không có kết quả | Quá trình xử lý bất đồng bộ vẫn đang chạy. | Thăm dò `/v-w-c/gateway/ve/work/status` hoặc chờ callback. |
| Thiếu URL đầu ra | Sai chế độ quy trình hoặc tác vụ chưa ở trạng thái kết thúc. | Xác nhận `processStatus === 1` và kiểm tra các trường đầu ra dành riêng cho quy trình. |
| Callback không được ghi nhận trong ứng dụng của bạn | Trình xử lý đã trả về trước khi hoàn tất lưu trữ bền vững, không xác minh được chữ ký hoặc không khớp với ID công việc. | Lưu tải trọng callback thô, so sánh `Callback-Sign` và đảm bảo các cập nhật có tính lũy đẳng. |
| Endpoint không khả dụng | Quyền sử dụng của tài khoản chưa được bật. | Xác nhận quyền truy cập API cho nhóm tác vụ cụ thể. |
| Lỗi giới hạn cứng của video | Video dài hơn 15 phút hoặc lớn hơn 1000 MB. | Chia thành các đoạn hoặc nén trước khi gửi. |
| Lỗi giới hạn cứng của hình ảnh | Hình ảnh vượt quá `2000*2000 px`, vượt quá `50 MB`, không được hỗ trợ hoặc URL chứa ký tự tiếng Trung. | Thay đổi kích thước, nén lại, đổi tên/mã hóa URL, sau đó thử lại. |

## Quy ước dành cho tác nhân

Các tác nhân tự động hóa nên:

- Tải [llms.txt](./llms.txt) và [Kỹ năng Weydub API](./weydub-api-skill.md).
- Sử dụng [Các kịch bản demo](./demo-scenarios.md) trước khi sử dụng nội dung đa phương tiện của khách hàng.
- Lưu thông tin xác thực trong các biến môi trường hoặc trình quản lý bí mật.
- Lưu trữ bền vững các ID trước khi báo cáo thành công cho người dùng.
- Mô hình hóa các tác vụ theo `submitted -> processing -> succeeded | failed | timed_out`.
- Không bao giờ để lộ `AppSecret` hoặc tự đặt ra các endpoint đã được bật.