WWeydub API

API ガイド

認証と署名

概要に戻るMarkdown ソースを表示

Weydub API リクエストでは、AppKey および AppSign ヘッダーを使用します。AppSecret はサーバー側にのみ保持してください。

リクエストの構造

項目値
ベース URLhttps://api.zhaoli.com
プロトコルHTTPS
メソッドドキュメントに記載されている API 呼び出しでは POST
エンコーディングUTF-8
コンテンツタイプapplication/json
リクエストボディJSON（安定した署名のためにコンパクトにシリアライズ）

ヘッダー

text
Content-Type: application/json
AppKey: your_app_key
AppSign: computed_signature

AppSecret がヘッダーまたはボディフィールドとして送信されることはありません。サーバー上で AppSign を計算するためにのみ使用されます。

署名式

text
AppSign = md5(md5(request_body) + AppSecret)

署名は、ネットワーク上で実際に送信する JSON ボディそのものから計算する必要があります。安定した署名を得るため、余分なスペースを含めずに JSON をシリアライズしてください。

エンドポイントで空のボディが許可されている場合は、実際に送信するバイト列に署名してください。ほとんどの統合では、ボディなしの呼び出しに対して {} を送信し、{} に署名することを推奨します。

署名不要のエンドポイント

enum エンドポイントには署名は不要です:

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

これを使用して、sourceLang、Lang、ProcessStatus、ImageTaskStatus などの動的な言語/ステータス列挙型を取得します。

Python 署名ヘルパー

python
import hashlib
import json


def signed_body_and_headers(payload: dict, app_key: str, app_secret: str):
    body = json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
    body_md5 = hashlib.md5(body.encode("utf-8")).hexdigest()
    app_sign = hashlib.md5((body_md5 + app_secret).encode("utf-8")).hexdigest()
    return body, {
        "Content-Type": "application/json",
        "AppKey": app_key,
        "AppSign": app_sign,
    }

Node 署名ヘルパー

js
import crypto from "node:crypto";

export function signedBodyAndHeaders(payload, appKey, appSecret) {
  const body = JSON.stringify(payload);
  const bodyMd5 = crypto.createHash("md5").update(body).digest("hex");
  const appSign = crypto.createHash("md5").update(bodyMd5 + appSecret).digest("hex");
  return {
    body,
    headers: {
      "Content-Type": "application/json",
      AppKey: appKey,
      AppSign: appSign,
    },
  };
}

cURL パターン

バックエンドで AppSign を計算してから、その計算に使用した本文をそのまま送信します。

bash
curl -X POST "https://api.zhaoli.com/v-w-c/gateway/ve/work/status" \
  -H "Content-Type: application/json" \
  -H "AppKey: $WEYDUB_APP_KEY" \
  -H "AppSign: $WEYDUB_APP_SIGN" \
  --data '{"idWorks":[488026661]}'

コールバック署名

Weydub がコールバックを送信する際、次の情報が含まれます。

text
Callback-Sign: computed_callback_signature

未加工のコールバックリクエスト本文を使用し、同じ式でコールバックを検証します。

text
expected = md5(md5(raw_callback_body) + AppSecret)

expected と Callback-Sign を比較します。検証に失敗したコールバックペイロードは拒否するか、隔離してください。

よくある間違い

  • 整形表示された JSON に署名しながら、コンパクトな JSON を送信する。
  • 署名後にペイロードを変更する。
  • 署名時と送信時で異なる文字列エスケープを使用する。
  • HTTP 経由で送信される最終的なバイト列ではなく、メモリ内のオブジェクトに署名する。
  • extraOptions、wyVoiceParam、videoInpaintMasks、downloadInfo、および再実行時の result は、外側の JSON 本文内でコンパクトな JSON 文字列のまま保持する必要がある場合があることを見落とす。
  • フロントエンドコードに認証情報を埋め込む。
  • AppSecret をブラウザー拡張機能やクライアント側アプリと共有したり、スクリーンショット、ログ、公開プロンプトに含めたりする。

エージェントのルール

  • 環境変数またはシークレットマネージャーから認証情報を読み込む。
  • AppSecret を決して出力しない。
  • 生成するサンプルファイルに認証情報を決して書き込まない。
  • 実行可能な例を作成する際は、プレースホルダーまたは環境変数を使用する。
  • 署名エラーをデバッグする際は、秘密情報を出力せずに、本文のバイト列と機密ではない本文ハッシュを比較する。
  • WebhookハンドラーではCallback-Signを検証する。