HappyHorse - リファレンス動画 API リファレンス

注意事項

API 呼び出しを正常に実行するには、同じリージョンに属するモデル、エンドポイント URL、および API キーを使用する必要があります。リージョンをまたいだ呼び出しは失敗します。

モデルの選択：モデルが配置されているリージョンを確認します。
URL の選択：対応するエンドポイント URL を選択します。HTTP と DashScope SDK の両方の URL がサポートされています。
API キーの設定：リージョンを選択し、API キーを取得してから、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 呼び出し

リファレンス動画タスクは時間がかかるため (通常 1～5 分)、API は非同期呼び出しを使用します。ワークフローは、「タスクの作成 -> 結果のポーリング」という 2 つのコアステップで構成されます。

ステップ 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-r2v。input object (必須)モデルの入力。参照画像とテキストプロンプトが含まれます。

プロパティ

prompt string (必須)生成する動画に含めたい要素や視覚的なスタイルの説明。任意の言語での入力がサポートされています。長さは、中国語以外の文字で 5,000 文字、中国語の文字で 2,500 文字に制限されます。この制限を超えたコンテンツは自動的に切り捨てられます。画像の参照：プロンプトでは、「[Image 1]」や「[Image 2]」を使用して、media 配列内の対応する参照画像を参照します。順序は media 配列内の順序と一致している必要があります。参照を使用する際は、「[Image 1] の赤いチャイナドレスの女性」のように、画像内のオブジェクトを指定します。media array (必須)参照画像のリスト。配列内の各要素は、type と url フィールドを含むメディアオブジェクトです。

この配列内の要素の順序は、prompt 内の被写体の参照順序を定義します。
配列内の最初の reference_image は[Image 1]に、2 番目は[Image 2]に対応し、以下同様です。

要素のプロパティ

type string (必須)メディアアセットのタイプ。これを次のように設定します：

reference_image：参照画像。

アセットの制限：

参照画像の数：1～9 枚。

url string (必須)参照画像の URL または Base64 エンコードされたデータ。画像の要件：

フォーマット：JPEG、JPG、PNG、WEBP。
解像度：最も短い辺が 400 ピクセル以上である必要があります。720P 以上の解像度で鮮明な画像を推奨します。小さすぎる、ぼやけている、または過度に圧縮された画像の使用は、出力品質を低下させる可能性があるため避けてください。
最大ファイルサイズ：20 MB。

サポートされている入力フォーマット：

公開 URL：
- HTTP または HTTPS プロトコルをサポートします。
- 例：https://xxx/xxx.jpg。
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：デフォルト値。

ratio string (任意)生成される動画の縦横比。有効値：

16:9：デフォルト値。
9:16
3:4
4:3
4:5
5:4
1:1
9:21
21:9

duration integer (任意)生成される動画の持続時間 (秒単位)。有効値：3 から 15 までの整数。デフォルト値：5。watermark boolean (任意)生成される動画にウォーターマークを追加するかどうかを指定します。ウォーターマークは右下隅に配置され、テキストは「Happy Horse」で固定されます。

true：デフォルト値。ウォーターマークが追加されます。
false：ウォーターマークは追加されません。

seed integer (任意)乱数シードは [0, 2147483647] の範囲の整数である必要があります。指定しない場合、ランダムなシードが生成されます。シードを固定すると再現性が向上します。モデルの生成は確率的であるため、同じシードでも同一の結果が保証されるわけではありません。

リファレンス動画 (複数画像)

# 以下の URL はシンガポールリージョン用です。呼び出す際は、{WorkspaceId} を実際のワークスペース 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-r2v",
    "input": {
        "prompt": "A woman in a red qipao from [Image 1] is first shown in a profile medium shot, highlighting the tailored cut and S-curve of the dress. The camera then switches to a low-angle shot, capturing her unfolding the fan from [Image 2] while the tassel earrings from [Image 3] sway with her head movement. The scene ends with a close-up of her face, focusing on the charm in her eyes as her fingertips touch the fan, showcasing Eastern elegance from multiple angles.",
        "media": [
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/mvzfud/hh-v2v-girl.jpg"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/fvuihk/hh-v2v2-folding-fan.jpg"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/imerii/hh-v2v-earrings.jpg"
            }
        ]
    },
    "parameters": {
        "resolution": "720P",
        "ratio": "16:9",
        "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"
}

タスクの作成に失敗しました。「エラーコード」をご参照ください。

{
    "code": "InvalidApiKey",
    "message": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

ステップ 2：タスク結果の取得

シンガポール
米国 (バージニア)
中国 (北京)
ドイツ (フランクフルト)
日本 (東京)

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

ポーリングの推奨事項：動画の生成には数分かかる場合があります。合理的なクエリ間隔 (例：15 秒) でポーリングメカニズムを実装し、結果を取得することを推奨します。
タスクステータスのフロー：PENDING (キューイング) → RUNNING (処理中) → SUCCEEDED (成功) または FAILED (失敗)。
タスク ID の有効期間：タスク ID は 24 時間有効です。この期間を過ぎると、結果をクエリできなくなり、API はタスクステータスとして UNKNOWN を返します。

リクエストパラメーター

リクエストヘッダー

Authorization string (必須)Model Studio API キーでリクエストを認証します。例：Bearer sk-xxxx。

URL パスパラメーター

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+08:00 で、フォーマットは YYYY-MM-DD HH:mm:ss.SSS です。scheduled_time stringタスクが実行された時刻。時刻は UTC+08:00 で、フォーマットは YYYY-MM-DD HH:mm:ss.SSS です。end_time stringタスクが完了した時刻。時刻は UTC+08:00 で、フォーマットは YYYY-MM-DD HH:mm:ss.SSS です。video_url string生成された動画の URL。task_status が SUCCEEDED の場合にのみ返されます。24 時間有効です。動画は H.264 エンコーディングの MP4 フォーマットです。orig_prompt string元の入力プロンプト。リクエストパラメーター prompt に対応します。code stringエラーコード。失敗したリクエストに対してのみ返されます。「エラーコード」をご参照ください。message string詳細なエラーメッセージ。失敗したリクエストに対してのみ返されます。「エラーコード」をご参照ください。

usage objectタスクの使用量統計。成功したタスクに対してのみ課金されます。

プロパティ

duration integer生成された動画の課金対象となる持続時間 (秒単位)。input_video_duration integer入力動画の合計持続時間 (秒単位)。リファレンス動画タスクでは常に 0 です。output_video_duration integer出力動画の合計持続時間 (秒単位)。ratio string生成された動画の縦横比。SR integer生成された動画の解像度レベル。video_count integer生成された動画の数。常に 1 です。

request_id stringトレースとトラブルシューティングのための一意なリクエスト識別子。

タスク成功
タスク失敗
タスククエリの期限切れ

動画 URL は 24 時間のみ有効で、その後自動的にパージされます。生成された動画は速やかに保存してください。

{
    "request_id": "35137489-2862-96cb-b6f2-xxxxxx",
    "output": {
        "task_id": "1469cfc3-3004-4d9e-ab10-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-04-25 15:03:25.848",
        "scheduled_time": "2026-04-25 15:03:25.884",
        "end_time": "2026-04-25 15:04:05.882",
        "orig_prompt": "A woman in a red qipao from [Image 1] is first shown in a profile medium shot, highlighting the dress'\''s tailored cut and S-curve. The camera then switches to a low-angle shot, capturing her unfolding the fan from [Image 2] while the tassel earrings from [Image 3] sway with her head movement. The scene ends with a close-up of her face, focusing on the charm in her eyes as her fingertips touch the fan, showcasing Eastern elegance from multiple angles.",
        "video_url": "https://dashscope-result-intl.oss-ap-southeast-1.aliyuncs.com/xxxx.mp4"
    },
    "usage": {
        "duration": 5,
        "input_video_duration": 0,
        "output_video_duration": 5,
        "video_count": 1,
        "SR": 720,
        "ratio": "16:9"
    }
}

タスクが失敗すると、task_status は FAILED となり、エラーコードとメッセージが表示されます。「エラーコード」をご参照ください。

{
    "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The resolution is not valid xxxxxx"
    }
}

task_id は 24 時間有効です。この期間を過ぎると、クエリは以下のエラーを返します。

{
    "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
    "output": {
        "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
        "task_status": "UNKNOWN"
    }
}

エラーコード

モデルの呼び出しが失敗し、エラーメッセージが返された場合は、「エラーコード」で解決策をご参照ください。

​注意事項

​HTTP 呼び出し

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

リクエストパラメーター

リクエストヘッダー

リクエストボディ

レスポンスパラメーター

​ステップ 2：タスク結果の取得

リクエストパラメーター

リクエストヘッダー

URL パスパラメーター

レスポンスパラメーター

​エラーコード

注意事項

HTTP 呼び出し

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

ステップ 2：タスク結果の取得

エラーコード