vidu-q3-ad reference-to-video API：curl、Python と実行可能なリクエスト

構築する内容

hiapi の非同期 /v1/tasks API 上で reference-to-video 呼び出しを1回行い、1〜7枚の商品静止画をネイティブ音声付きのショート動画広告に変換します。vidu-q3-ad/reference-to-video は Vidu Q3 の広告向けティアです。商品の参照画像をアップロードしてカメラワークの説明を書くと、モデルは3〜15秒のMP4を返します。スマート編集、カメラワーク、生成された効果音が組み込まれており、別途音声トラックを提供する必要はありません。

必要なのは POST を1回送信し、その後タスク完了までポーリング（またはコールバックを受信）してから MP4 をダウンロードするだけです。まず hiapi コンソール からキーを取得してください。以下の各リクエストは Authorization: Bearer sk-... を使用します。

そのままコピーすべき3項目：

• 送信エンドポイント：POST https://api.hiapi.ai/v1/tasks
• ポーリングエンドポイント：GET https://api.hiapi.ai/v1/tasks/{taskId}
• モデル ID：vidu-q3-ad/reference-to-video——スラッシュと -ad サフィックスはどちらも省略できません。vidu-q3-mix と vidu-q4-preview は別のエンドポイントです。

入力スキーマ（リアルタイムプローブで取得）

フィールド	必須	型	説明
prompt	はい	string	カメラワークの説明。番号で商品を参照します（例：「参照画像1の腕時計」）
reference_image_urls	はい	array、1〜7	商品静止画の公開 URL（サーバー側で取得されます）
duration	はい	integer、3〜15	秒数。整数である必要があります（4.5 は拒否されます）
size	いいえ	enum（10値）	同時にアスペクト比と 720/1080 ティアを決定します。デフォルトは 1280*720

バリデータは非常に厳格で、上記リスト以外のフィールドはすべて拒否されます。特筆すべき拒否パターンが2つあり、他の hiapi 動画モデルから移行した人が必ずつまずきます：

• aspect_ratio と resolution はどちらも拒否されます。他のほぼすべての hiapi 動画エンドポイントはこの2つのフィールドを使いますが、q3-ad は使いません。サイズは size でのみ制御します。
• reference_audio_urls も拒否されます。音声クリップを受け取れる Vidu Q4 の reference-to-video ティアとは異なり、q3-ad には音声入力がありません——BGM はネイティブ生成です。（これをどう確認したかは下の検証セクションを参照。）

size の選び方

size は固定セットからの width*height 文字列です。5つのアスペクト比 × 2つの品質ティアのグリッドとして読めます：

アスペクト比	720 ティア	1080 ティア
16:9 横	1280*720	1920*1080
9:16 縦	720*1280	1080*1920
1:1 スクエア	1280*1280	1808*1808
4:3	1280*960	1920*1440
3:4	960*1280	1440*1920

配信先に応じて行を選び（Reels と TikTok は縦の 720*1280 / 1080*1920、YouTube のインストリーム広告は横の行）、画質と予算のトレードオフで列を選びます。課金は出力秒数に基づき、ティアが1秒あたりの単価を決定します——詳細は料金を参照。最低課金は3秒のクリップです。

最小リクエスト（curl）

2ステップ：送信してからポーリングします。

# 1) 送信——taskId が返ります
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vidu-q3-ad/reference-to-video",
    "input": {
      "prompt": "参照画像1のチタン製スマートウォッチの商品広告：暗い反射する台座の上でゆっくりと回転し、硬い光の帯がブラッシュ仕上げのケースを左から右へ掃く。スクリーンは暗いまま、カメラは低いヒーローアングルを維持する。コマーシャルライティング、ハイコントラスト、マクロディテール。",
      "reference_image_urls": [
        "https://your-cdn.com/watch-front.png",
        "https://your-cdn.com/watch-side.png"
      ],
      "duration": 5,
      "size": "1280*720"
    }
  }'
# -> {"data":{"taskId":"..."}}

# 2) data.status が "success" または "fail" になるまでポーリング
curl -s https://api.hiapi.ai/v1/tasks/THE_TASK_ID \
  -H "Authorization: Bearer sk-your-key"
# 成功 -> data.status == "success"、data.output[0].url が MP4

参照画像の URL は公開アクセス可能でなければなりません——タスクはサーバー側でそれらを取得するため、localhost や数秒で失効する署名付き URL は使えません。

Python：送信、ポーリング、ダウンロード

import time
import requests  # または urllib/subprocess で依存ゼロを維持

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-your-key", "Content-Type": "application/json"}

def submit():
    payload = {
        "model": "vidu-q3-ad/reference-to-video",
        "input": {
            "prompt": "参照画像1のスニーカーの広告ショット、照らされたターンテーブルで回転、"
                      "ゆっくりとしたプッシュイン、柔らかなリムライト、商品ヒーローのフレーミング。",
            "reference_image_urls": ["https://your-cdn.com/sneaker.png"],
            "duration": 5,
            "size": "1080*1920",   # 縦 1080p、Reels / TikTok 向け
        },
    }
    body = requests.post(API, headers=HEADERS, json=payload, timeout=60).json()
    task_id = (body.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"submit rejected: {body}")   # 400 はここに来る
    return task_id

def wait(task_id, timeout_s=600, interval=5):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json().get("data") or {}
        status = data.get("status")
        if status == "success":
            return data["output"][0]["url"]
        if status == "fail":
            raise RuntimeError(f"task failed: {data.get('error')}")
        time.sleep(interval)
    raise TimeoutError(task_id)

url = wait(submit())
mp4 = requests.get(url, timeout=120).content   # すぐにダウンロード——出力 URL は失効する
open("ad.mp4", "wb").write(mp4)

Q3-ad のレンダリングは通常1〜2分で完了します。5秒のポーリング間隔で十分です。出力 URL は一時的（expireAt 付き）なので、タスク成功後すぐにバイトをダウンロードし、ページにホットリンクしないでください。

本番環境のパターン

ポーリングの代わりにコールバックを使う。 サーバーサイドのシナリオでは、トップレベルの callback を設定すればポーリングループを維持する必要がありません：

{
  "model": "vidu-q3-ad/reference-to-video",
  "input": { "prompt": "...", "reference_image_urls": ["..."], "duration": 5 },
  "callback": { "url": "https://your-app.com/hooks/hiapi", "when": "final" }
}

when は "final" のみサポートします——タスクが終端状態に入ったときにフックが1回発火し、そのリクエストボディは GET /v1/tasks/{taskId} が返すペイロードと同じです。フックは再試行される可能性があるため、taskId で重複排除し、配信が失われた場合に備えて低速なポーリングをフォールバックとして残してください。

HTTP ステータスコードではなくレスポンスボディで分岐する。 レンダリング失敗でも HTTP 200 が返ります。失敗情報は data.status == "fail" にあり、詳細は data.error にあります。リクエストレベルの拒否（フィールドエラー、キー欠落、未認証）のみが 4xx を使い、{"code":400,"error_code":"INVALID_REQUEST","message":"...","data":null} を返します。

冪等性。 送信ごとに新しい課金タスクが作成されるため、taskId を受け取った瞬間に保存し、リトライ時はその ID で再ポーリングしてください。単一のポーリングリクエストがタイムアウトしただけで再送信してはいけません。

何を検証したか

本番エンドポイントを無効な値でプローブしました。これらは検証段階で無料で拒否されます——タスクは作成されず、課金もされません（無効な値はレンダリング開始前に失敗するため、フィールドを漏らすより安全です）。実際のレスポンスがスキーマです：

• ほぼ空のリクエストボディ → reference_image_urls: missing required field ...; duration: missing required field ...。したがって prompt、reference_image_urls、duration はすべて必須です。
• duration: 99999 → maximum: got 99,999, want 15；duration: 1 → minimum: got 1, want 3；duration: 4.5 → got number, want integer。duration は3〜15の整数です。
• reference_image_urls に8件渡す → maxItems: got 8, want 7。上限は7です。
• size: "9000p" → value must be one of '1280*720', '1280*960', '1280*1280', '960*1280', '720*1280', '1920*1080', '1920*1440', '1808*1808', '1440*1920', '1080*1920'。
• aspect_ratio と resolution → どちらも additional properties ... not allowed を返します。これらは q3-ad のフィールドではありません。size を使ってください。
• reference_audio_urls を正しい形式の配列で渡す → additional properties 'reference_audio_urls' not allowed。（配列以外で渡すと、先に別のメディアチェック——「must be an array」——が発火し、誤解を招きます。このフィールドは本当にスキーマにありません。）このティアには音声参照入力はありません。音声はネイティブ生成です。

これは統合リファレンスであるため、画質に関する主張は含みません——本記事のために有料レンダリングは実行していません。成功時の output[0].url がどのようなものかについては、以下のモデルページがこのエンドポイント付属のサンプル（実際の音声トラック付き MP4）をホストしています。

関連ガイド

• Vidu Q3 Ad reference-to-video モデルページ——仕様、サンプル広告プロンプト、オンライン試用ボックス。
• Vidu Q4 reference-to-video API ガイド——より上位のティア：最大4K、1〜15枚の参照画像、そして q3-ad にはない reference_audio_urls 音声フィールド。
• Seedance 2.5 reference-to-video API ガイド——もう一つの reference-to-video エンドポイント。モデル比較に便利です。
• AI 動画カメラワークプロンプト——prompt フィールドで使うと良いカメラ言語。
• hiapi クイックスタート と 料金。

よくある質問

クリップを縦や横にするには？ aspect_ratio ではなく size で行います。縦は 720*1280 または 1080*1920、横は 1280*720 または 1920*1080 です。

ナレーションや音声参照を提供できますか？ このティアではできません——reference_audio_urls は拒否されます。Q3-ad はネイティブ音声を自身で生成します。参照クリップで音声を駆動する必要がある場合は、Vidu Q4 の reference-to-video ティアを使ってください。

商品画像は何枚送れますか？ 1〜7枚で、reference_image_urls に入れ、プロンプト内で番号で参照します（「参照画像2のボトル」）。

タスクが200を返したのに動画がありません——なぜ？ data.status を見てください。"fail" は HTTP 200 で返り、理由は data.error にあります。形式が不正なリクエストだけが 4xx になります。

費用はいくらですか？ 出力秒数で課金され、size ティア（720 級 vs 1080 級）が1秒あたりの単価を決定します。最低は3秒のクリップです。現在の料金は料金を参照してください。