# เอกสารอ้างอิง API

เอกสารอ้างอิงนี้เป็นแหล่งข้อมูลแบบกระชับแห่งเดียวสำหรับนักพัฒนาและเอเจนต์ระบบอัตโนมัติ เพื่อค้นหาปลายทางของ Weydub API การตรวจสอบสิทธิ์เข้าถึง โครงสร้างคำขอ การทำงานแบบอะซิงโครนัส กฎการเรียกเก็บเงิน/การเก็บรักษา และตัวบ่งชี้สำหรับการแก้ไขปัญหา

## ข้อมูลพื้นฐานเกี่ยวกับคำขอ

| รายการ | ค่า |
| --- | --- |
| URL ฐาน | `https://api.zhaoli.com` |
| โปรโตคอล | HTTPS |
| เมธอด | `POST` สำหรับการเรียก API ที่ระบุไว้ในเอกสาร |
| การเข้ารหัส | UTF-8 |
| ชนิดเนื้อหา | `application/json` |
| การยืนยันตัวตน | ส่วนหัว `AppKey` และ `AppSign` ยกเว้นปลายทางที่ระบุไว้อย่างชัดเจนว่าไม่ต้องลงนาม |

ชื่อโครงสร้างพื้นฐานเดิมบางชื่ออาจยังปรากฏในแอสเซตเดโมสาธารณะหรือเส้นทางบัญชีรุ่นเก่า ให้ถือว่าเอกสาร Weydub API นี้เป็นข้อกำหนดปัจจุบันสำหรับผลิตภัณฑ์

## ก่อนเรียกใช้งาน

| สิ่งที่ต้องตรวจสอบ | สิ่งที่ต้องยืนยัน | เหตุใดจึงสำคัญ |
| --- | --- | --- |
| สิทธิ์เข้าถึง API | บัญชี Weydub ที่ลงชื่อเข้าใช้แล้วสามารถเปิดใช้สิทธิ์เข้าถึง API ได้ฟรี โปรดยืนยันสิทธิ์การใช้งานเฉพาะเวิร์กโฟลว์เมื่อจำเป็น | งานบางกลุ่ม โดยเฉพาะการแปลรูปภาพและการพากย์เสียงที่มีอารมณ์เข้มข้น อาจได้รับการจัดสรรสิทธิ์เป็นรายบัญชี |
| ข้อมูลประจำตัว | คุณมี `AppKey` และ `AppSecret` ซึ่งจัดเก็บเป็นข้อมูลลับของแบ็กเอนด์ | ต้องไม่ให้ `AppSecret` ปรากฏในโค้ดฟรอนต์เอนด์ ที่เก็บโค้ดสาธารณะ บันทึก ภาพหน้าจอ หรือพรอมต์โดยเด็ดขาด |
| URL สื่อ | ไฟล์ต้นฉบับเข้าถึงได้แบบสาธารณะและยังคงใช้งานได้ตลอดช่วงเวลาประมวลผล | เวิร์กเกอร์ของ Weydub ต้องดาวน์โหลดสื่อต้นฉบับก่อนประมวลผล |
| URL สำหรับ Callback | Callback ในระบบใช้งานจริงจะตอบกลับด้วย HTTP 200 พร้อมเนื้อหาที่ไม่ว่างเปล่า หลังจากจัดเก็บข้อมูลแบบถาวรแล้วเท่านั้น | งานแบบอะซิงโครนัสอาจเสร็จสมบูรณ์หลังจากคำขอเดิมได้รับการตอบกลับแล้ว |
| การจัดเก็บผลลัพธ์ | บริการของคุณจัดเก็บ ID งาน ID งานย่อย สถานะ URL ผลลัพธ์ และข้อผิดพลาด | แอสเซตที่สร้างขึ้นอาจอยู่ภายใต้นโยบายการเก็บรักษา จึงควรคัดลอกข้อมูลอ้างอิงไปเก็บไว้ในที่จัดเก็บถาวรโดยเร็ว |

## การยืนยันตัวตน

คำขอส่วนใหญ่ใช้ส่วนหัวต่อไปนี้:

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

ลงนามเนื้อหา JSON แบบกระชับที่ตรงกับเนื้อหาที่จะส่งทุกประการ อ่าน [การยืนยันตัวตนและการลงนาม](./auth-and-signing.md) ก่อนแก้ไขปัญหาการตรวจสอบลายเซ็นล้มเหลว

ข้อยกเว้นที่ไม่ต้องลงนาม:

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

ปลายทางสำหรับคิวรี enum ใช้สำหรับรายการภาษา/สถานะแบบไดนามิกและไม่ต้องลงนาม

## ดัชนีปลายทาง

| เมธอด | เส้นทาง | กลุ่ม | วัตถุประสงค์ | หมายเหตุด้านการเข้าถึง |
| --- | --- | --- | --- | --- |
| `POST` | `/v-w-c/gateway/ve/work/free` | วิดีโอ | สร้างงานวิดีโอส่วนใหญ่ ได้แก่ การลบคำบรรยาย/ข้อความ การแปลวิดีโอ การแยกคำบรรยายด้วย OCR การแยกข้อมูลด้วย ASR และการเรนเดอร์คำบรรยาย | ต้องมีสิทธิ์เข้าถึง API หลัก |
| `POST` | `/v-w-c/gateway/ve/work/status` | วิดีโอ | คิวรีสถานะงานวิดีโอและฟิลด์ผลลัพธ์ตาม ID งาน | ใช้หลังจากสร้างงานหรือเป็นทางเลือกสำรองของ Callback |
| `POST` | `/v-w-c/gateway/ve/work/list` | วิดีโอ | คิวรีงานวิดีโอย้อนหลัง | มีประโยชน์สำหรับแดชบอร์ดภายในและการกระทบยอด |
| `POST` | `/v-w-c/gateway/ve/work/video/inpaint/redo` | วิดีโอ | ทำการลบข้อความ/เติมเต็มภาพใหม่โดยปรับมาสก์ | ต้องมีบริบทของงาน/งานย่อยที่มีอยู่แล้ว |
| `POST` | `/v-w-c/gateway/ve/work/translationPro/redo` | วิดีโอ | ทำการแปล/พากย์เสียงใหม่โดยปรับคำบรรยาย การกำหนดเวลา หรือการตั้งค่าเสียง | ต้องมีบริบทของงานแปลที่มีอยู่แล้ว |
| `POST` | `/v-w-c/gateway/ve/work/voice/incorporate` | วิดีโอ | สร้างงานโคลนเสียงและพากย์เสียงที่มีอารมณ์เข้มข้น | ยืนยันสิทธิ์การใช้งานของบัญชีก่อนเชื่อมต่อทราฟฟิกของระบบใช้งานจริง |
| `POST` | `/v-w-c/gateway/ve/image/translate` | รูปภาพ | สร้างงานลบข้อความออกจากรูปภาพหรือแปลรูปภาพ | แม้เปิดใช้สิทธิ์เข้าถึง API ฟรีแล้ว ก็อาจยังต้องมีสิทธิ์การใช้งานเวิร์กโฟลว์รูปภาพ |
| `POST` | `/v-w-c/gateway/ve/image/translate/redo` | รูปภาพ | สร้างงานรูปภาพขึ้นใหม่หลังจากแก้ไขข้อความผลลัพธ์/ข้อมูลเมตาของสไตล์ | ต้องมี ID งานรูปภาพที่มีอยู่และ JSON ของผลลัพธ์ |
| `POST` | `/v-w-c/ve/image/translate/task/launch` | รูปภาพแบบเดิม/เว็บ | สร้างงานรูปภาพหนึ่งรายการในโฟลว์บัญชีรุ่นเก่าหรือโฟลว์เว็บ | ใช้เฉพาะเมื่อยืนยันแล้วว่าใช้ได้กับบัญชีนั้น |
| `POST` | `/v-w-c/ve/image/translate/task/launch2` | รูปภาพแบบเดิม/เว็บ | สร้างงานรูปภาพแบบกลุ่มในโฟลว์บัญชีรุ่นเก่าหรือโฟลว์เว็บ | ยืนยันขีดจำกัดของงานแบบกลุ่มและนโยบาย Callback |
| `POST` | `/v-w-c/ve/image/translate/task/query` | รูปภาพแบบเดิม/เว็บ | คิวรีงานรูปภาพหนึ่งรายการในโฟลว์บัญชีรุ่นเก่าหรือโฟลว์เว็บ | พอลจนกว่าจะถึงสถานะสิ้นสุดก่อนอ่านผลลัพธ์ |
| `POST` | `/v-w-c/enum/query2` | ยูทิลิตี | คิวรี enum แบบไดนามิก เช่น สถานะและรายการภาษา | ไม่ต้องใช้ลายเซ็น |

## สร้างงานวิดีโอ

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

เวิร์กโฟลว์ทั่วไปที่ใช้ปลายทางนี้:

| เวิร์กโฟลว์ | ตัวบ่งชี้ที่จำเป็น | หน้าเริ่มต้น |
| --- | --- | --- |
| การลบคำบรรยาย/ข้อความ | `needChineseOcclude: 1`, `2` หรือ `3`; Advanced Lite/Pro ผ่าน `extraOptions.extra_inpaint_config` | [การลบคำบรรยายและข้อความออกจากวิดีโอ](./video-subtitle-removal.md) |
| การแปล/พากย์เสียงวิดีโอ | `needWanyin: 1`, `sourceLang`, `lang`, `wyTaskType` | [การแปลวิดีโอ](./video-translation.md) |
| การแปลข้อความบนหน้าจอ | `needChineseOcclude: 11`, `sourceLang`, `lang`, `videoInpaintLang` | [การแปลวิดีโอ](./video-translation.md) |
| การแยกคำบรรยายด้วย OCR | `needChineseOcclude: 14`, `videoInpaintMasks`, `videoInpaintLang` | [การแยกคำบรรยาย](./subtitle-extraction.md) |
| การแยกคำบรรยายด้วย ASR | `needWanyin: 1`, `wyTaskType: "ONLY_ASR"`, `wyNeedText: 0` | [การแยกคำบรรยาย](./subtitle-extraction.md) |

คำขอขั้นต่ำ:

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

ฟิลด์การตอบกลับทั่วไปเมื่อสร้างงาน:

| ฟิลด์ | ความหมาย |
| --- | --- |
| `idProject` | ID ชุดงาน/โปรเจกต์ |
| `dataList[].id` | ID งานสำหรับการพอลสถานะและการจับคู่ Callback |
| `dataList[].url` | URL ต้นฉบับที่ระบบยอมรับให้ประมวลผล |

## คิวรีสถานะวิดีโอ

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

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

ค่าสถานะ:

| `processStatus` | ความหมาย | การดำเนินการของไคลเอนต์ |
| --- | --- | --- |
| `< 1` | กำลังประมวลผล | พอลอีกครั้งในภายหลังหรือรอ Callback |
| `1` | สำเร็จ | อ่าน URL ผลลัพธ์และจัดเก็บไว้อย่างถาวร |
| `> 1` | ล้มเหลว | แสดง `errorDetail` งานที่ล้มเหลวจะไม่ถูกหักเครดิต |

งานวิดีโอที่สำเร็จอาจประกอบด้วย `videoUrl`, `coverUrl`, `srcSrtUrl`, `tgtSrtUrl`, `sourceVideoUrl`, `ttsMetaResult`, `wyVoiceParam` และข้อมูลเมตาของงาน

## งานรูปภาพ

ปลายทางสาธารณะสำหรับสร้างงานในปัจจุบัน:

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

ปลายทางสำหรับดำเนินการซ้ำ:

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

คำขอแปลรูปภาพ:

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

คำขอลบข้อความออกจากรูปภาพ:

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

อ่าน [การแปลรูปภาพ](./image-translation.md) ก่อนพัฒนางานรูปภาพ เนื่องจาก `downloadInfo`, `downloadInfos` และ `result` สำหรับการทำซ้ำต้องคงโครงสร้างสตริงตามที่ระบุไว้ในเอกสาร

## การคิวรี Enum

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

ปลายทางนี้ไม่ต้องใช้ `AppSign`

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

ชื่อ enum ที่ใช้ทั่วไป:

| `text` | วัตถุประสงค์ |
| --- | --- |
| `ProcessStatus` | รหัสสถานะงานวิดีโอ |
| `ImageTaskStatus` | รหัสสถานะงานรูปภาพ |
| `sourceLang` | รายการภาษาต้นทางสำหรับการแปลวิดีโอ |
| `Lang` | รายการภาษาเป้าหมายสำหรับการแปลวิดีโอ |
| `musicRegion` | รายการภูมิภาคสำหรับเพลงอัจฉริยะในระบบที่รองรับ |

## การเรียกเก็บเงิน ขีดจำกัด และการเก็บรักษา

| หัวข้อ | กฎ |
| --- | --- |
| ระยะเวลาวิดีโอ | ขีดจำกัดสูงสุดแบบตายตัวในปัจจุบันคือ 15 นาทีต่อไฟล์วิดีโอ แบ่งสื่อที่ยาวกว่านั้นเป็นส่วนย่อยที่สั้นกว่า 15 นาที เช่น 14:59 เพื่อหลีกเลี่ยงปัญหาจากการปัดเศษระยะเวลา |
| ขนาดวิดีโอ | ขีดจำกัดสูงสุดแบบตายตัวในปัจจุบันคือ 1000 MB ต่อไฟล์วิดีโอ บีบอัดไฟล์ที่มีขนาดเกินกำหนดก่อนส่ง |
| ขีดจำกัดของรูปภาพ | สูงสุด `2000*2000 px`, สูงสุด `50 MB`, รองรับรูปแบบ `png`, `jpeg`, `jpg`, `bmp`, `webp`; URL รูปภาพต้องไม่มีอักขระภาษาจีน |
| หน่วยการเรียกเก็บเงิน | เวิร์กโฟลว์วิดีโอคิดค่าบริการเป็นหน่วยละ 30 วินาที วิดีโอที่สั้นกว่า 30 วินาทีจะนับเป็น 30 วินาที |
| บริการแบบรวม | การใช้บริการร่วมกัน เช่น การลบข้อความและการแปลเสียง อาจทำให้ค่าใช้จ่ายซ้อนทบกัน |
| ทาสก์ที่ล้มเหลว | ทาสก์ที่ล้มเหลวในสถานะสุดท้าย (`processStatus > 1`) จะไม่หักเครดิต |
| การเก็บรักษา | ข้อมูลที่ API สร้างขึ้นเป็นไปตามกฎการเก็บรักษาข้อมูลบนเว็บของ Weydub โดยค่าเริ่มต้น ระบบจะเก็บรักษาไฟล์ต้นฉบับและเอาต์พุตที่เรนเดอร์ในช่วง 30 วันที่ผ่านมาไว้ ดาวน์โหลดและจัดเก็บแอสเซ็ตสำคัญหลังได้รับ Callback |
| CRF | ค่า CRF เริ่มต้นของวิดีโอคือ `17` ซึ่งแทบไม่สูญเสียคุณภาพที่มองเห็นได้สำหรับการเผยแพร่ส่วนใหญ่ ค่าที่ต่ำกว่า เช่น `15` หรือ `16` อาจมีให้ใช้ผ่าน `extraOptions.write_options` และอาจมีค่าใช้จ่ายด้านแบนด์วิดท์/พื้นที่จัดเก็บเพิ่มเติม |

## สรุป Callback

ระบุ URL สำหรับ `callback` ในคำขอสร้างเมื่อระบบรองรับ Weydub จะส่งรายการงานที่เสร็จสมบูรณ์ไปยังเซิร์ฟเวอร์ของคุณโดยตรง โดยไม่มีโครงสร้างห่อหุ้ม `code` / `msg` / `body` ชั้นนอกที่ใช้ในการตอบกลับจากการโพล

กฎการจัดการ Callback:

- ตรวจสอบ `Callback-Sign` โดยใช้เนื้อหาคำขอ Callback แบบดิบและ `AppSecret` ของคุณ
- ส่ง HTTP 200 พร้อมเนื้อหาตอบกลับที่ไม่ว่างกลับไป หลังจากจัดเก็บข้อมูลลงในพื้นที่จัดเก็บถาวรสำเร็จแล้วเท่านั้น
- ทำให้ตัวจัดการทำงานแบบ idempotent โดยอิงตาม ID ของงาน/ทาสก์
- ระบบจะลองส่ง Callback ที่ล้มเหลวสำหรับทาสก์ที่สร้างขึ้นในช่วง 24 ชั่วโมงที่ผ่านมาอีกครั้งทุกประมาณ 30 นาที
- หากการทำใหม่เปลี่ยนเนื้อหาวิดีโอหรือรูปภาพ URL ของเอาต์พุตอาจเปลี่ยนแปลงได้ ให้จัดเก็บ URL ของผลลัพธ์ล่าสุด

อ่าน [โมเดลทาสก์แบบอะซิงโครนัส](./async-task-model.md) เพื่อดูรายละเอียดเกี่ยวกับ Callback

## การแก้ไขปัญหา

| อาการ | สาเหตุที่เป็นไปได้ | สิ่งที่ควรตรวจสอบ |
| --- | --- | --- |
| ข้อผิดพลาดเกี่ยวกับลายเซ็น | ไบต์ของเนื้อหาเปลี่ยนไปหลังการลงนาม หรือมีการลงนาม JSON แบบจัดรูปแบบให้อ่านง่าย แต่ส่ง JSON แบบย่อ | บันทึกค่าแฮชของเนื้อหาในลักษณะที่ไม่เปิดเผยความลับ และเปรียบเทียบเส้นทางโค้ดสำหรับการลงนามกับการส่ง |
| สร้างทาสก์แล้วแต่ไม่มีผลลัพธ์ | การประมวลผลแบบอะซิงโครนัสยังคงดำเนินอยู่ | โพล `/v-w-c/gateway/ve/work/status` หรือรอ Callback |
| ไม่มี URL ของเอาต์พุต | โหมดเวิร์กโฟลว์ไม่ถูกต้อง หรือทาสก์ยังไม่เข้าสู่สถานะสิ้นสุด | ยืนยัน `processStatus === 1` และตรวจสอบฟิลด์เอาต์พุตเฉพาะเวิร์กโฟลว์ |
| Callback ไม่ปรากฏในแอปของคุณ | ตัวจัดการตอบกลับก่อนจัดเก็บข้อมูลลงในพื้นที่จัดเก็บถาวร การตรวจสอบลายเซ็นล้มเหลว หรือ work ID ไม่ตรงกัน | จัดเก็บเพย์โหลดดิบของ Callback เปรียบเทียบ `Callback-Sign` และทำให้การอัปเดตเป็นแบบ idempotent |
| Endpoint ไม่พร้อมใช้งาน | ยังไม่ได้เปิดใช้สิทธิ์ให้บัญชี | ยืนยันสิทธิ์เข้าถึง API สำหรับกลุ่มทาสก์นั้น |
| ข้อผิดพลาดจากขีดจำกัดสูงสุดของวิดีโอ | วิดีโอยาวกว่า 15 นาที หรือมีขนาดใหญ่กว่า 1000 MB | แบ่งวิดีโอเป็นส่วนหรือบีบอัดก่อนส่ง |
| ข้อผิดพลาดจากขีดจำกัดสูงสุดของรูปภาพ | รูปภาพมีขนาดภาพเกิน `2000*2000 px` ขนาดไฟล์เกิน `50 MB` อยู่ในรูปแบบที่ไม่รองรับ หรือ URL มีอักขระภาษาจีน | ปรับขนาด บีบอัดใหม่ เปลี่ยนชื่อ/เข้ารหัส URL แล้วลองอีกครั้ง |

## ข้อกำหนดสำหรับ Agent

Agent สำหรับระบบอัตโนมัติควร:

- โหลด [llms.txt](./llms.txt) และ [Weydub API ทักษะ](./weydub-api-skill.md)
- ใช้ [สถานการณ์สาธิต](./demo-scenarios.md) ก่อนใช้สื่อของลูกค้า
- เก็บข้อมูลรับรองไว้ในตัวแปรสภาพแวดล้อมหรือระบบจัดการข้อมูลลับ
- จัดเก็บ ID อย่างถาวรก่อนรายงานความสำเร็จแก่ผู้ใช้
- สร้างแบบจำลองงานเป็น `submitted -> processing -> succeeded | failed | timed_out`
- ห้ามเปิดเผย `AppSecret` หรือสมมติขึ้นเองว่า Endpoint ใดเปิดใช้งานอยู่