使用ガイド
wan2.7-video/text-to-video@pro でショート動画を制作：エンドツーエンドの hiapi API ワークフロー
ショート動画の成否はイテレーションの速さにかかっています。大量の候補クリップが、縦型フォーマットで、音声付きで、しかも素早く必要です。本ガイドはまさにその点を中心に、hiapi 上の wan2.7-video/text-to-video@pro——Alibaba 通義万相 2.7 のテキスト・トゥ・ビデオモデルで、最大 1080P 出力、ネイティブ音声、クリップは最長 15 秒——を使って解説します。以下の各リクエスト構造、パラメータの境界、エラーメッセージはすべて執筆時点の本番 API に対して実際に実行して検証したものであり、文中に埋め込まれた 2 本のデモクリップも、示したコードからそのまま生成されたものです。
モデルが提供するもの
wan2.7-video/text-to-video@pro は hiapi の統一非同期タスクエンドポイント（/v1/tasks）経由で提供されます。本番スキーマに対して検証済みの主な特徴は以下の通りです：
- 出力：H.264 MP4、最大 1080P、ネイティブ AAC 音声トラック付き——モデルがプロンプトに応じて環境音や効果音を生成するため、別途の音声ステップは不要です。
- 長さ：1 クリップ 2〜15 秒（整数秒）。
- アスペクト比：
16:9、9:16、1:1、4:3、3:4——Shorts/Reels/TikTok 系のフォーマットに合わせた真の縦型 9:16 で、クロップは不要です。 - 課金：出力動画の秒数に応じた課金で、執筆時点では $0.167/秒から——5 秒の 1080P クリップで約 $0.84。バッチ生成の前に必ず料金ページで確認してください。
動画には同期モードがありません。タスクを作成し、完了までポーリングし、結果をダウンロードする必要があります。
最小の動作例（curl）
タスクを作成：
curl -X POST "https://api.hiapi.ai/v1/tasks" \
-H "Authorization: Bearer sk-YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "wan2.7-video/text-to-video@pro",
"input": {
"prompt": "マクロ撮影のスタジオショット：ロイヤルブルーのインクの一滴が透明な水に落ち、スローモーションで広がり、インクの筋が雲のような形に展開する。背景は明るい白のシームレスバック、クリアなハイキー照明、かすかな環境のハミング音",
"ratio": "16:9",
"resolution": "1080P",
"duration": 4
}
}'
レスポンス：
{"code": 200, "data": {"taskId": "tk-hiapi-01KWGGS29FDZ8NRJW49YRQZ65R"}, "message": "success"}
結果をポーリング：
curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWGGS29FDZ8NRJW49YRQZ65R" \
-H "Authorization: Bearer sk-YOUR_KEY"
レンダリング中は data.status が handling になり、完了すると success に変わって data.output[0].url に MP4 が入ります。このリクエストからそのまま生成されたクリップがこちらです：
⚠️ 出力 URL はexpireAt タイムスタンプ付きの一時リンクです。タスク成功後すぐにファイルを自分のストレージにダウンロードしてください——直接ホットリンクしたりデータベースに保存したりしないでください。
完全な入力スキーマ（本番 API に対して検証済み）
API は input を厳密に検証し、未知のフィールドを拒否します。以下が受け付けられるフィールドの完全な一覧です——どこかからコピーしたものではなく、エンドポイントを直接プローブして得たものです：
| フィールド | 型 | 制約 | 必須か |
|---|---|---|---|
prompt |
string | シーンの説明；生成される音声も同時に制御する | ✅ |
ratio |
string | 16:9、9:16、1:1、4:3、3:4 のいずれか |
任意 |
resolution |
string | 720P または 1080P |
任意 |
duration |
integer | 2〜15（秒） | 任意 |
negative_prompt |
string | 抑制したい内容（例：ウォーターマーク、文字のオーバーレイ） | 任意 |
seed |
integer | リトライ間で再現可能にする | 任意 |
watermark |
boolean | サービスプロバイダーのウォーターマークを切り替える | 任意 |
400 を避けるための落とし穴が 2 つあります：
- フィールド名は
ratioであり、aspect_ratioではありません——hiapi の画像モデルはaspect_ratioを使いますが、この動画モデルは使いません。aspect_ratioを送るとadditional properties 'aspect_ratio' not allowedが返ります。 durationはサーバー側で検証されます：duration: minimum: got 1, want 2とmaximum: got 999, want 15が、2〜15 の範囲を外れたときに得られる正確なエラーです。
エンドツーエンドの Python：プロンプトを入力し、公開可能な MP4 を出力
これが完全なワークフローです——作成、ポーリング、ダウンロード——SDK は不要で、requests だけを使います：
import time
import requests
API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY", "Content-Type": "application/json"}
def make_short(prompt: str, out_path: str, duration: int = 5,
ratio: str = "9:16", seed: int | None = None) -> str:
payload = {
"model": "wan2.7-video/text-to-video@pro",
"input": {
"prompt": prompt,
"ratio": ratio, # 9:16 = 縦型ショート動画
"resolution": "1080P",
"duration": duration, # 2..15 秒
"negative_prompt": "文字のオーバーレイ, ウォーターマーク, 歪んだ手",
},
}
if seed is not None:
payload["input"]["seed"] = seed
task_id = requests.post(API, headers=HEADERS, json=payload).json()["data"]["taskId"]
while True:
task = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
if task["status"] == "success":
break
if task["status"] == "fail":
raise RuntimeError(f"task failed: {task.get('error')}")
time.sleep(10)
video_url = task["output"][0]["url"] # 一時リンク——すぐにダウンロードすること
with open(out_path, "wb") as f:
f.write(requests.get(video_url, timeout=120).content)
return out_path
make_short(
"ゴールデンアワーの手持ち縦型ナイトマーケットのショット：屋台の店主が "
"炎が舞い上がる中華鍋でジュージュー音を立てる麺をあおり、湯気とオレンジ色の火花が "
"カメラに向かって渦を巻いて流れてくる。ネオンサインがボケた背景に柔らかなピンクとシアンでにじみ、浅い "
"被写界深度、躍動感のある手持ちドキュメンタリータッチ、ジュージューという音とパチパチという音を伴う",
"night-market.mp4",
duration=5,
seed=20260702,
)
この呼び出しから実際に生成されたクリップがこちらです——縦型 1080×1920、5 秒、ジュージューという音はプロンプトのテキストから生成されています：
私の実行では、4 秒の 16:9 クリップは約 3 分で完了し、5 秒の 9:16 クリップはもう少し長くかかりました——1 クリップあたり数分を見込み、約 10 秒ごとにポーリングし、エンドポイントを叩きすぎないようにしてください。
ショート動画のプロンプトのコツ：動きも音声もプロンプトが決める
スキーマにはカメラ制御やモーションのパラメータがありません——動き、テンポ、音に関するすべてはプロンプトの言葉で導きます。私のテストで効果があった方法：
- カメラの挙動を明示的に名指す：例えば "handheld"（手持ち）、"slow push-in"（ゆっくり寄る）、"macro"（マクロ）、"shallow depth of field"（浅い被写界深度）。ナイトマーケットのクリップのドキュメンタリー風の揺れは、完全に "handheld" という一語から来ています。
- 欲しい音声を描写する：モデルはプロンプトに応じて音を生成します。"sizzling and crackling sounds"（ジュージューという音とパチパチという音）も "gentle ambient hum"（かすかな環境のハミング音）も、出力音声トラックに現れました。
- フックを先頭に置く：ショート動画では最初の 1 秒がすべてを決めます。最も躍動的な要素（炎で鍋をあおる、インクが水に落ちる）をプロンプト記述の冒頭に置きましょう。
negative_promptを防御的に使う："text overlay, watermark, distorted hands"（文字のオーバーレイ、ウォーターマーク、歪んだ手）は、メインプロンプトに影響を与えずに最もよくある瑕疵をきれいにできます。- イテレーション時は
seedを固定する：seed を固定し、一度にプロンプトの一フレーズだけを変えて、そのフレーズが実際に何をしているかを観察しましょう。
最初のフレームを制御したい？ ならばイメージ・トゥ・ビデオ版を使う
ワークフローが設計済みのキーフレームから始まる場合——製品画像、ブランドスタイルの最初のフレーム——テキスト・トゥ・ビデオは画像入力を受け付けません。姉妹モデルの wan2.7-video/image-to-video@pro なら可能です：{"url": "...", "type": "image"} オブジェクトからなる media 配列を受け付け、同じ prompt / resolution / duration フィールドと組み合わせて、提供したフレームを一から生成するのではなくアニメーション化します。同じタスクベースのフローで、同じ秒数課金です。実用的なパイプラインとしては、画像モデルで静止画を生成し、レビューを通った後に承認済みのフレームをアニメーション化する——そうすれば動画生成の費用は承認済みのフレームにだけかかります。
よくあるエラーとその実際の意味
invalid input: prompt: missing required field "prompt"——promptが唯一の必須フィールドです。invalid input: ratio: value must be one of '16:9', '9:16', '1:1', '4:3', '3:4'——モデルがサポートしないアスペクト比を渡した（または打ち間違えた）ということです。invalid input: <root>: additional properties '...' not allowed——未知のフィールドです。スキーマは厳格なので、上の表を確認してください。status: "fail"とTASK_FAILED——タスクが作成後に失敗しました。新しいタスクを作成してください（再現性を保つためseedを再利用します）。- ダウンロードしたファイルが小さい、または再生できない——期限切れの出力 URL を取得した可能性が高いです。
expireAtを再確認し、success後すぐにダウンロードしてください。
まとめ
1 回の POST、1 つのポーリングループ、1 回のダウンロード——テキストプロンプトから公開可能な音声付き縦型 MP4 までの距離はこれだけです。ショート動画のパイプラインを構築するなら、コンソールで API キーを取得し、上の Python 関数から始めて、モデルカタログの残りを眺めてみてください——同じ /v1/tasks パターン（seedance-2.0-fast ガイドで示している通り）がプラットフォーム上のすべての動画モデルに当てはまるので、後でモデルを変えるのは 1 行の変更で済みます。
