全部產品
Search

搜尋本產品

    Alibaba Cloud Model Studio：HappyHorse-文生視頻API參考

    文件中心

    Alibaba Cloud Model Studio：HappyHorse-文生視頻API參考

    更新時間：Apr 28, 2026

    HappyHorse文生視頻模型，輸入文本提示詞產生物理真實、運動流暢的視頻內容。

    適用範圍

    為確保調用成功，請務必保證模型、endpoint URL 和 API Key 均屬於同一地區。跨地區調用將會失敗。

    說明

    本文的範例程式碼適用於新加坡地區。

    HTTP調用

    文生視頻任務耗時較長（通常為1-5分鐘），API採用非同步呼叫的方式。整個流程包含 "建立任務 -> 輪詢擷取" 兩個核心步驟，具體如下：

    步驟1：建立任務擷取任務ID

    新加坡

    POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

    北京

    POST https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

    說明

    • 建立成功後，使用介面返回的 task_id 查詢結果，task_id 有效期間為 24 小時。請勿重複建立任務，輪詢擷取即可。

    • 新手指引請參見Postman。

    請求參數

    文生視頻

    curl --location 'https://dashscope-intl.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.0-t2v",
    "input": {
        "prompt": "一座由硬紙板和瓶蓋搭建的微型城市，在夜晚煥發出生機。一列硬紙板火車緩緩駛過，小燈點綴其間，照亮前路。"
    },
    "parameters": {
        "resolution": "720P",
        "ratio": "16:9",
        "duration": 5
    }
}'

    Content-Type string （必選）

    請求內容類型。此參數必須設定為application/json。

    Authorization string（必選）

    請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。樣本值：Bearer sk-xxxx。

    X-DashScope-Async string （必選）

    非同步處理配置參數。HTTP請求只支援非同步，必須設定為enable。

    重要

    缺少此要求標頭將報錯：“current user api does not support synchronous calls”。

    請求體（Request Body）

    model string （必選）

    模型名稱。

    可選值：

    • happyhorse-1.0-t2v

    input object （必選）

    模型的輸入資訊。

    屬性

    prompt string （必選）

    文本提示詞，用於描述期望產生的視頻內容。

    支援任何語言輸入，長度不超過5000個非中文字元或2500個中文字元，超過部分將自動截斷。

    parameters object （可選）

    視頻處理參數，如設定視頻解析度、設定視頻時間長度等。

    屬性

    resolution string （可選）

    指定產生視頻的解析度檔位。

    可選值：

    • 720P

    • 1080P：預設值。

    ratio string （可選）

    指定產生視頻的寬高比。

    可選值：

    • 16:9：預設值。

    • 9:16

    • 1:1

    • 4:3

    • 3:4

    duration integer （可選）

    指定產生視頻的時間長度，單位為秒。

    取值為[3, 15]之間的整數。預設值為5。

    watermark boolean （可選）

    是否在產生的視頻上添加浮水印標識。浮水印位於視頻右下角，文案固定為“Happy Horse”。

    • true：預設值，添加浮水印。

    • false：不添加浮水印。

    seed integer （可選）

    隨機數種子，取值範圍為[0, 2147483647]。

    未指定時，系統自動產生隨機種子。若需提升產生結果的可複現性，建議固定seed值。

    請注意，由於模型產生具有機率性，即使使用相同 seed，也不能保證每次產生結果完全一致。

    響應參數

    成功響應

    請儲存 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"
}

    output object

    任務輸出資訊。

    屬性

    task_id string

    任務ID。查詢有效期間24小時。

    task_status string

    任務狀態。

    枚舉值

    • PENDING：任務排隊中

    • RUNNING：任務處理中

    • SUCCEEDED：任務執行成功

    • FAILED：任務執行失敗

    • CANCELED：任務已取消

    • UNKNOWN：任務不存在或狀態未知

    request_id string

    請求唯一標識。可用於請求明細溯源和問題排查。

    code string

    請求失敗的錯誤碼。請求成功時不會返回此參數，詳情請參見錯誤資訊。

    message string

    請求失敗的詳細資料。請求成功時不會返回此參數，詳情請參見錯誤資訊。

    步驟2：根據任務ID查詢結果

    新加坡

    GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}

    北京

    GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

    說明

    • 輪詢建議：視頻產生過程約需數分鐘，建議採用輪詢機制，並設定合理的查詢間隔（如 15 秒）來擷取結果。

    • 任務狀態流轉：PENDING（排隊中）→ RUNNING（處理中）→ SUCCEEDED（成功）/ FAILED（失敗）。

    • 結果連結：任務成功後返回視頻連結，有效期間為 24 小時。建議在擷取連結後立即下載並轉存至永久儲存（如阿里雲 OSS）。

    • task_id 有效期間：24小時，逾時後將無法查詢結果，介面將返回任務狀態為UNKNOWN。

    請求參數

    查詢任務結果

    將{task_id}完整替換為上一步介面返回的task_id的值。task_id查詢有效期間為24小時。

    curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
    要求標頭（Headers）

    Authorization string（必選）

    請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。樣本值：Bearer sk-xxxx。

    URL路徑參數（Path parameters）

    task_id string（必選）

    任務ID。

    響應參數

    任務執行成功

    視頻URL僅保留24小時，逾時後會被自動清除，請及時儲存產生的視頻。

    {
    "request_id": "99243b47-ec5f-9413-9993-xxxxxx",
    "output": {
        "task_id": "4673458e-28be-4a05-bf2a-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-04-20 17:55:17.075",
        "scheduled_time": "2026-04-20 17:55:17.129",
        "end_time": "2026-04-20 17:56:36.658",
        "orig_prompt": "一座由硬紙板和瓶蓋搭建的微型城市，在夜晚煥發出生機。一列硬紙板火車緩緩駛過，小燈點綴其間，照亮前路。",
        "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,
        "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 parameter is invalid."
    }
}

    任務查詢到期

    task_id查詢有效期間為 24 小時，逾時後將無法查詢，返回以下報錯資訊。

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

    output object

    任務輸出資訊。

    屬性

    task_id string

    任務ID。查詢有效期間24小時。

    task_status string

    任務狀態。

    枚舉值

    • PENDING：任務排隊中

    • RUNNING：任務處理中

    • SUCCEEDED：任務執行成功

    • FAILED：任務執行失敗

    • CANCELED：任務已取消

    • UNKNOWN：任務不存在或狀態未知

    輪詢過程中的狀態流轉：

    • PENDING（排隊中） → RUNNING（處理中）→ SUCCEEDED（成功）/ FAILED（失敗）。

    • 初次查詢狀態通常為 PENDING（排隊中）或 RUNNING（處理中）。

    • 當狀態變為 SUCCEEDED 時，響應中將包含產生的視頻URL。

    • 若狀態為 FAILED，請檢查錯誤資訊並重試。

    • 若狀態為 CANCELED，表示任務已取消，如需繼續請重新提交任務。

    • 若狀態為 UNKNOWN，表示任務不存在或狀態未知，可能在 task_id 不存在或超過 24 小時有效期間後出現。

    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_url string

    視頻URL。僅在 task_status 為 SUCCEEDED 時返回。

    連結有效期間24小時，可通過此URL下載視頻。視頻格式為MP4（H.264 編碼）。

    orig_prompt string

    原始輸入的prompt，對應請求參數prompt。

    code string

    請求失敗的錯誤碼。請求成功時不會返回此參數，詳情請參見錯誤資訊。

    message string

    請求失敗的詳細資料。請求成功時不會返回此參數，詳情請參見錯誤資訊。

    usage object

    輸出資訊統計，只對成功的結果計數。

    屬性

    input_video_duration integer

    輸入的視頻的時間長度，單位秒。

    output_video_duration integer

    輸出視頻的時間長度，單位秒。

    duration integer

    總的視頻時間長度，用於計費。

    SR integer

    輸出視頻的解析度檔位。

    ratio string

    輸出視頻的寬高比。

    video_count integer

    輸出視頻的數量。固定為1。

    request_id string

    請求唯一標識。可用於請求明細溯源和問題排查。

    錯誤碼

    如果模型調用失敗並返回報錯資訊，請參見錯誤資訊進行解決。