Wan / HappyHorse：動画生成 API

HopBase は、Wan と HappyHorse の動画生成を公式 API の契約のまま、元のパスで提供します(Wan 3.0(万相 3.0)/ HappyHorse(快乐马) 1.1)。公式 SDK や HTTP で書いたコードは、base URL とキーだけを変更すれば移行できます。リクエストボディ、レスポンス形式、パスはすべて変わりません。

利用できるモデル

Wan 3.0 の長さは、自動の場合 -1 も指定できます。参照グループは参照画像最大 10 枚、参照動画最大 5 本、参照音声最大 5 本、ドキュメント 1 件、Web リンク 1 件です。

上記の正確な ID を使用してください。エイリアスは登録されておらず、未知のモデル名は拒否されます。wan3.0-video-prime、happyhorse-1.1-video-edit、および HappyHorse 1.0 系列は提供されていません。

wan3.0-video と happyhorse-1.1-* はそれぞれ別のプラン Wan 3.0 公式と HappyHorse 1.1 公式から提供されるため、キーはそのモデルのプランを含む場合にのみ到達できます。1 つのキーに両方のプランを含めることもできます。課金対象の処理を送信する前に、キーが到達できるモデルを GET /v1/models で確認してください。

料金の詳細と完全な仕様はモデルカードを参照してください:wan3.0-video、happyhorse-1.1-t2v、happyhorse-1.1-i2v、happyhorse-1.1-r2v。

リクエストパラメータ

すべてのリクエストは Authorization: Bearer sk-your-key と Content-Type: application/json を使用します。非同期用のヘッダーを追加で送信する必要はありません。タスクは常に非同期で実行されます。

{
  "model": "wan3.0-video",
  "input": { "prompt": "...", "media": [{ "type": "first_frame", "url": "..." }] },
  "parameters": { "resolution": "1080P", "duration": 5 }
}

HappyHorse は 2,501〜5,000 文字の中国語プロンプトをエラーなしで約 2,500 文字に切り詰めます。

input.media

file の対応形式:docx / doc / xlsx / xls / pptx / ppt / pdf / txt / key / pages / numbers / md。

Wan 3.0 では、先頭/末尾フレーム入力と参照グループ(reference_*、file、link)は 1 つのリクエスト内で排他です。

url には公開された絶対 http(s) URL または data: URI(base64)を指定できます。oss:// は拒否されます。そのオブジェクトはお客様自身のクラウドアカウントに属し、ゲートウェイからはアクセスできないためです。

種類・個数・組み合わせは送信時に検証し、ファイルサイズ・寸法・コーデック・長さ・ページ数は実行時にサービス側が検証します。JSON ボディ全体の上限は base64 を含めて 128 MiB のため、大きなメディアには URL を使用してください。

parameters

モデルが対応していないパラメータは無視されず 400 になります。ゲートウェイは resolution と duration を常に送信し(デフォルトは上表)、その他の省略したフィールドは送信しないため、サービス側のデフォルトが適用されます。

画像から動画を生成する例:

{
  "model": "happyhorse-1.1-i2v",
  "input": {
    "prompt": "The camera slowly pushes in, light drifting across the scene",
    "media": [{ "type": "first_frame", "url": "data:image/jpeg;base64,..." }]
  },
  "parameters": { "resolution": "720P", "duration": 5, "watermark": false }
}

レスポンス

送信レスポンス

送信に成功すると 200 が返り、HopBase のタスク ID は 公式のレスポンス形式のまま output.task_id(blt… の形式)に入っています。

{
  "output": {
    "task_id": "blt60x4115010d-d361-4bfc-b131-a382f1c400a5",
    "task_status": "PENDING"
  },
  "request_id": "..."
}

タスク照会のフィールド

GET /api/v1/tasks/{task_id} をポーリングします。

output.task_status(大文字)は PENDING → RUNNING → SUCCEEDED | FAILED と遷移し、終了状態はこの最後の 2 つのみです。それ以外の値は実行中として扱ってください。通常、1 本のクリップは 1〜5 分で完成し、長い Wan 3.0 のクリップはより時間がかかります。おおよそ 15 秒間隔でポーリングしてください。

処理中

{
  "output": {
    "task_id": "blt60x4115010d-d361-4bfc-b131-a382f1c400a5",
    "task_status": "RUNNING"
  },
  "model": "wan3.0-video"
}

成功

成功した場合、レスポンスには output.video_url に出力 URL が含まれます。

{
  "output": {
    "task_id": "blt60x4115010d-d361-4bfc-b131-a382f1c400a5",
    "task_status": "SUCCEEDED",
    "video_url": "https://api.hop-base.com/...",
    "orig_prompt": "..."
  },
  "usage": { "video_count": 1, "duration": 5, "SR": 1080, "output_video_duration": 5, "input_video_duration": 0, "ratio": "16:9", "billed_seconds": 5, "billing_bucket": "1080p", "cost": 4.08, "cost_usd": 0.6, "currency": "CNY" }
}

失敗

失敗したタスクは課金されません。code は常に TaskFailed のため、output.message で原因を判別してください(非同期タスクの失敗)。

{ "output": { "task_id": "blt60x...", "task_status": "FAILED", "code": "TaskFailed", "message": "..." } }

最小の例

BASE=https://api.hop-base.com
# 1. 送信
curl "$BASE/api/v1/services/aigc/video-generation/video-synthesis" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "input": {
      "prompt": "Aerial shot of snow mountains above clouds at sunrise"
    },
    "parameters": {
      "resolution": "1080P",
      "duration": 5,
      "ratio": "16:9"
    }
  }'

# 2. 返された output.task_id で約 15 秒ごとにポーリング
curl "$BASE/api/v1/tasks/blt-your-task-id" \
  -H "Authorization: Bearer sk-your-key"

注意事項

• 未知のフィールドと 2 つ目の JSON 値は、リクエストが送信される前に拒否されます。これは意図的な設計です。
• 参照メディアは HopBase ではなく公式側でダウンロードされます。データセンターの IP をブロックする画像ホスティングサービス(多くの無料画像 CDN がこれに該当します)を使うと送信の数分後にタスクが失敗するため、data: 埋め込み、またはお客様自身のオブジェクトストレージ / CDN の利用を推奨します。
• GET /api/v1/tasks/{task_id} をポーリングしてください。他のページの動画エンドポイントとは異なり、このパスには /api の前に /v1 が付かないことに注意してください。一覧取得のエンドポイントはないため、タスク ID はお客様側で管理してください。
• 作成から 2 時間経っても完了しないタスクは自動的に失敗扱いになり、これらのタスクを取り消すことはできません。
• output.video_url は api.hop-base.com 上の署名付き URL で、タスク完了時点から 24 時間有効です。
• 再度照会しても同じ URL が返るだけで有効期限は延長されず、期限切れの URL は 410 を返すため、この時間内に結果をダウンロードしてください。
• usage.ratio は実際に生成されたアスペクト比を返しますが、リクエストの列挙値ではなく生の寸法(例:1632:937)になることがあります。

よくあるエラーと対処

リクエストエラーは {"code":…,"message":…} を返します。

413 と 404 の message 原文:

request body exceeds the 128 MiB limit (received N bytes)
invalid task ID format
task not found            # 他ユーザーのキーでの照会もこれになる

それ以外のフィールド(OpenAI の size / n / image、Wan 2.x の img_url / negative_prompt / shot_type、media 内の余分なキー)は 400 を返します。

400 {"code":"InvalidParameter","message":"request body does not match the JSON contract: json: unknown field \"size\""}

タスクが失敗した場合は output.message に応じて対処します。

課金

タスクの送信時は「利用可能残高 − 実行中タスクの見積もり額 − 今回のリクエストの見積もり額」で判定され、不足している場合は code が insufficient_balance の 402 が返ります。見積もり額はタスク終了時に自動的に解放されます。すべての動画ファミリーに共通する詳細は動画の概要を参照してください。失敗したタスクは課金されません。

どちらの系列も、トークンではなく、解像度ティアによって異なる秒単位の単価で動画の長さに応じて課金します。

1 リクエストあたりの課金額 = usage.billed_seconds × usage.billing_bucket のレート

usage.SR は生成された動画の解像度ティア(480 / 720 / 1080)を示し、これがレートを決定します。同じティアでも、2 つの系列でレートは異なります。

課金対象となる長さの範囲は両者で異なります。

• wan3.0-video は出力だけでなく入力動画にも課金されます。課金対象の長さ = 入力動画の長さ + 出力動画の長さとなり、usage.input_video_duration が課金秒数に加算されます。リクエストに動画入力が含まれない場合は 0.0 になります。
• happyhorse-1.1-* の各モデルは出力のみに課金され、参照から動画を生成する場合、公式ドキュメントでは input_video_duration は固定で 0 と記載されています。

タスク終了後は、照会レスポンスのルートの usage に cost_usd(このタスクで残高から実際に差し引かれた米ドル額。課金なしの失敗は 0)、cost(同じ課金額の人民元額)、currency(常に CNY)も含まれます。

公式のリスト価格は料金ページに掲載されています。実際の適用レートはログイン後のモデルカタログに表示され、各リクエストの実際の課金額は利用量レコードで確認できます。

次のステップ

• 動画の概要:全動画モデル共通の残高の仮押さえ、タイムアウト、結果 URL
• MiniMax Hailuo(海螺) H3 動画 API
• エラーコードと再試行:非同期タスクの失敗を含む
• 同時実行数、タイムアウト、課金