跳至主要內容

Mage API · 影片生成

AI 影片生成 API,支援文字與圖片輸入

15 個模型支援文字生成影片、圖片生成影片、首尾影格生成影片與參考素材生成影片,由 Mage 旗艦模型 Cherry 2 Pro 領軍,許多影片還能附帶音訊。

POST https://api.mage.space/v1/{model}/generate

重點速覽

Mage 影片生成 API 是位於 https://api.mage.space/v1 的 REST API,可執行 15 個文字生成影片與圖片生成影片模型,包括 Cherry 2 Pro、Lemon、Plum、Melon、MiniMax-H3、Grok Video 和 Wan。提交提示詞,並可選擇搭配影格或參考素材,輪詢請求狀態後即可下載 MP4。每支影片依模型、解析度和長度以 Gems 計費。

  • 15個影片模型
  • $0.02預設最低價,每支影片
  • 20同時生成數
  • $0月費

模型

Mage API 的所有影片模型

價格以每次生成計算,單位為 Gems。標準包 1,000 Gems 為 $1,較大的方案包會加贈 Gems。價格取決於模型、解析度和時長;此處顯示的是預設設定下的價格,每個回應都會在 billing.gems_charged 中回報實際扣款。生成失敗會退款;被 Mage 內容政策封鎖的則不會退款。

模型最適合model_id 值預設價格
Berry忠實呈現你參考素材的影片berry, berry-2189 Gems ($0.189)
Blueberry鎖定首尾影格blueberry, blueberry-v2360 Gems ($0.36)
Cherry我們的旗艦影片系列cherry-mini, cherry, cherry-pro, cherry-2, cherry-2-pro618 Gems ($0.618)
Grok Video動起來的 Grok Imaginegrok-imagine-video375 Gems ($0.375)
Kiwi日常影片,免設定kiwi270 Gems ($0.27)
Lemon完整影片功能,價格更親民lemon245 Gems ($0.245)
LTX Video適合反覆調整的快速開放權重影片模型ltx-video-096-distilled, ltx-video-096-dev20 Gems ($0.02)
Magejutsu重新演繹任何影片,並保留原有動態magejutsu, magejutsu-lite, magejutsu-feather1,856 Gems ($1.856)
Melon動態動漫,可選配音訊melon, melon-pro147 Gems ($0.147)
MiniMax-H3快速開放式影片,支援立體聲minimax-h3-turbo, pika-h3-flex, minimax-h345 Gems ($0.045)
Plum每支影片都有聲音,最高 2Kplum, plum-max, plum-fast173 Gems ($0.173)
Raspberry從首張影格讓角色活起來raspberry360 Gems ($0.36)
SeedanceSeedance,內容過濾較為嚴格seedance-2.0-mini, seedance-2.0-fast, seedance-2.0, seedance-2.5-flash, seedance-2.5618 Gems ($0.618)
Wan 3.0Wan 3.0,內容過濾嚴格wan-3.0245 Gems ($0.245)
Wan Video v2.2開放權重影片模型,提供 Lightning 版本wan22-video, wan22-video-lightning40 Gems ($0.04)

快速開始

使用 Berry 2 生成影片

設定 MAGE_API_KEY、送出請求,然後輪詢直到完成。把網址中的 berry 換成上方任一模型即可。

cURL
STATUS_URL=$(curl --request POST 'https://api.mage.space/v1/berry/generate' \
  --header "Authorization: Bearer $MAGE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "A slow push-in on a lighthouse at dusk, waves breaking below",
  "aspect_ratio": "16:9",
  "duration": "3",
  "model_id": "berry-2"
}' | jq -r '.status_url')

# Repeat until status is "completed"; result.url is the file
curl "$STATUS_URL" --header "Authorization: Bearer $MAGE_API_KEY"
TypeScript
// npm install @mage-space/sdk
import Mage from '@mage-space/sdk';

const mage = new Mage(); // reads MAGE_API_KEY

const request = await mage.run('berry', {
  prompt: 'A slow push-in on a lighthouse at dusk, waves breaking below',
  aspect_ratio: '16:9',
  duration: '3',
  model_id: 'berry-2',
});

console.log(request.result.url);
Python
# pip install mage-space
from mage_space import Mage

mage = Mage()  # reads MAGE_API_KEY

request = mage.run("berry", {
    "prompt": "A slow push-in on a lighthouse at dusk, waves breaking below",
    "aspect_ratio": "16:9",
    "duration": "3",
    "model_id": "berry-2",
})

print(request["result"]["url"])

運作方式

從 API 金鑰到成品,只需三次呼叫

所有模型都使用同一套驗證機制、同一個非同步請求流程和相同的欄位名稱。

  1. 建立 API 金鑰

    登入 Mage,開啟 API → API Keys 並建立金鑰。金鑰以 mage_sk_ 開頭,只會顯示一次。每個帳號最多可有 10 組啟用中的金鑰。

  2. 提交生成請求

    以 POST 方式將 JSON 內容傳送到 https://api.mage.space/v1/{model}/generate,並帶上 Authorization: Bearer 標頭。回應會立即傳回 request_id、status 和 status_url。請附上 Idempotency-Key 標頭,重試時就不會重複扣款。

  3. 輪詢並下載

    持續輪詢 status_url,直到狀態變成 completed、failed 或 cancelled。已完成的請求會包含 result.url,指向圖片、影片或音訊檔案,檔案會保存 30 天。

為正式上線打造

每個 Mage API 請求都享有的功能

  • 一組金鑰,通用所有模型

    37 款圖片、影片與音訊模型,共用一組 REST API 和一個 Gems 餘額。只要更改 URL 路徑即可切換模型。

  • 依生成次數計費

    無需訂閱,也沒有最低消費。你只要購買 Gems,每次請求就會依標示價格扣款。生成失敗會退還 Gems,但因違反 Mage 內容政策而被封鎖的除外。

  • 安全重試

    透過冪等鍵,重新送出的請求會回傳原本的結果,不會重複扣款。

  • 角色保持一致

    只要儲存一次角色或參考素材,之後在任何提示詞中輸入 @handle,就能搭配所有支援的模型使用。

  • 支援大型輸入檔案

    可用 URL 或 data URL 傳送圖片、影片和音訊,也可透過簽署上傳功能上傳最大 100 MB 的檔案。

  • 同時處理 20 個生成任務

    每個帳號可同時執行 20 個生成任務,也可以依你的使用情境調高上限。被拒絕的請求一律不會扣款。

使用情境

開發者用影片 API 打造什麼

  • 短影音與社群影片

    用提示詞或產品圖片,製作適用於 TikTok、Reels 和 Shorts 的直式影片。

  • 讓靜態圖片動起來

    使用 Lemon 與 Kiwi 等圖片生成影片模型,把首張影格或首尾影格變成動態影片。

  • 角色驅動的故事

    使用支援 @handle 角色的參考素材生成影片模型,讓同一個角色出現在不同鏡頭中。

  • 有聲影片

    Plum 與其他模型能隨畫面生成語音、音效與環境音,也支援以音訊參考指定聲音。

  • 廣告與產品展示

    生成多種廣告版本再挑出最佳的,冪等提交可確保絕不重複扣款。

  • 編輯現有影片

    Berry、Plum 與 Grok Video 可編輯你傳入的來源影片;Lemon 與 MiniMax-H3 也支援參考影片。

常見問題

常見問題

最好的 AI 影片生成 API 是哪一個?
在 Mage 上,影片預設使用 Cherry 2 Pro:支援角色、多張參考圖片、音訊參考,可輸出 480p 到 4K,影片長度最長 30 秒。如果想控制首尾影格,可以選 Lemon;想要生成帶聲音、最高 2K 的影片,可以選 Plum;想用較低成本製作草稿,則可以選 Cherry Mini 或 Wan。
影片 API 支援圖片生成影片嗎?
支援。圖片生成影片模型會接收首張影格,部分模型也接受末張影格或參考圖片,格式可以是網址、data URL 或上傳檔案。每個模型頁面都列出了支援的輸入內容,以及是否必須提供圖片。
生成的影片最長可以多長?
視模型和解析度而定。許多模型可生成 4 到 15 秒的影片,Cherry 2 Pro 和 Cherry 2 則可達 20、25 和 30 秒。各模型頁面都列有支援的長度。
生成一支影片需要多久?
依模型、解析度與長度而定。這個 API 採非同步運作:送出請求後,以退避機制輪詢 status_url,或讓你的 MCP 用戶端透過 get_request 等待結果。
Mage API 的費用是多少?
沒有訂閱制,也沒有月費。每次生成都依該模型的標示價格以 Gems 支付,標準方案中 1,000 Gems 為 $1。每個模型頁面都會列出預設設定下的價格,每次回應也會顯示實際扣款金額。生成失敗會退款;但被 Mage 內容政策封鎖的不會退款。若你的餘額不足以支付請求,系統會在扣款前直接拒絕。
使用 API 需要 Mage 會員資格嗎?
不行。API 只能使用 Gems。會員方案及其應用程式內的無限生成,並不適用於 API 請求。帳號需要先完成一次成功付款,購買任一 Gem 包或訂閱任一方案皆可;註冊贈送的 Gems 僅限在 Mage 應用程式中使用。
API 生成的內容可以商用嗎?
可以。你使用 Mage 建立的內容,包括透過 API 和 MCP 伺服器產生的內容,都可以用於商業用途。我們歡迎標示出處,但不強制要求。
速率限制是多少?
每個帳號最多可同時有 20 個生成任務排隊或執行中。超過上限的送出請求會被以 429 拒絕,且不會收費。如果你的使用情境需要更高的上限,請寫信到 [email protected]。
我的 AI Agent 可以使用 Mage API 嗎?
可以。Agent 可以使用金鑰呼叫 REST API,也可以連接 Mage MCP 伺服器,為 Claude、ChatGPT、Claude Code、Grok 和 Cursor 提供十六個現成工具,用來選擇模型、查詢價格、生成內容及取得結果。請參閱MCP 伺服器。
Mage API 有提供 SDK 嗎?
有。npm 上的官方 @mage-space/sdk 套件與 PyPI 上的 mage-space 皆為開源,並為每個模型提供型別定義。它們會幫你送出請求、等待結果、安全地重試,並上傳檔案。ComfyUI 使用者可以安裝 comfyui-mage 節點包。請參閱Mage SDK。
我已經在用其他生成 API,需要更改哪些地方?
將你的用戶端指向 https://api.mage.space/v1,以 Bearer token 的方式傳送你的 Mage 金鑰,並依照模型頁面對應你的欄位:prompt、aspect_ratio、resolution、duration 和 model_id 在所有 Mage 模型中的用法都相同。請求為非同步,因此請先送出,再輪詢 status_url。

開始使用 Mage 打造你的作品

一個帳號、一份 Gems 餘額,通用所有模型。只需為你生成的內容付費。

Characters社群