# API 參考文件

本參考文件為開發人員與自動化代理程式提供一個集中且精簡的資訊來源，可查找 Weydub API 端點、存取權檢查、請求結構、非同步行為、計費／保留規則，以及疑難排解線索。

## 請求基本資訊

| 項目 | 值 |
| --- | --- |
| 基底 URL | `https://api.zhaoli.com` |
| 通訊協定 | HTTPS |
| 方法 | 本文件記載的 API 呼叫使用 `POST` |
| 編碼 | UTF-8 |
| 內容類型 | `application/json` |
| 身分驗證 | `AppKey` 與 `AppSign` 標頭，但明確標示為不需簽署的端點除外 |

某些舊有基礎架構名稱可能仍會出現在公開示範素材或舊版帳戶路徑中。請將此 Weydub API 文件視為目前產品對外的契約。

## 呼叫前須知

| 檢查項目 | 要確認的事項 | 為何重要 |
| --- | --- | --- |
| API 存取權 | 您已登入的 Weydub 帳戶可免費開通 API 存取權；需要時請確認特定工作流程的使用權限。 | 某些任務類別，尤其是影像翻譯與高情緒配音，可能會按帳戶個別開通。 |
| 憑證 | 您擁有 `AppKey` 與 `AppSecret`，並將其以後端機密的形式儲存。 | `AppSecret` 絕不能出現在前端程式碼、公開儲存庫、日誌、螢幕擷取畫面或提示詞中。 |
| 媒體 URL | 來源檔案在處理期間可公開存取且保持穩定。 | Weydub 工作程式需要在處理前下載來源媒體。 |
| 回呼 URL | 正式環境回呼僅在持久儲存完成後，才傳回 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
```

列舉查詢端點用於取得動態語言／狀態清單，不需要簽章。

## 端點索引

| 方法 | 路徑 | 類別 | 用途 | 存取備註 |
| --- | --- | --- | --- | --- |
| `POST` | `/v-w-c/gateway/ve/work/free` | 影片 | 建立大多數影片任務：字幕／文字移除、影片翻譯、OCR 字幕擷取、ASR 擷取，以及字幕算繪。 | 需要核心 API 存取權。 |
| `POST` | `/v-w-c/gateway/ve/work/status` | 影片 | 根據工作 ID 查詢影片任務狀態與結果欄位。 | 建立任務後使用，或作為回呼的備援方式。 |
| `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` | 影像（舊版／網頁） | 在舊版帳戶或網頁流程中建立批次影像任務。 | 請確認批次限制與回呼政策。 |
| `POST` | `/v-w-c/ve/image/translate/task/query` | 影像（舊版／網頁） | 在舊版帳戶或網頁流程中查詢單一影像任務。 | 請輪詢至最終狀態後再讀取輸出。 |
| `POST` | `/v-w-c/enum/query2` | 公用工具 | 查詢狀態與語言清單等動態列舉值。 | 無須簽章。 |

## 建立影片任務

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

使用此端點的常見工作流程：

| 工作流程 | 必要訊號 | 起始頁面 |
| --- | --- | --- |
| 字幕／文字移除 | `needChineseOcclude: 1`、`2` 或 `3`；透過 `extraOptions.extra_inpaint_config` 使用 Advanced Lite/Pro | [影片字幕與文字移除](./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。 |
| `dataList[].url` | 已接受處理的來源 URL。 |

## 查詢影片狀態

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

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

狀態值：

| `processStatus` | 說明 | 用戶端行為 |
| --- | --- | --- |
| `< 1` | 處理中。 | 稍後再輪詢，或等待回呼。 |
| `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`，都必須維持文件指定的字串形式。

## 列舉查詢

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

此端點不需要 `AppSign`。

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

常見列舉名稱：

| `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 天的來源檔案與算繪輸出。收到回呼後，請下載並儲存重要資產。 |
| CRF | 預設影片 CRF 為 `17`，對大多數發布用途而言，在視覺上無損。可透過 `extraOptions.write_options` 使用 `15` 或 `16` 等較低的值，但可能會產生額外的頻寬／儲存費用。 |

## 回呼摘要

如有支援，請在建立請求中傳入 `callback` URL。Weydub 會將已完成的工作項目直接傳送至您的伺服器，而不會包含輪詢回應所使用的外層 `code` / `msg` / `body` 包裝。

回呼處理規則：

- 使用原始回呼請求本文與您的 `AppSecret` 驗證 `Callback-Sign`。
- 只有在持久性儲存成功後，才回傳 HTTP 200，並加上任一非空白的回應本文。
- 依工作／任務 ID 讓處理常式具有冪等性。
- 針對最近 24 小時內建立的任務，失敗的回呼約每 30 分鐘重試一次。
- 如果重做會變更影片或圖片內容，輸出 URL 可能會改變；請儲存最新的結果 URL。

如需回呼詳細資訊，請參閱[非同步任務模型](./async-task-model.md)。

## 疑難排解

| 症狀 | 可能原因 | 檢查項目 |
| --- | --- | --- |
| 簽章錯誤 | 簽署後本文的位元組已變更，或簽署的是美化排版的 JSON，但傳送的是精簡格式的 JSON。 | 記錄非機密的本文雜湊值，並比較簽署與傳送的程式碼路徑。 |
| 任務已建立但沒有結果 | 非同步處理仍在進行中。 | 輪詢 `/v-w-c/gateway/ve/work/status` 或等待回呼。 |
| 缺少輸出 URL | 工作流程模式錯誤，或任務尚未進入最終狀態。 | 確認 `processStatus === 1`，並檢查工作流程專屬的輸出欄位。 |
| 您的應用程式未反映回呼結果 | 處理常式在持久性儲存前便已回傳、簽章驗證失敗，或工作 ID 不相符。 | 儲存原始回呼承載資料、比較 `Callback-Sign`，並讓更新具有冪等性。 |
| 端點無法使用 | 帳戶權限尚未啟用。 | 確認該特定任務系列的 API 存取權。 |
| 影片硬性限制錯誤 | 影片長度超過 15 分鐘，或大小超過 1000 MB。 | 送出前先分段或壓縮。 |
| 圖片硬性限制錯誤 | 圖片尺寸超過 `2000*2000 px`、檔案大小超過 `50 MB`、格式不受支援，或 URL 包含中文字元。 | 調整大小、重新壓縮、重新命名／編碼 URL，然後重試。 |

## 代理程式契約

自動化代理程式應：

- 載入 [llms.txt](./llms.txt) 與 [Weydub API 技能](./weydub-api-skill.md)。
- 處理客戶媒體前，先使用[示範情境](./demo-scenarios.md)。
- 將憑證保存在環境變數或機密管理工具中。
- 向使用者回報成功前，先持久化儲存 ID。
- 將作業建模為 `submitted -> processing -> succeeded | failed | timed_out`。
- 絕不公開 `AppSecret`，也不捏造已啟用的端點。