# APIリファレンス

このリファレンスでは、開発者や自動化エージェントが、Weydub APIエンドポイント、アクセス確認、リクエスト形式、非同期動作、課金と保持に関するルール、トラブルシューティングの手がかりを1か所で簡潔に確認できます。

## リクエストの基本

| 項目 | 値 |
| --- | --- |
| ベース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
```

enumクエリエンドポイントは、動的な言語/ステータス一覧に使用され、署名は不要です。

## エンドポイント一覧

| メソッド | パス | ファミリー | 用途 | アクセスに関する注記 |
| --- | --- | --- | --- | --- |
| `POST` | `/v-w-c/gateway/ve/work/free` | 動画 | 大半の動画タスクを作成: 字幕/テキストの除去、動画翻訳、OCR字幕抽出、ASR抽出、字幕レンダリング。 | コア API アクセスが必要です。 |
| `POST` | `/v-w-c/gateway/ve/work/status` | 動画 | work IDを使用して、動画タスクのステータスと結果フィールドを照会。 | タスク作成後、またはコールバックのフォールバックとして使用。 |
| `POST` | `/v-w-c/gateway/ve/work/list` | 動画 | 過去の動画タスクを照会。 | 内部ダッシュボードや照合に有用。 |
| `POST` | `/v-w-c/gateway/ve/work/video/inpaint/redo` | 動画 | 調整済みマスクを使用して、テキスト除去/インペインティングを再実行。 | 既存のwork/taskコンテキストが必要。 |
| `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` | 画像（レガシー/Web） | 旧アカウントまたはWebフローで単一の画像タスクを作成。 | アカウントで利用できることを確認した場合のみ使用。 |
| `POST` | `/v-w-c/ve/image/translate/task/launch2` | 画像（レガシー/Web） | 旧アカウントまたはWebフローでバッチ画像タスクを作成。 | バッチの制限とコールバックポリシーを確認。 |
| `POST` | `/v-w-c/ve/image/translate/task/query` | 画像（レガシー/Web） | 旧アカウントまたはWebフローで1件の画像タスクを照会。 | 出力を読み取る前に、終端ステータスになるまでポーリング。 |
| `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。 |
| `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`では、ドキュメントに記載された文字列形式を維持する必要があります。

## Enumクエリ

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

このエンドポイントでは`AppSign`は必要ありません。

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

一般的なEnum名:

| `text` | 用途 |
| --- | --- |
| `ProcessStatus` | 動画タスクのステータスコード。 |
| `ImageTaskStatus` | 画像タスクのステータスコード。 |
| `sourceLang` | 動画翻訳の翻訳元言語リスト。 |
| `Lang` | 動画翻訳の翻訳先言語リスト。 |
| `musicRegion` | 対応時に利用できるスマートミュージック地域リスト。 |

## 課金、制限、保持

| 項目 | ルール |
| --- | --- |
| 動画の長さ | 現在の厳格な上限は、動画ファイル1つあたり15分です。長いメディアは、再生時間の丸め誤差を避けるため、15分未満のセグメント（例：14:59）に分割してください。 |
| 動画サイズ | 現在の厳格な上限は、動画ファイル1つあたり1000 MBです。送信前にサイズ超過ファイルを圧縮してください。 |
| 画像の制限 | 最大`2000*2000 px`、最大`50 MB`、対応形式は`png`、`jpeg`、`jpg`、`bmp`、`webp`です。画像URLに中国語の文字を含めてはなりません。 |
| 課金単位 | 動画ワークフローは30秒単位で課金されます。30秒未満の動画は30秒としてカウントされます。 |
| 複合サービス | テキスト削除や音声翻訳などのサービスを組み合わせると、費用が累積する場合があります。 |
| 失敗したタスク | 最終的に失敗したタスク（`processStatus > 1`）では、クレジットは消費されません。 |
| 保持 | APIで生成されたデータには、Weydubのウェブ保持ルールが適用されます。デフォルトでは、直近30日間のソースファイルとレンダリング済み出力が保持されます。コールバック後に重要なアセットをダウンロードして保存してください。 |
| CRF | デフォルトの動画CRFは`17`で、ほとんどの配信用途で視覚的に無劣化です。`15`や`16`などの低い値は、`extraOptions.write_options`経由で利用できる場合があり、帯域幅やストレージの料金が追加で発生する可能性があります。 |

## コールバックの概要

対応している場合は、作成リクエストに`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分を超えているか、1000MBを超えています。 | 送信前に分割または圧縮してください。 |
| 画像のハードリミットエラー | 画像が `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` を決して公開せず、有効化済みのエンドポイントを捏造しない。