萬相 3.0 與快樂馬影片 API

Essevin 上的阿里百煉影片生成——萬相 3.0 全能參考最長 30 秒,快樂馬 1.1 文生 / 圖生 / 參考生影片,僅按成片計費。

Essevin 以阿里自家的 DashScope 契約接入阿里雲百煉影片生成,並保持原始路徑。用阿里官方 SDK 或 HTTP 寫好的程式碼遷移過來只需改 base URL 與密鑰——請求體、回應結構、路徑都不用動。

兩個模型系列都是非同步的:提交任務後輪詢 Essevin 任務 ID。請使用已開通阿里分組的密鑰,並在發起付費任務前用 GET /v1/models 確認可用性。

端點

方法	路徑	用途
POST	`/api/v1/services/aigc/video-generation/video-synthesis`	提交萬相 3.0 或快樂馬影片任務
GET	`/api/v1/tasks/{task_id}`	查詢單一任務

所有請求使用 Authorization: Bearer sk-your-key 與 Content-Type: application/json。你不需要送出 X-DashScope-Async——閘道向上游一律以非同步方式請求。

請求體嚴格解碼:未知欄位與第二個 JSON 值會在呼叫上游前就被拒絕。這是刻意的。上游在提交階段幾乎不校驗參數,只在執行期才失敗——一個非法的 resolution 照樣會回傳任務 ID,約十分鐘後才報錯。Essevin 會直接以 400 當場拒絕。

模型

模型 ID	時長	解析度	輸入
`wan3.0-video`	2-30 秒整數(預設 5),或 `-1` 表示自動	`480P` / `720P` / `1080P`	首幀 / 尾幀,或最多 10 張參考圖、5 段參考影片、5 段參考音訊、1 個文件、1 個網頁連結
`happyhorse-1.1-t2v`	3-15 秒整數(預設 5)	`480P` / `720P` / `1080P`	僅提示詞
`happyhorse-1.1-i2v`	3-15 秒整數(預設 5)	`480P` / `720P` / `1080P`	恰好 1 張 `first_frame` 圖片
`happyhorse-1.1-r2v`	3-15 秒整數(預設 5)	`480P` / `720P` / `1080P`	1-9 張 `reference_image` 圖片

請使用上表中的精確 ID。未登記任何別名,未知模型名會被拒絕。wan3.0-video-prime、happyhorse-1.1-video-edit 以及快樂馬 1.0 系列均未上架。

請求契約

{
  "model": "wan3.0-video",
  "input": { "prompt": "...", "media": [{ "type": "first_frame", "url": "..." }] },
  "parameters": { "resolution": "1080P", "duration": 5 }
}

`input`

prompt 是否必填逐模型不同,與阿里自身契約一致:

模型	`prompt`
`wan3.0-video`	條件必選 —— `prompt` 與 `media` 必填其一
`happyhorse-1.1-t2v`	必選
`happyhorse-1.1-i2v`	選填 —— 純首幀圖即可驅動
`happyhorse-1.1-r2v`	必選

長度:萬相 3.0 最多 20,000 字元;快樂馬最多 5,000 個非中文字元(中文實際被上游限到 2,500)。阿里對超長是靜默截斷;Essevin 對超過該模型官方上限的 prompt 直接回傳 400,而不是放行一個會被悄悄改寫的請求。

media 每一項都帶 type 與 url:

`type`	萬相 3.0	快樂馬
`first_frame`	1	僅 `-i2v`,必填
`last_frame`	1	不接受
`reference_image`	最多 10	僅 `-r2v`,必填 1-9
`reference_video`	最多 5,合計 ≤15 秒	不接受
`reference_audio`	最多 5,合計 ≤15 秒	不接受
`file`	1 個文件(docx / doc / xlsx / xls / pptx / ppt / pdf / txt / key / pages / numbers / md;≤100 MB、≤50 頁)	不接受
`link`	1 個公開網頁	不接受

對萬相 3.0,首尾幀輸入與參考組(reference_*、file、link)在同一次請求中互斥,且 file 與 link 彼此也互斥。有參考影片時,阿里還要求輸入影片總時長 + 輸出時長 ≤ 30 秒;閘道量不到你的輸入片長,這條由上游判定。

url 接受絕對的公網 http(s) 位址或 data: 內嵌(base64)。oss:// 會被拒絕——該物件歸屬你自己的阿里雲帳號,閘道無法代取。link 必須是真實網頁位址,不能是 data: 內嵌。

`parameters`

欄位	萬相 3.0	快樂馬 1.1
`resolution`	`480P` / `720P` / `1080P`(預設 `1080P`)	同左
`duration`	選填;2-30,預設 5,或 `-1` 表示自動	選填;3-15,預設 5
`ratio`	`adaptive` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16`	`16:9` / `9:16` / `1:1` / `4:3` / `3:4` / `4:5` / `5:4` / `9:21` / `21:9`;`-i2v` 不接受,成片比例隨輸入圖
`audio`	布林,上游預設 `true`(開關聲音價格相同)	不接受
`prompt_extend`	布林,上游預設 `true`	不接受
`watermark`	布林,上游預設 `false`	布林,上游預設 `true`
`seed`	整數 0-2147483647	同左

模型不支援的參數會被拒絕而不是靜默丟棄,避免出現「以為生效了其實沒有」的情況。你沒傳的欄位完全不會送往上游——阿里自己的預設值原樣生效。

快樂馬預設帶浮水印

阿里對快樂馬 watermark 的預設值是 true,會在成片上打「Happy Horse」標記。Essevin 不覆蓋上游預設值。需要乾淨輸出請顯式傳 "watermark": false。

範例 —— 文生影片

curl https://api.essevin.com/api/v1/services/aigc/video-generation/video-synthesis \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "input": { "prompt": "日出時分航拍雲海之上的雪山" },
    "parameters": { "resolution": "1080P", "duration": 5, "ratio": "16:9" }
  }'

提交回傳阿里回應結構中的 Essevin 任務 ID:

{ "output": { "task_id": "blt60x4115010d-d361-4bfc-b131-a382f1c400a5", "task_status": "PENDING" }, "request_id": "..." }

範例 —— 圖生影片

{
  "model": "happyhorse-1.1-i2v",
  "input": {
    "prompt": "鏡頭緩緩推進,光影在場景中流動",
    "media": [{ "type": "first_frame", "url": "data:image/jpeg;base64,..." }]
  },
  "parameters": { "resolution": "720P", "duration": 5, "watermark": false }
}

用穩定的圖床或 data: 內嵌

參考素材由上游下載,而不是 Essevin 下載。屏蔽機房 IP 的圖床(很多免費圖床都會)會讓任務在提交幾分鐘後失敗。建議用 data: 內嵌或你自己的 OSS / CDN。

任務生命週期

輪詢 GET /api/v1/tasks/{task_id}。output.task_status 走 PENDING → RUNNING → SUCCEEDED | FAILED。一條片子通常 1-5 分鐘完成,萬相 3.0 的長片更久。建議約 15 秒輪詢一次。

成功時回應攜帶穩定的 Essevin 中繼位址(上游下載連結 24 小時過期,中繼會透明刷新):

{
  "output": {
    "task_id": "blt60x4115010d-d361-4bfc-b131-a382f1c400a5",
    "task_status": "SUCCEEDED",
    "video_url": "https://api.essevin.com/relay/...",
    "orig_prompt": "..."
  },
  "usage": { "video_count": 1, "duration": 5, "SR": 1080, "output_video_duration": 5, "input_video_duration": 0, "ratio": "16:9", "billed_seconds": 5, "billing_bucket": "1080p" }
}

usage.SR 是輸出短邊像素,決定計費檔;usage.ratio 回報的是成片實際比例,可能是原始尺寸(如 1632:937)而不是請求裡的列舉值。

失敗任務在 output.message 裡給出原因:

{ "output": { "task_id": "blt60x...", "task_status": "FAILED", "code": "TaskFailed", "message": "..." } }

計費

只有任務成功才計費,依據上游回報的用量:

輸出秒數按上游實際產出的檔位(usage.SR)計價,而不是按你請求的檔位。
萬相 3.0 還會計參考影片的輸入秒數,與輸出同檔價——阿里價目表把它列為「輸入和輸出單價」。快樂馬只計輸出秒數。
生成失敗或命中安全審核不計費,也不會產生用量記錄。

官方牌價見價格頁;你的實際費率以登入後的模型目錄為準。

本頁目錄