Skip to main content

HappyHorse image-to-video (開始フレーム) API リファレンス

HappyHorse モデルを使用して、開始フレーム画像とオプションのテキストプロンプトから、リアルで滑らかな動きの動画を生成します。

注意事項

モデル、エンドポイント URL、API キーは同じリージョンに属している必要があります。リージョン間の呼び出しは失敗します。
このトピックのサンプルコードは、シンガポールリージョンに適用されます。
Alibaba Cloud Model Studio は、中国 (北京) およびシンガポールリージョン向けにワークスペース固有のドメインをリリースしました。新しい専用ドメインは、推論リクエストに対して優れたパフォーマンスと高い安定性を提供します。新しいドメインへの移行を推奨します：
  • 中国 (北京)：https://dashscope.aliyuncs.com から https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • シンガポール：https://dashscope-intl.aliyuncs.com から https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} はワークスペース ID で、Alibaba Cloud Model Studio コンソールの [ワークスペース詳細] ページで確認できます。既存のドメインは引き続き完全に機能します。

HTTP 呼び出し

Image-to-video タスクには 1～5 分かかります。API は非同期呼び出しを使用します：「タスクの作成 → 結果のポーリング」。

ステップ 1：タスクの作成

  • シンガポール
  • 米国 (バージニア)
  • 中国 (北京)
  • ドイツ (フランクフルト)
  • 日本 (東京)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
{WorkspaceId} を実際の ワークスペース ID に置き換えてください。
  • タスクが作成された後、返された task_id を使用して結果をクエリします。task_id は 24 時間有効です。重複タスクを作成しないでください。代わりに、ポーリングを使用して結果を取得してください。
  • 初心者向けのガイダンスについては、「Postman または cURL を使用した API の呼び出し」をご参照ください。

リクエストパラメーター

Content-Type string (必須)リクエストのコンテンツタイプ。application/json である必要があります。Authorization string (必須)Model Studio API キーでリクエストを認証します。例：Bearer sk-xxxx。X-DashScope-Async string (必須)非同期処理を有効にします。HTTP リクエストは非同期呼び出しのみをサポートします。enable に設定する必要があります。
このリクエストヘッダーがない場合、「current user api does not support synchronous calls」というエラーが返されます。
リクエストボディ
model string (必須)モデル名です。利用可能なモデルについては、Model Studio コンソールをご参照ください。例：happyhorse-1.1-i2v。input object (必須)テキストプロンプトを含むモデル入力です。

プロパティ

prompt string (任意)生成する動画のコンテンツを記述します。任意の言語をサポートします。最大：5,000 非中国語文字または 2,500 中国語文字。これより長い入力は切り捨てられます。media array (必須)入力画像配列です。

media[] 要素のプロパティ

type string (必須)メディアのタイプです。許可される値：
  • first_frame：開始フレーム。
開始フレーム画像が 1 つだけ必須です。url string (必須)メディアの URL です。

入力画像 (type=first_frame)

開始フレーム画像の URL または Base64 エンコードされたデータです。画像の制約：
  • フォーマット：JPEG、JPG、PNG、WEBP。
  • 解像度：幅と高さの両方が 300 ピクセル以上である必要があります。
  • 縦横比：1:2.5 から 2.5:1 の間。
  • ファイルサイズ：最大 20 MB。
サポートされている入力フォーマット：
  1. パブリック URL：
  2. Base64 エンコードされた画像文字列：
    • フォーマット：data:{MIME_type};base64,{base64_data}。
    • 例：data:image/png;base64,GDU7MtCZzEbTbmRZ...... (表示のために切り捨て)。

      Base64 エンコード形式

      フォーマット：data:{MIME_type};base64,{base64_data}。
      • {base64_data}：画像ファイルの Base64 エンコードされた文字列。
      • {MIME_type}：画像のメディアタイプで、ファイル形式と一致する必要があります。

      画像フォーマット

      MIME タイプ

      JPEG

      image/jpeg

      JPG

      image/jpeg

      PNG

      image/png

      WEBP

      image/webp

parameters object (任意)解像度や持続時間などの動画出力設定です。

プロパティ

resolution string (任意)生成される動画の解像度です。出力ピクセル数は、入力画像の縦横比を維持しながら、選択された階層に近似します。許可される値：
  • 480P
  • 720P
  • 1080P (デフォルト)
duration integer (任意)生成される動画の持続時間 (秒単位) です。値は [3, 15] の範囲の整数である必要があります。デフォルト: 5。watermark boolean (任意)右下隅に「Happy Horse」というテキストのウォーターマークを追加します。
  • true (デフォルト)
  • false
seed integer (任意)乱数シードは、[0, 2147483647] の範囲の整数である必要があります。指定しない場合、ランダムなシードが生成されます。シードを固定すると、再現性が向上します。モデルの生成は確率的であるため、同じシードでも同一の結果が保証されるわけではありません。
  • Image-to-video
# 以下の URL はシンガポールリージョン用です。{WorkspaceId} をご利用の Bailian ワークスペース ID に置き換えてください。URL はリージョンによって異なります。
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "happyhorse-1.1-i2v",
    "input": {
        "prompt": "A cat running on the grass",
        "media": [
            {
                "type": "first_frame",
                "url": "https://cdn.translate.alibaba.com/r/wanx-demo-1.png"
            }
        ]
    },
    "parameters": {
        "resolution": "720P",
        "duration": 5
    }
}'

レスポンスパラメーター

output objectタスクの出力です。

プロパティ

task_id stringタスク ID です。24 時間クエリに対して有効です。task_status stringタスクのステータスです。

列挙値

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN：タスクが存在しないか、ステータスが不明です。
request_id stringトレースとトラブルシューティングのためのユニークなリクエスト識別子です。code stringエラーコードです。失敗したリクエストに対してのみ返されます。「エラーコード」をご参照ください。message string詳細なエラーメッセージです。失敗したリクエストに対してのみ返されます。「エラーコード」をご参照ください。
  • 成功レスポンス
  • エラーレスポンス
task_id を保存して、タスクのステータスと結果をクエリします。
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

ステップ 2：結果のポーリング

  • シンガポール
  • 米国 (バージニア)
  • 中国 (北京)
  • ドイツ (フランクフルト)
  • 日本 (東京)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
  • ポーリングの推奨事項：動画の生成には数分かかります。15 秒などの適切な間隔でポーリングメカニズムを使用してください。
  • タスクの状態遷移：PENDING → RUNNING → SUCCEEDED または FAILED。
  • 結果リンク：タスクが成功すると、24 時間有効な動画 URL が返されます。動画をダウンロードし、OSS などの永続ストレージに保存してください。
  • task_idの有効期間：24 時間。この期間を過ぎると、クエリはタスクステータスを UNKNOWN として返します。

リクエストパラメーター

リクエストヘッダー
Authorization string (必須)Model Studio API キーでリクエストを認証します。例：Bearer sk-xxxx。
パスパラメーター
task_id string (必須)タスクの ID です。
  • タスク結果のクエリ
{task_id} を、前の API 呼び出しで返された task_id の値に置き換えてください。task_id は 24 時間クエリに対して有効です。{WorkspaceId} を実際の ワークスペース ID に置き換えてください。
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

レスポンスパラメーター

outputobjectタスクの出力です。

プロパティ

task_id stringタスク ID です。24 時間クエリに対して有効です。task_status stringタスクのステータスです。

列挙値

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN：タスクが存在しないか、ステータスが不明です。
ポーリング中の状態遷移：
  • PENDING → RUNNING → SUCCEEDED または FAILED。
  • 最初のクエリステータスは通常 PENDING または RUNNING です。
  • ステータスが SUCCEEDED に変わると、レスポンスには生成された動画の URL が含まれます。
  • ステータスが FAILED の場合は、エラーメッセージを確認してタスクをリトライしてください。
submit_time stringタスクが送信された時間です。時間は UTC+8 で、フォーマットは YYYY-MM-DD HH:mm:ss.SSS です。scheduled_time stringタスクが実行された時間です。時間は UTC+8 で、フォーマットは YYYY-MM-DD HH:mm:ss.SSS です。end_time stringタスクが完了した時間です。時間は UTC+8 で、フォーマットは YYYY-MM-DD HH:mm:ss.SSS です。video_urlstringtask_status が SUCCEEDED の場合にのみ返されます。URL は 24 時間有効です。この URL から MP4 動画 (24 fps、H.264 エンコード) をダウンロードしてください。orig_prompt string元の入力プロンプトで、リクエストパラメーター prompt に対応します。code stringエラーコードです。失敗したリクエストに対してのみ返されます。「エラーコード」をご参照ください。message string詳細なエラーメッセージです。失敗したリクエストに対してのみ返されます。「エラーコード」をご参照ください。
usage object使用量統計です。成功したタスクに対してのみ計算されます。

プロパティ

input_video_duration integer入力動画の持続時間 (秒単位) です。output_video_duration integer出力動画の持続時間 (秒単位) です。duration integer課金対象となる合計動画持続時間です。SR integer出力動画の解像度です。video_count integer出力動画の数です。この値は常に 1 です。
request_id stringトレースとトラブルシューティングのためのユニークなリクエスト識別子です。
  • タスク成功
  • タスク失敗
  • タスククエリの期限切れ
動画 URL は 24 時間のみ有効で、その後自動的にパージされます。生成された動画は速やかに保存してください。
{
    "request_id": "8ae698ba-df2d-966c-abcf-xxxxxx",
    "output": {
        "task_id": "e56d806f-76f9-4037-aefa-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-04-20 19:33:50.425",
        "scheduled_time": "2026-04-20 19:33:50.463",
        "end_time": "2026-04-20 19:35:34.216",
        "orig_prompt": "A cat running on the grass",
        "video_url": "https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
    "usage": {
        "duration": 5,
        "input_video_duration": 0,
        "output_video_duration": 5,
        "video_count": 1,
        "SR": 720
    }
}

エラーコード

呼び出しが失敗した場合は、「エラーメッセージ」のリファレンスをご確認ください。

よくある質問

動画の縦横比

出力の縦横比は開始フレームと一致します。HappyHorse text-to-video モデルとは異なり、image-to-video は ratio パラメーターをサポートしていません。