動画生成の概要

動画生成は非同期タスクです。送信してタスク ID を受け取り、完了までポーリングし、有効期限内に出力動画をダウンロードします。

# 1. タスクを送信し、返ってきた task.id(vt… 形式)を控える
curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-5-260628",
    "content": [
      {
        "type": "text",
        "text": "日差しの草原を走るオレンジ色の猫、カメラが追う"
      }
    ]
  }'

# 2. task.status が completed になるまで 5 秒ごとに照会
#    出力 URL は task.outputs
curl https://api.hop-base.com/v1/video/tasks/vt-your-task-id \
  -H "Authorization: Bearer sk-your-key"

ファミリーを選ぶ

HopBase は 6 つの動画モデルファミリーを提供しています。すべて下記の同じ非同期フロー（送信 → ポーリング → ダウンロード）を使います。

価格列は各ファミリーで最も安い段階の開始価格です。すべての段階は各ファミリーのページとモデルカードを参照してください。Kling のリップシンクなど特殊モードは別価格です。実際の単価はログイン後のモデル広場で確認できます。

モデル ID とプラン

ファミリーごとに別のプランに属します。そのプランを含むキーで呼び出してください。

Kling にはモーションコントロール、アバター、リップシンクのモデルもあります。Kling のページを参照してください。各ファミリーの最小リクエストと結果の読み取り先は次のとおりです。

MiniMax でテキストのみから生成する場合は ratio も必須です。Kling の特殊モードは Kling のページを参照してください。Seedance の content[] には通常 text と image_url 要素を使います。

タスクの流れ：送信 → ポーリング → ダウンロード

動画モデルはすべてこの 3 ステップで呼び出します。

送信

HopBase はリクエストの model とキーに含まれるプランに基づいて、適切なファミリーにリクエストを振り分けます。リクエストボディとステータス値はファミリーごとに異なるため、各ファミリーのページに従ってください。送信成功時のステータスコードもファミリーごとに異なるため、2xx であれば送信成功として扱ってください。

キーが到達できるのは、含まれるプランのファミリーだけです。1 つのキーに複数の動画プランを含めることもできます。実際に使用するキーで GET /v1/models を呼び出し、レスポンスから完全なモデル ID を取得してください。モデル ID は完全一致で判定され、未知の名前は拒否されるだけで、近い名前へのルーティングは行われません。

ポーリング

送信時に返ったタスク ID で、成功か失敗になるまでステータスを照会します。Seedance、Grok Imagine、MiniMax、Kling にはタスク一覧もあります。

GET /v1/video/tasks?page=1&limit=20

Wan 3.0 と HappyHorse には一覧エンドポイントがないため、タスク ID は自分で保存してください。

ダウンロード

出力 URL は api.hop-base.com 上の署名付き URL で、タスク完了時点から有効期限が始まります。

再度照会しても同じ URL が返るだけで有効期限は延長されず、期限切れの URL は 410 を返します。早めにダウンロードして保存してください。

残高と課金

動画の送信時には「利用可能残高 − 実行中タスクの見積もり額 − 今回のリクエストの見積もり額」で判定されます。不足している場合は 402 が返り、code は insufficient_balance です。見積もり額はタスク終了時に自動的に解放されます。

Insufficient balance: available $X, reserved in flight $Y, this request estimated $Z
Insufficient quota: …    # 利用枠が設定された企業メンバーの枠が不足した場合、message はこれで始まる

Kling のリップシンクは見積もりができないため予約は行われません。

失敗した動画タスクは一切課金されません。タスクが終了すると、単一タスクの照会レスポンスのルートに usage も含まれます。

課金されずに失敗したタスクは 0 です。実行中はこのフィールドは返らず、単一タスクの照会ではタスクを作成したキーにのみ返されます。例の金額は説明用です。タスク一覧(タスク ID を付けない GET /v1/video/tasks)でも、終了済みの各タスクの usage に同じ cost・cost_usd・currency が含まれます。一覧はアカウント単位のため、同じアカウントの別のキーで作成したタスクにも金額が付きます。

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

失敗、タイムアウト、取り消し

送信の 2xx は受付を意味するだけです。生成に失敗しても照会は HTTP 200 で、失敗ステータスと英語の理由が返り、安定したエラーコードはありません。

Seedance は task.error.message を読み、他ファミリーは各ページを参照してください。コンソールの使用状況ページに失敗の分類と対処案が表示されます。詳しくはエラーを参照してください。

実行中タスクの時間上限はファミリーごとに異なるため、各ページを参照してください。Seedance のタスクは作成から 24 時間経っても終わらないと自動的に失敗になり、message は次のとおりです。

The task did not finish within 24 hours and was terminated automatically

動画タスクを取り消すことはできません。

参照素材の比較

各モデルが受け付ける参照素材の数:

• Seedance の最初/最後のフレームは ≤2 枚です。2.0 のフレームモードは参照モードと排他です。
• MiniMax-H3 のフレームと参照は排他です。H3-Max は reference_* を受け付けません。
• Wan 3.0 の文書と Web は各 ≤1 で排他、フレームと参照群も排他です。
• Kling の usage と特殊モードはモデルごとに Kling のページを参照してください。
• Grok Imagine の content はテキストのみです。

各モデルが受け付けるエンコード形式:

Seedance 2.0 の素材庫登録 URL は HTTP(S) のみです。MiniMax-H3-Max は形式を変えても種類制限は同じです。HappyHorse は動画/音声の参照を受け付けません。

Data URL は data:MIME;base64,内容 です。裸の base64 だけを渡すことはできません。

次のステップ

• Seedance: Seedance 2.0 / 2.5 のパラメータ、レスポンス、エラー
• Kling: Kling の動画パラメータとタスクモード
• API リファレンス：動画タスクの送信: 各ファミリーの完全なリクエストフィールド
• 同時実行数、タイムアウト、課金: 同時実行数の上限、タイムアウト、課金ルール
• エラーコードと再試行: 各エラーコードの意味と再試行の要否