チュートリアル
HiAPI API で muse-video-1.0/text-to-video を呼び出す:curl と Python ガイド
リクエストフィールド、非同期ポーリング、実行可能なサンプルリクエスト
このページの内容
送信前に:認証、エンドポイント、モデル識別子
muse-video-1.0/text-to-video はテキストプロンプトから動画クリップを生成できます。プロンプトといくつかの制御パラメータを送信すると、サービスがクリップをレンダリングし、ダウンロード可能な URL または参照を返します。
重要なアーキテクチャ上のポイントは、この呼び出しが非同期であることです。動画のレンダリングには時間がかかるため、API はファイルが準備できるまで HTTP 接続を開いたままにしません。そのため、フローは 2 つの段階に分かれます:
- 送信——プロンプトとパラメータを POST します。レスポンスはすぐに返り、タスク識別子と初期タスク状態が含まれます。
- ポーリング——識別子を使って一定間隔でタスクを GET し、状態が終端(成功または失敗)になるまで待ち、その後結果を取得します。
この「まず送信してからポーリングする」という形態は、コードを書く前に最もよく理解しておくべき要点です。これによりアプリケーションの構造が変わります。動画は送信リクエストのレスポンスには現れず、遭遇するエラーはすべて特定の段階(送信、検証、レンダリング、取得)に属します。自分のコードでこれらの段階を区別する(別々の関数を使い、個別にログを記録する)ことで、本ガイドの残りの内容がより適用しやすくなります。
渡すモデル文字列は正確でなければなりません:muse-video-1.0/text-to-video。vendor/model 形式は HiAPI の各モデルエンドポイント共通の規約であり、API のルーティングはこれに基づいてどの生成器を呼び出すかを判断します。
リクエストの構築:プロンプト、再生時間、音声フィールド
最初のリクエストの前に、3 つのものを準備する必要があります。
API キー
すべてのリクエストは bearer token による認証が必要です。ソースコードではなく環境変数に保存し、コミット履歴に漏れないようにしてください:
export HIAPI_API_KEY="your_key_here"
Authorization: Bearer $HIAPI_API_KEY ヘッダーとして送信します。認証系のエラーでリクエストが失敗した場合は、まずこのヘッダーを確認してください——変数名の綴り間違い、末尾の空白、現在のシェルで値が設定されていないことが最も一般的な原因です。
ベース URL
すべての呼び出しは HiAPI プラットフォームの 1 つのベース URL を共有します。アカウントパネルまたは API リファレンスの現在の値を使用し、古いコードスニペットからコピーしないでください。変数に保存しておけば、1 か所を変更するだけで済みます。
モデル識別子
モデル文字列は muse-video-1.0/text-to-video です。大文字小文字を区別するリテラルとして扱ってください。異なる大文字小文字や欠落したサフィックスなどのバリエーションを自分で結合したり推測したりしないでください——未知のモデル識別子は検証エラーであり、フォールバックではありません。
これら 3 つの要素が準備できたら、リクエストボディを構築できます。
実際に動作する curl リクエスト
リクエストボディは JSON です。概念上、3 つのフィールドグループが含まれます。
プロンプト
プロンプトはクリエイティブな指示であり、出力品質の大部分を決定します。効果的なプロンプトは、形容詞を並べるだけでなく、被写体、動作、カメラの動き、照明、スタイルを具体的に記述します。これは通常の文字列フィールドです。
再生時間
テキストから動画を生成するモデルは、クリップの長さを知る必要があります。再生時間はリクエストフィールドであり、コストにも影響します:生成は出力秒数に基づいて課金されます。許容範囲とデフォルト値はモデルが特定の時点で定義するため、muse-video-1.0/text-to-video のライブ API リファレンスから正確なフィールド名と許容値を読み取り、推測しないでください。範囲外の再生時間を渡すと検証エラーになります。
音声
muse-video-1.0/text-to-video は視覚生成に加えて音声関連の制御もサポートしています。これらもリクエストフィールドです——通常はトグルまたは音声プロンプトスタイルの入力——正確な名前と許容値は同じ API リファレンスに文書化されています。初回統合時には、オプションの音声フィールドを完全に省略し、動画が正常に返ることを確認してから、音声オプションを 1 つずつ追加するのが保守的な方法です。
したがって、最小限のリクエストボディは概ね次のようになります(フィールド名は例示のみ——リファレンスで確認してください):
{
"model": "muse-video-1.0/text-to-video",
"prompt": "日の出の時刻、霧に包まれた松林をゆっくりと空中から押し進むショット、柔らかなボリュームライト、シネマティック",
"duration": 5
}
パラメータセットは進化する可能性があるため、信頼できる習慣は:そのモデルのリファレンスドキュメントを取得し、フィールド名を一字一句コピーし、送信前にローカルで検証することです。
Python での同じリクエスト
送信呼び出しは単なる HTTP POST です。正確なリソースパスは HiAPI API リファレンスで定義されています。以下の例では通常のタスクエンドポイントを使用し、モデルをリクエストボディに含めます。
curl -sS -X POST "$HIAPI_BASE_URL/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "muse-video-1.0/text-to-video",
"prompt": "雨のネオン路地を歩く段ボール製のロボット、濡れたアスファルトの反射、35mm フィルムの質感",
"duration": 5
}'
レスポンスは小さく、すぐに返ります。重要なのはタスク識別子と状態です。典型的な構造は次のとおりです:
{
"id": "job_abc123",
"status": "queued"
}
id を記録してください——これが後続のすべての呼び出しのハンドルです。status が queued または processing であることは正常であり、リクエストが受け入れられたことを示します。問題が発生したわけではありません。
シェルで手動ポーリング:
curl -sS "$HIAPI_BASE_URL/v1/video/generations/job_abc123" \
-H "Authorization: Bearer $HIAPI_API_KEY"
一定間隔で数回実行し、status が終端状態に変化するのを観察します。実際には、このループはターミナル履歴ではなくコード内に置くべきです。
非同期結果の処理と API を過度に叩かないポーリング
Python 版は同じ 2 つのことを行います——送信してからポーリング——が、タイムアウト処理、有界リトライ、結果保存を追加し、無人で安全に実行できるようにします。
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}"}
MODEL = "muse-video-1.0/text-to-video"
def submit(prompt: str, duration: int) -> str:
resp = requests.post(
f"{BASE}/v1/video/generations",
headers={**HEADERS, "Content-Type": "application/json"},
json={"model": MODEL, "prompt": prompt, "duration": duration},
timeout=30,
)
resp.raise_for_status()
return resp.json()["id"]
def wait_for(job_id: str, max_wait: int = 900) -> dict:
deadline = time.time() + max_wait
interval = 5
while time.time() < deadline:
r = requests.get(
f"{BASE}/v1/video/generations/{job_id}",
headers=HEADERS,
timeout=30,
)
if r.status_code >= 500 or r.status_code == 429:
time.sleep(interval)
interval = min(interval * 2, 30)
continue
r.raise_for_status()
job = r.json()
if job["status"] == "succeeded":
return job
if job["status"] == "failed":
raise RuntimeError(job.get("error") or "generation failed")
time.sleep(interval)
interval = min(interval * 1.5, 30)
raise TimeoutError(f"job {job_id} did not finish in time")
def save(job: dict, path: str) -> None:
url = job["result"]["video_url"]
with requests.get(url, stream=True, timeout=120) as r:
r.raise_for_status()
with open(path, "wb") as f:
for chunk in r.iter_content(8192):
f.write(chunk)
if __name__ == "__main__":
job_id = submit(
"木のテーブルの上に置かれたガラスのミニチュアテラリウム、朝の光、舞う塵の粒子、マクロ",
5,
)
job = wait_for(job_id)
save(job, "output.mp4")
print("saved output.mp4")
ここには 3 つの意図的な選択があります。リトライはループ回数ではなく締め切りによって制限されるため、無限にハングしません。バックオフは一時的な失敗時には増加し、成功パスのポーリングでは緩やかに増加します。ダウンロードは別のストリーミングリクエストであり、大きなファイルが JSON パスを通るのを避けます。
よくあるエラーとそのトラブルシューティング方法
ポーリング頻度は実際の設計上の決定です。200 ミリ秒ごとにポーリングすると無駄な負荷が発生するだけです。5 分ごとにポーリングすると、レンダリング完了後に実際の時間を無駄にします。
実用的な戦略:
- 適度な間隔(数秒)から始めて徐々に増加——各ポーリングで 1.5 倍にし、上限を約 30 秒にするとうまく機能します。
429および5xxレスポンスにはバックオフを強化:間隔を 2 倍にしてリトライし、タスク状態ではなく容量シグナルとして扱います。- 最大総待機時間を設定し、タイムアウト時にはエラーをスローし、永遠にポーリングしないようにします。より長い再生時間のレンダリングは実際に時間がかかるため、上限は自身のワークロードに基づいて設定する必要があります。
- 状態が変化したときのみ 1 回遷移を記録し、毎回のポーリングでは記録しない——ノイズの多いログは実際の失敗を発見しにくくします。
完了したタスクのレスポンスには通常、終端の status、タスク id、およびダウンロード可能な動画 URL を含む結果ペイロードが含まれ、メタデータや URL の有効期限が付随することもあります。成功後は速やかにファイルを取得してください。タスクが failed を報告した場合、リトライ前にレスポンスのエラーメッセージを読んでください——検証エラーはリトライで成功することは決してありませんが、内部レンダリングエラーは成功する可能性があります。
次のステップ
最小限のリクエストボディから始め、エンドツーエンドの成功を 1 回確認してから、muse-video-1.0/text-to-video の現在のリファレンスドキュメントに照らして再生時間と音声制御を追加してください。同じ「まず送信してからポーリングする」パターンは他の HiAPI モデルエンドポイントにも移行できるため、ここで書いたクライアントコードは再利用可能です。