このページの内容
Hailuo 2.3 API
1つの非同期APIから、Hailuo 2.3のテキストからの動画生成と画像からの動画生成タスクを作成できます。より低遅延の画像からの動画生成にはHailuo 2.3 Fastを利用できます。
REST API · v1 · 非同期タスク
最初のリクエストを送信する
一意のIdempotency-Keyでタスクを作成し、返されたtask IDを保存して、結果が準備できるまで取得します。
- 1
APIキーを作成
Imyaアカウントの設定画面でキーを発行します。
- 2
タスクを作成
Hailuo 2.3またはHailuo 2.3 Fastを選び、入力を送信します。
- 3
結果を取得
成功または失敗になるまでtask IDを取得します。
認証と冪等性
APIキーをBearerトークンとして送信します。生成POSTには一意のIdempotency-Keyも必須です。安全に再試行しても二重課金は発生しません。
Authorization: Bearer YOUR_IMYA_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY動画生成タスクを作成
非同期のHailuoタスクを作成し、このリクエストに対してリアルタイムで計算したcredits_reservedを返します。
/v1/videos/generations# Text to video (Hailuo 2.3)
curl https://imya.ai/v1/videos/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: hailuo-t2v-order-001" \
-d '{
"model": "hailuo-2.3",
"prompt": "A paper boat crossing a rain-soaked neon street",
"duration": 6,
"resolution": "720p",
"prompt_optimizer": true
}'
# Image to video (Hailuo 2.3 Fast)
curl https://imya.ai/v1/videos/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: hailuo-i2v-order-001" \
-d '{
"model": "hailuo-2.3-fast",
"prompt": "Slow camera push-in with warm moving light",
"image_url": "https://cdn.example.com/first-frame.jpg",
"duration": 6,
"resolution": "1080p"
}'旧ベータAPIとの互換性
既存の実装ではPOST /api/video/generateとx-api-keyを引き続き利用できますが、安全な再試行のため、生成POSTにはIdempotency-Keyも必須です。新規実装では/v1/videos/generationsを使用してください。
curl https://imya.ai/api/video/generate \
-H "x-api-key: YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: legacy-hailuo-order-001" \
-d '{
"modelKey": "hailuo-2-3-standard-t2v",
"prompt": "A paper boat crossing a rain-soaked neon street",
"resolution": "720p",
"outputDurationSec": 6,
"promptExtend": true
}'タスクを取得
最新のタスク状態、最終クレジット使用量、生成MP4、または安全化されたエラーを返します。取得間隔は5秒以上にしてください。短い間隔のリクエストもレート制限に数えられますが、上流の状態は更新されません。動画URLは一時的な場合があるため、速やかにダウンロードしてください。APIは動画の7日または30日の保存を保証しません。
/v1/tasks/{id}curl https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef \
-H "Authorization: Bearer YOUR_IMYA_API_KEY"リクエストパラメーター
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| model | string | はい | hailuo-2.3またはhailuo-2.3-fast。 |
| prompt | string | はい | 最大5,000文字の生成指示です。 |
| image_url | string | 条件付き | 公開HTTPSの開始フレームです。Fastでは必須、標準のテキストからの動画生成では省略します。 |
| duration | number | いいえ | 6秒または10秒です。既定値は6秒です。 |
| resolution | string | いいえ | 720pまたは1080pです。1080pは6秒のみ対応します。 |
| prompt_optimizer | boolean | いいえ | プロンプトを最適化します。既定値はtrueです。 |
レスポンス
{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "pending",
"model": "hailuo-2.3",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:00.000Z",
"credits_reserved": 225
}{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "succeeded",
"model": "hailuo-2.3",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:02:18.000Z",
"credits_reserved": 225,
"credits_used": 225,
"data": [
{
"url": "https://media.example.com/generated/example.mp4"
}
]
}リアルタイムのクレジット課金
サーバーは、選択したモデル、ワークフロー、解像度、長さ、APIキー所有者の現在のプランからcredits_reservedを計算します。レスポンス例の数値は形式を示すためのものです。必ず各リクエストで返された値を使用し、Hailuoの料金をクライアント側に固定しないでください。
タスクステータス
pendingタスクを受け付け、開始を待っています。
processingモデルが動画を生成しています。
succeeded生成が完了し、dataにMP4が含まれます。
failed生成に失敗しました。安全化されたerrorオブジェクトを確認してください。
エラー
400Idempotency-Keyがないか、JSONの形式が不正です。
401APIキーがないか、無効です。
402アカウントのクレジットが不足しています。
403APIアカウントが無効です。
404タスクが存在しないか、このアカウントに属していません。
409同じ冪等キーが異なるリクエスト本文で再利用されました。
413リクエスト本文が64 KiBを超えています。
415Content-Type は application/json である必要があります。
422モデル、プロンプト、画像、長さ、または解像度が無効です。
429レート制限または同時実行タスク数の上限に達しました。
5xxリクエストを完了または送信できませんでした。
Imya 公開 API の共通仕様
以下のルールは、すべての公開画像・動画生成 API に適用されます。モデル固有のパラメータと料金は、このページのパラメータ表を確認してください。
課金と安全な再試行
新しいタスクが受理されると、credits_reserved に表示された正確なクレジットがアトミックに差し引かれます。同じ Idempotency-Key と同じリクエスト本文を再送しても、二重課金されません。
タイムアウトと返金
30 分以内に最終状態へ到達しないタスクは失敗になります。対象クレジットの返金は一度だけ行われ、元の有効期限が維持されます。
レートと同時実行制限
API キーごとに 60 秒間で最大 120 リクエストです。同一アカウントでは画像タスクを最大 5 件、動画タスクを最大 3 件まで同時実行できます。429 応答には Retry-After が含まれる場合があるため、返された場合は従ってください。
ポーリングと所有権
タスク作成時に返された id を使い、GET /v1/tasks/{id} を 5 秒以上の間隔で取得してください。短い間隔のリクエストも API キーのレート制限に数えられますが、上流の状態は更新されません。作成したアカウントだけが結果を参照でき、現在は Webhook、SDK、バッチ送信に対応していません。
エラーとコンテンツ安全性
公開エラーはサニタイズされ、上流の認証情報、内部 URL、インフラ情報を公開しません。安全でないプロンプトは生成前に prompt_blocked で拒否される場合があります。
画像結果の保存期間
無料アカウントの画像結果は 7 日間、有効な有料プランまたは Lifetime アカウントでは最長 30 日間保存されます。削除後は空の成功応答ではなく、status が failed、error.code が media_deleted の応答を返します。
Hailuo 2.3 API 本番環境導入ガイド
安定した Hailuo 2.3 連携は、1 回の長時間 HTTP リクエストではなく、小規模な非同期ジョブシステムとして設計します。モデルの選択肢を設定に集約し、Imya タスクから返される id を必ず保存し、再試行を決定的にしてください。以下はローカルのサンプルから本番環境へ進む際の実践的な指針です。
モデル仕様からパラメーターを選ぶ
送信前に、このページのパラメーター表に対してすべてのリクエストを検証します。開発中は最小のサポート済み入出力から始め、製品に必要な場合にだけ品質、サイズ、長さ、または参照数を増やします。ユーザー入力のプロンプトとファイルは、API を呼び出す前に長さ、種類、容量を自社サーバーで確認してください。
動画では、ドキュメントに記載された長さ、解像度、アスペクト比、音声、ソースメディアの組み合わせだけを許可し、未対応の選択を自動変更しないでください。
復旧できる非同期フローを設計する
動画タスクを送信し、返却された id を自社のジョブレコードと共に保存し、バックグラウンドワーカーで状態を取得します。GET /v1/tasks/{id} は 5 秒以上の間隔でポーリングしてください。短い間隔のリクエストも API キーのレート制限に数えられますが、上流の状態は更新されません。公開 status は pending、processing、succeeded、failed の 4 種類だけです。タスクのハード期限は 30 分です。最終状態を受信するか期限に達したら停止します。現在、Webhook、SDK、バッチ送信は利用できないため、HTTP リクエストとポーリングで連携します。
- 01UI を更新する前に、id、status、credits_reserved、リクエスト識別子を永続化します。
- 02一時的なネットワークエラーではバックオフし、429 の Retry-After に従い、通信エラーから新しい有料タスクを自動作成しないでください。
- 03同一アカウントの同時実行は最大 3 件の動画タスクです。API キーごとに 60 秒間で最大 120 リクエストです。
課金と再試行を決定的にする
新しいタスクが受理されると、credits_reserved で返された正確なクレジットがアトミックに差し引かれます。意図した作成ごとに 1 つの Idempotency-Key を生成し、リクエストと一緒に保存します。同じ Key と同じ本文の再送は元のタスクを返し、二重課金されません。リクエストを変更した場合は新しい Key を使います。
失敗タスクが返金対象の場合、Imya はクレジットを一度だけ返し、元の有効期限を維持します。公開 status は failed のままで、決済処理中は error.code が refund_pending、返金完了後は credits_refunded が応答に含まれます。id で照合し、クライアント側でクレジットを発行しないでください。
認証情報、所有権、生成メディアを保護する
API キーはサーバーに保存し、ブラウザーやモバイルバンドルに埋め込まないでください。返された各 id を作成者の認証済みユーザーまたはワークスペースに関連付け、結果を表示する前に確認します。公開エラーはサニタイズされています。サポート用に独自のリクエスト ID とタスク id を記録し、プロンプト、非公開 URL、認証情報は露出しないでください。
動画の固定保存期間を前提にしないでください。成功後、製品で保存が必要な結果は、ユーザーの同意と自社のプライバシーポリシーに従って、自社管理のストレージに複製し、URL の利用不能を通常のライフサイクルとして扱います。
本番環境チェックリスト
- 送信前にモデル固有のフィールドを検証する。
- 意図したタスクごとに Idempotency-Key とリクエスト本文を保存する。
- タスク状態を永続化し、5 秒以上の間隔でポーリングする。
- アカウントの同時実行数と API キーのレート制限を実施する。
- 4 種類の公開 status を明示的に処理する。failed では error.code の media_deleted または refund_pending を確認し、credits_refunded で返金完了を確認する。
- 認証情報をサーバー側に保ち、結果の保存ポリシーを定義する。
よくある質問
ワーカーはどのくらいの間隔でポーリングすべきですか？
5 秒以上の間隔にします。処理中のタスクには、バックオフを伴うより遅いポーリングも適切です。
クレジットはいつ差し引かれますか？
新しいタスクが受理された時点で、credits_reserved の正確な額がアトミックに差し引かれます。
再試行で二重課金されますか？
同じ Idempotency-Key と完全に同じリクエスト本文の再送は、元のタスクを返し、再課金されません。
タスクが最終的に失敗したらどうしますか？
明確な製品向けエラーを表示し、サポート用に id を保持し、対象となる 1 回限りの返金はサーバーに完了させます。存在しない refunded status を待たず、credits_refunded で結果を確認します。
実装前にHailuoを試しますか？
Hailuo 2.3のオンラインツールで、Fast版と標準版、テキスト入力と画像入力を比較できます。
Hailuo 2.3をオンラインで試す