チュートリアル
muse-video-1.0 画像から動画生成 API チュートリアル:curl と Python Requests
このページの内容
muse-video-1.0 画像から動画生成エンドポイントが要求するもの
muse-video-1.0/image-to-video エンドポイントは、単一の静止画像を短い動画に変換します。最初のコードを書く前にリクエストの構造を理解しておけば、正しいリクエストペイロードを一度で組み立てられます。
高レベルで見ると、1回の呼び出しは4つの側面を含みます:
- モデルルーティング —— HiAPI 統合 API を通じて
muse-video-1.0/image-to-videoでモデルを指定します。 - 入力画像 —— アニメーションの起点となる静止フレーム。これは必須のクリエイティブ入力です。
- 生成オプション —— 音声の挙動と長さのティア。これらはソース素材ではなく出力特性を形作ります。
- 非同期実行 —— 生成はインラインで完成動画を返しません。まずタスクを送信し、その後ポーリングして結果を取得します。
最後の点は開発者が最も見落としがちです。レンダリングには時間がかかるため、このエンドポイントはタスクベースです:最初の呼び出しはリクエストを確認してハンドルを返し、その後ステータスクエリでフォローアップして動画の準備が整うまで待ちます。ポーリングを後付けするのではなく、最初からこの2段階フローを前提にクライアントを設計してください。
リクエストボディ自体は JSON です。フィールドはグループ化された構造をとります:画像は独立した input ブロックにあり、音声と長さはそれと並列に生成設定として配置されます。このメンタルモデル —— 入力、オプション、タスクライフサイクルの分離 —— を保てば、このチュートリアルの残りは straightforward です。
認証
すべてのリクエストは HiAPI API キーで認証され、bearer 資格情報として Authorization ヘッダーに含めます。キーは機密として扱い、共有する可能性のあるスクリプトにハードコードせず、環境変数から読み込んでください。
export HIAPI_API_KEY="your_api_key_here"
キーをエクスポートすれば、リクエストを理解する準備は整いました。次のセクションではリクエストペイロードを段階的に構築します。
最初のフレーム画像を準備してアップロードする
最初のフレーム画像はタスク全体のクリエイティブなアンカーです。提供した内容がゼロフレームとなり、モデルはそこから前方にアニメーション化します。これを正しく行うことで生成回数の無駄を避けられます。
ソースフレームに関する実用的なアドバイス
- 明確で高品質な静止画を使用する。 単一フレーム画像として自然に読める内容が、モデルに最良の出発点を提供します。
- 目標出力に合ったアスペクト比を選ぶ。 ワイドな横長画像と縦長の長い画像ではまったく異なる構図になるため、アップロード前に方向を決めておくべきです。
- 強いモーションブラーや不明瞭な被写体を避ける。 視覚的に安定した静止画ほど予測可能なアニメーションを生成します。
- ファイルがリクエスト時にアクセス可能であることを確認する。 URL を渡すにせよエンコードされたペイロードを渡すにせよ、タスク送信の瞬間にその参照が到達可能であることを保証してください。
画像がリクエストに入る方法
画像は JSON リクエストボディの input ブロックで提供されます。最小限の画像入力は次のようになります:
{
"input": {
"image": "https://your-host.example/first-frame.jpg"
}
}
ソース画像がローカルにある場合は、リクエストからアクセス可能な場所にホストするか、エンドポイントが受け入れるエンコード形式で渡してください。重要なルールは:input.image の値はタスク作成時に実際の画像内容に解決されなければならない —— 破損または期限切れのリンクはポーリング時ではなく送信時に失敗し、これは実際に有用な早期シグナルです。
生成前に検証する
簡単な健全性チェックは価値があります:ブラウザで画像 URL を開き、読み込めることを確認し、次にサイズが意図した出力に適していることを確認します。ここで2秒かけて確認すれば、後で混乱するデバッグを避けられます。
最初のフレームが準備できてアクセス可能になったら、生成オプションの処理に進めます。
音声パラメータと長さティアを設定する
画像に加えて、muse-video-1.0/image-to-video は出力特性を変える2種類のオプションを提供します:音声の挙動と長さです。
音声パラメータ
音声はリクエストボディ内の1つのフィールドとして表され、input と並列に配置されます。呼び出し前に意図を決めてください:
- 無音出力 —— 後で独自のサウンドトラックを追加する予定、またはクリーンなビデオトラックが必要な場合は音声をオフにします。
- 音声を有効化 —— クリップに音声を含めるべき場合は音声をオンにします。デフォルト値を仮定せず、リクエストペイロードでこのオプションを明示的に確認してください。
音声処理は後処理ステップではなくリクエスト自体の属性であるため、スケールアップ前に確定しておく価値があります。パイプラインが無音クリップと音声付きクリップを混在させる場合は、意図しない事態を避けるため、その選択をクライアントコード内の明示的なパラメータとしてモデル化してください。
長さティア
このエンドポイントではクリップの長さティアを選択できます。長さは意図的なクリエイティブかつコストの決定として扱ってください:
- 短いティア は迅速なプレビュー、ソーシャルクリップ、絵コンテテストに適しており、多くのソース画像で素早くフィードバックを得たい場合に便利です。
- 長いティア はアニメーションにより多くの発展の余地を与え、キービジュアルショットや呼吸感が必要なシーケンスに適しています。
長さは出力秒数で課金されるため、選択したティアが直接コストに影響します。単なる迅速な視覚チェックのために長いクリップをレンダリングする利点はありません —— 最初のフレームを反復する間は短いティアを使い、勝ち残った設定をより長いティアに昇格させてください。
これらのオプションを一緒に組み立てる
JSON では、音声と長さの設定は input ブロックと並列になります:
{
"input": {
"image": "https://your-host.example/first-frame.jpg"
},
"audio": true,
"duration": "<duration_tier>"
}
推測値ではなく、エンドポイントドキュメントに記載された正確なティア識別子を使用してください。次のセクションでこれを実行可能なリクエストにします。
動作する curl リクエスト
リクエストペイロードが組み立てられたら、以下が初期送信の curl コマンドです。これはタスクを作成し、完成動画は返しません。
curl -X POST "https://api.hiapi.ai/v1/muse-video-1.0/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": {
"image": "https://your-host.example/first-frame.jpg"
},
"audio": true,
"duration": "<duration_tier>"
}'
このコマンドに関するいくつかの注意点:
- URL がモデルを名前で指定します。 モデルごとに個別のクライアントを用意する必要はありません。パスがすでに
muse-video-1.0/image-to-videoを識別しています。 - ヘッダーがキーを運びます。
$HIAPI_API_KEYは先にエクスポートした環境変数から展開されるため、キーがスクリプト自体に現れることはありません。 - リクエストボディは先ほど構築したペイロードです。 画像 URL、音声フラグ、長さティアが一緒に渡されます。
レスポンスはタスク確認です:作成したタスクの識別子が含まれます。その識別子をコピーしてください —— ポーリングステップで使用します。単に探索しているだけなら、JSON フォーマッタでレスポンスを整形すると job ID を見つけやすくなります。
送信が失敗した場合、エラーは通常即座かつ具体的です:JSON ボディの形式エラー、画像参照の欠落、または認識できないオプション値。この迅速なフィードバックループこそ、ポーリングを組み込む前に送信を単独でテストする価値がある理由です。
同じリクエストを Python で実装する
ほとんどの統合は最終的に Python に落ち着くため、標準ライブラリを使用した同等の送信を示します —— サードパーティ SDK は不要です。
import json
import os
import urllib.request
API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/muse-video-1.0/image-to-video"
payload = {
"input": {
"image": "https://your-host.example/first-frame.jpg"
},
"audio": True,
"duration": "<duration_tier>",
}
request = urllib.request.Request(
ENDPOINT,
data=json.dumps(payload).encode("utf-8"),
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(request) as response:
result = json.loads(response.read().decode("utf-8"))
job_id = result["id"]
print("Submitted job:", job_id)
このスクリプトは curl 呼び出しにフィールドごとに対応しています。身につける価値のある習慣がいくつかあります:
- リクエストペイロードを辞書に保持する。 Python 辞書として構築すれば、同じ構造を任意の HTTP ライブラリ ——
urllib、requests、または非同期クライアント —— にロジックを書き直すことなく渡せます。 - キーを環境から読み取る。
os.environにより資格情報がソース管理から離れます。 - レスポンスを即座に JSON として解析する。 job ID を名前付き変数に抽出すると、ポーリングステップがより明確に読めます。
requests ライブラリを好む場合、唯一の変更はトランスポート層の交換です:同じ payload 辞書を構築し、ヘッダーセットで送信し、レスポンスに対して .json() を呼び出します。エンドポイント、ヘッダー、ボディは完全に同一のままです。
タスクが送信され識別子が取得できたら、残る作業は正しい方法で結果を待つことです。
非同期タスクをポーリングして動画を取得する
動画生成は即時ではないため、このエンドポイントは非同期です。送信後、タスクステータスをポーリングしてレンダリングがいつ完了するかを把握し、その後出力を取得します。
ポーリングループ
堅牢なループは3つのことを行います:チェック間で待機し、無限に実行しないよう上限を設定し、「処理中」、「完了」、「失敗」を区別します。
import time
import urllib.request
STATUS_ENDPOINT = "https://api.hiapi.ai/v1/jobs/{job_id}"
def wait_for_video(job_id, max_attempts=60, interval=5):
for attempt in range(max_attempts):
url = STATUS_ENDPOINT.format(job_id=job_id)
request = urllib.request.Request(
url,
headers={"Authorization": f"Bearer {API_KEY}"},
)
with urllib.request.urlopen(request) as response:
status = json.loads(response.read().decode("utf-8"))
state = status.get("status")
if state == "succeeded":
return status.get("output")
if state == "failed":
raise RuntimeError(f"Job {job_id} failed: {status}")
time.sleep(interval)
raise TimeoutError(f"Job {job_id} did not finish in time")
本番環境の設計ポイント
- 合理的な間隔を使用する。 5秒は妥当な開始点です。ステータスエンドポイントを連打しないでください。
- 常に試行回数を制限する。
max_attemptsの上限により、無限待機がログとアラート可能な明確なエラーに変わります。 - 失敗状態を明示的に処理する。 失敗したタスクには診断情報が含まれます —— 同じ入力を静かに再試行するのではなく、それを表面化させてください。
- job ID を永続化する。 プロセスが再起動しても、ポーリングを再開でき、再生成の費用を払わずに済みます。
出力を取得する
タスクが成功すると、ステータスレスポンスに完成動画の出力参照が含まれます。長期間有効なリンクに依存せず、速やかに独自のストレージにダウンロードしてください。ファイルをローカルまたはバケットに保持した時点で、パイプラインの観点から生成は完了です。
これがライフサイクル全体です:送信、ポーリング、取得。コード内で2つのフェーズを分離すれば、各フェーズはシンプルに保たれます。
よくある落とし穴とデバッグのヒント
muse-video-1.0/image-to-video を使用する際の統合問題のほとんどは、少数のカテゴリに分類できます。問題が発生したときに確認すべき内容は以下のとおりです。
画像入力の問題
- 画像参照が到達不能。 URL が認証を必要としたり期限切れだったりすると、タスクは送信時に失敗します。リクエスト中はフレームを公開読み取り可能な場所にホストしてください。
- アスペクト比の不一致。 縦長の静止画を横長出力に強制すると、不格好なクロップや黒帯が発生します。ソースの方向を目標に合わせて設定してください。
- 内容の誤り。 実際のフレームではなくサムネイルやプレースホルダーを指してしまうことはよくあります。URL が意図した画像を開くことを確認してください。
パラメータの誤り
- 長さの値を推測する。 エンドポイントドキュメントに正確に記載されたティア識別子を使用してください。認識できない値は一般的な拒否理由です。
- 音声フラグを忘れる。 音声設定を省略しながら音声を期待すると、無音クリップが得られる可能性があります。音声が必要かどうかを明示してください。
- トップレベルフィールドと input フィールドを混同する。 画像は
inputの内部に属します。音声と長さはinputの兄弟であり、子ではありません。ネストの誤りは混乱を招く検証メッセージを生みます。
ポーリングの誤り
- 送信を完了と見なす。 最初のレスポンスは確認にすぎず、動画ではありません。常にステータスチェックでフォローアップしてください。
- 無制限のポーリング。 上限のないループはタスクが停滞したときにワーカーをハングさせます。上限とタイムアウトエラーを追加してください。
- 失敗を無視する。 失敗状態で終了したタスクは決して動画を生成しません。待ち続けるのではなく、それを捕捉して診断情報を確認してください。
- 誤った入力で長時間待機する。 レンダリングが繰り返し失敗する場合は、再生成を停止してください。まずソースフレームまたはパラメータを修正し、それから再送信してください。
効果的なデバッグ順序
- 画像 URL がブラウザで読み込めることを確認する。
- パラメータの問題を切り分けるため、画像のみで最小限のペイロードを送信する。
- job ID が問題なく返されることを検証する。
- まず手動でポーリングし、状態遷移を観察する。
- それができてから初めて、ループを自動化し、一時的なネットワークエラーに対する再試行を追加する。
これらのステップを順番に処理することで、問題を画像、オプション、またはライフサイクルのいずれかの層に迅速に絞り込み、統合を前進させ続けられます。リクエスト構造、オプション、ポーリングフローを理解した今、このエンドポイントに対する構築の準備が整いました。