跳至主要内容

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 中给出实际扣费。生成失败会退还 Gems;因 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,提交请求,然后轮询直到完成。把 URL 中的 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. 提交生成任务

    携带 Authorization: Bearer 请求头,向 https://api.mage.space/v1/{model}/generate 发送 JSON 格式的 POST 请求。接口会立即返回 request_id、status 和 status_url。请附上 Idempotency-Key 请求头,这样重试时不会重复扣费。

  3. 轮询并下载

    持续轮询 status_url,直到状态变为 completed、failed 或 cancelled。请求完成后,result.url 会提供图片、视频或音频文件,文件保留 30 天。

为生产环境而生

每个 Mage API 请求都享有

  • 一个密钥,通用所有模型

    一个 REST API、一个 Gems 余额,即可使用 37 个图片、视频和音频模型。只需修改 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 支持图生视频吗?
支持。图生视频模型接受首帧,部分模型还接受尾帧或参考图,格式可以是 URL、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。每个模型页面都会列出默认设置下的价格,每次响应也会返回实际扣费金额。生成失败会退还 Gems;因违反 Mage 内容政策而被拦截的则不予退还。如果你的余额不足以支付某次请求,该请求会在扣费前被拒绝。
使用 API 需要 Mage 会员吗?
不能。API 只能使用 Gems。会员套餐及其应用内无限生成不适用于 API 请求。账号需要先成功付款一次,购买任意 Gem 包或套餐均可;注册赠送的 Gems 仅限在 Mage 应用内使用。
API 生成的内容可以商用吗?
可以。你用 Mage 创作的内容(包括通过 API 和 MCP 服务器生成的内容)可用于商业用途。署名我们会很感谢,但不是必须的。
速率限制是多少?
一个账号最多可同时有 20 个生成任务处于排队或运行中。超出后提交会被以 429 拒绝,且不会扣费。如需根据你的使用场景提高上限,请发邮件至 [email protected]。
我的 AI 智能体可以使用 Mage API 吗?
可以。智能体可以使用密钥调用 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,把 Mage 密钥作为 Bearer 令牌发送,并按模型页面映射你的字段:prompt、aspect_ratio、resolution、duration 和 model_id 在所有 Mage 模型中的用法一致。请求是异步的,所以先提交,再轮询 status_url。

用 Mage 开始开发

一个账号,一份 Gems 余额,畅用所有模型。按生成量付费,用多少付多少。

Characters社区