Muse Video 是 Meta 超级智能实验室(Meta Superintelligence Labs)的视频模型。在 APIMODELS 上它是统一视频端点里的一个模型名 muse-video:只传提示词就是文生视频;加一张首帧图,视频从这张图开始;或者加最多 4 张参考图,模型保留图里的人物或主体,但视频不从这些图开始。成片 4-30 秒,720p,16:9(1280×720)或 9:16(720×1280),H.264 MP4、24 fps。不支持的时长、尺寸和输入在建任务前直接返回 400;并非每次请求都能成功,生成失败不扣费。按请求秒数计费,每秒 $0.037。
Muse Video 能做什么、不能做什么,都在这张表里。接入前请逐条核对:只有 720p,只有横屏或竖屏,图片是 1 张首帧或最多 4 张参考图,二选一。
| 项目 | 支持 | 不支持 |
|---|---|---|
| 分辨率 | 只有 720p(resolution 传 "720p" 或不传) | 1080p、2K、4K、480p |
| 画幅 | 16:9 横屏 1280×720(默认)或 9:16 竖屏 720×1280 | 方形 1:1、4:3、3:4、21:9 及其他任何比例或尺寸 |
| 时长 | 4-30 的整数秒;5、6、8、10、15、20、25、30 秒精确出片,其他秒数向上取到下一档 | 少于 4 秒、多于 30 秒、带小数(如 8.5) |
| 图片 | 二选一:1 张首帧,或最多 4 张参考图(保留同一个人物或主体),不能同时传;PNG、JPEG 或 WebP,每张最大 20 MB,公网 URL 或 base64 | 首帧和参考图同时传、超过 4 张参考图、尾帧 |
| 视频 / 音频输入 | 无,图片是唯一的媒体输入 | 参考视频、视频编辑或续写、音频输入、按你的音频对口型 |
| 声音 | 由模型和画面一起生成;generate_audio: true 可以传 | 关闭声音(generate_audio: false 返回 400);也不保证每条都有声音 |
| 其他控制 | 提示词最多 4000 个字符,任何语言;运镜写在提示词里 | negative_prompt、seed(结果不可复现)、运镜参数 |
不支持的取值和字段在建任务前返回 400,不扣费;报错原文见下方「常见报错」。
Muse Video 的成功率不是 100%。请求通过参数校验、建好任务之后,仍然可能失败:
失败的任务状态为 failed,原因在 data.failMsg,不扣费。我们上线测试的两单都出了片,但两单远远不够说明成功率,所以我们不公布成功率。请按「偶尔会失败」来设计流程:临时错误重试,被拒的提示词改写后再发,不要假设第一次请求一定能拿到视频。
同一个模型名、同一个端点,按你传了什么图来区分。三种方式同价。
| 方式 | 传什么 | 模型怎么用 |
|---|---|---|
| 文生视频 | 只传 prompt | 画面全部按提示词生成。 |
| 首帧(图生视频) | prompt + 1 张图,放在 image_url(或 first_frame_url、image、input_reference) | 视频从这张图开始,提示词写接下来怎么动。 |
| 参考图 | prompt + 1-4 张图,放在 images(或 image_urls、reference_image_urls) | 模型保留图里的人物、主体或风格,但视频不从这些图开始,场景由提示词决定。适合在多条视频里用同一个角色。 |
首帧和参考图不能放在同一个请求里,同时传返回 400。图片数组(images、image_urls、reference_image_urls)哪怕只有一张,也一律按参考图处理;要传首帧,请用单图字段 image_url。
所有请求在 Header 携带 API Key:
Authorization: Bearer YOUR_API_KEYhttps://api.apimodels.app/v1/video/generations·GET/v1/video/generations?task_id=# Muse Video — text-to-video. model and prompt are required; everything else is optional.
# duration: whole seconds 4-30 (default 5). aspect_ratio: 16:9 (default, 1280x720) or 9:16 (720x1280).
# Billed $0.037 per requested second: this 10 s request is $0.37.
curl -X POST https://api.apimodels.app/v1/video/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "muse-video",
"prompt": "An orange cat stretches on a sunny windowsill, sunlight pours in, the camera slowly pushes in",
"duration": 10,
"aspect_ratio": "16:9"
}'
# Response (async — a task is created):
# { "code": 200, "msg": "success", "data": { "taskId": "clxxx", "state": "pending", "model": "muse-video" } }
# Poll every 10-15 s until completed (result files are kept 30 days)
curl "https://api.apimodels.app/v1/video/generations?task_id=TASK_ID" \
-H "Authorization: Bearer YOUR_API_KEY"
# { "code": 200, "data": { "state": "completed",
# "resultUrls": ["https://r2.apimodels.app/videos/clxxx.mp4"] } }同一个模型名、同一个端点,多传一张首帧图即可,价格和文生视频相同。Node.js 示例用的是 OpenAI 风格的字段名 seconds、size 和 input_reference,同样可用。
# Muse Video — image-to-video: the same request plus ONE first-frame image.
# PNG, JPEG or WebP, up to 20 MB, as a public URL or a base64 data URI.
# Same price as text-to-video. Use an image with the same orientation as the clip.
curl -X POST https://api.apimodels.app/v1/video/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "muse-video",
"prompt": "She turns toward the window and smiles, the curtains drift in the breeze, slow push-in",
"image_url": "https://example.com/first-frame-portrait.jpg",
"duration": 6,
"aspect_ratio": "9:16"
}'
# first_frame_url, image or input_reference work in place of image_url. Do not put a first frame in image_urls:
# an image array (images, image_urls, reference_image_urls) always means reference images, see the next example.
# Poll the returned taskId exactly as in the text-to-video example.要在多条视频里保留同一个人物或主体,把 1-4 张参考图放进 images(image_urls、reference_image_urls 也可)。模型保留图里的脸和样子,但视频不从任何一张参考图开始。提示词里点明「参考图里的这个人」,再写新场景。不能和首帧同时传,价格和文生视频相同。
# Muse Video — reference images: 1 to 4 images of the same person or subject in "images".
# The model keeps the face and look from them, but the clip does not start from any of them.
# image_urls and reference_image_urls work in place of images. Do not add a first frame to the same request.
# PNG, JPEG or WebP, up to 20 MB each, public URLs or base64 data URIs. Same price as text-to-video.
curl -X POST https://api.apimodels.app/v1/video/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "muse-video",
"prompt": "The same young woman from the reference images walks barefoot along a beach at sunset, smiling back at the camera, handheld vertical shot",
"images": [
"https://example.com/ref-1.jpg",
"https://example.com/ref-2.jpg",
"https://example.com/ref-3.jpg",
"https://example.com/ref-4.jpg"
],
"duration": 5,
"aspect_ratio": "9:16"
}'
# Poll the returned taskId exactly as in the text-to-video example.任务状态依次是 pending → processing → completed 或 failed。completed 时 data.resultUrls[0] 是 MP4;failed 时原因在 data.failMsg,不扣费。10 秒以内的片子通常 1-2 分钟出片,15-30 秒通常 3-7 分钟;我们上线测试的 4 秒请求约 1.5 分钟完成。每 10-15 秒轮询一次即可。
不想轮询就在创建请求里传 callback_url。任务到达 completed 或 failed 时,我们向这个地址发一个 HTTP POST(JSON)。投递失败会按指数退避重试,30 分钟内持续重试,直到你的接口返回 2xx。回调地址必须公网可达,localhost 和内网地址在创建时就返回 400。轮询接口照常可用。
POST {your callback_url}
Content-Type: application/json
{
"code": 200,
"msg": "success",
"data": {
"taskId": "clxxx...",
"model": "muse-video",
"state": "completed", // or "failed"
"param": "<JSON string>", // your request, JSON.parse once
"resultJson": "<JSON string> | null", // {"resultUrls": ["https://...mp4"]}, JSON.parse once
"failCode": null,
"failMsg": null
}
}| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| model | 是 | string | muse-video |
| prompt | 是 | string | 画面里发生什么,最多 4000 个字符,任何语言。图生视频同样必填。 |
| duration | 否 | number | string | 整数秒,4-30,默认 5;字符串或数字都行,OpenAI 风格的 seconds 也认。5、6、8、10、15、20、25、30 秒精确出片,其他秒数向上取到下一档(见下表)。 |
| aspect_ratio | 否 | string | 16:9(默认,1280×720)或 9:16(720×1280)。其他比例返回 400。 |
| size | 否 | string | 可代替 aspect_ratio:"1280x720" 或 "720x1280"。两个都传时必须一致。 |
| resolution | 否 | string | 可不传;只接受 "720p",其他值返回 400。 |
| image_url | 否 | string | 首帧图,只能一张,视频从这张图开始:公网 URL 或 base64 data URI,PNG、JPEG 或 WebP,最大 20 MB。也接受 first_frame_url、image、input_reference。不能和 images 同时传。 |
| images | 否 | string[] | 参考图,1-4 张:模型保留图里的人物、主体或风格,但视频不从这些图开始,适合固定角色。每张都是公网 URL 或 base64 data URI,PNG、JPEG 或 WebP,最大 20 MB。也接受 image_urls、reference_image_urls;数组只放一张也算参考图,不算首帧。不能和首帧同时传,超过 4 张返回 400。 |
| generate_audio | 否 | boolean | 可不传;只接受 true。有没有声音由模型决定,传 true 也不保证每条都有声音;传 false 返回 400(声音关不掉)。 |
| callback_url | 否 | string | 任务完成时我们向该地址 POST 结果;不传就轮询 GET 查询。 |
没有尾帧、参考视频和参考音频输入,也没有 negative_prompt 和 seed:传了会返回 400,不会被悄悄忽略。也没有运镜参数,镜头怎么动请写进提示词。
请求 5、6、8、10、15、20、25、30 秒,成片就是这么长;其他整数秒向上取到下一档,成片不会比你付费的秒数短。计费按请求的秒数,不按成片时长。
| 请求的 duration | 成片时长 |
|---|---|
| 4 / 5 秒 | 5 秒 |
| 6 秒 | 6 秒 |
| 7 / 8 秒 | 8 秒 |
| 9 / 10 秒 | 10 秒 |
| 11–15 秒 | 15 秒 |
| 16–20 秒 | 20 秒 |
| 21–25 秒 | 25 秒 |
| 26–30 秒 | 30 秒 |
一次参考图测试(2026-10-30)
我们发了四张同一位年轻女性的照片(靠在枕头上、微笑、比 V、捂嘴笑),提示词是 "The same young woman from the reference images walks barefoot along a beach at sunset, smiling back at the camera, handheld vertical shot",duration 4,aspect_ratio 9:16。88 秒后返回一条 5.0 秒、720×1280、带音轨的视频。视频一开始就在海滩上,没有从任何一张参考图开始。她还是同一张脸、同样的发型,衣服也相近(奶白色吊带变成了白色吊带裙),模型还用上了参考图里的动作:比 V 和捂嘴笑。5 秒里切了好几个镜头:特写、远景、背影、比 V、再回到特写。扣费和 4 秒的文生视频完全一样。这只是一次测试,不代表每次都会得到同样的结果。
| 请求秒数 | 成片时长 | 价格 |
|---|---|---|
| 每请求秒 | — | $0.037 |
| 4 秒 | 5 秒 | $0.148 |
| 5 秒(默认) | 5 秒 | $0.185 |
| 6 秒 | 6 秒 | $0.222 |
| 7 秒 | 8 秒 | $0.259 |
| 8 秒 | 8 秒 | $0.296 |
| 10 秒 | 10 秒 | $0.37 |
| 15 秒 | 15 秒 | $0.555 |
| 20 秒 | 20 秒 | $0.74 |
| 25 秒 | 25 秒 | $0.925 |
| 30 秒 | 30 秒 | $1.11 |
按请求的秒数计费:请求 4 秒收 $0.148,交回 5 秒的片子。带首帧或参考图不加价,三种方式同价。被 400 拒掉的请求不建任务、不扣费;生成失败不扣费。
参数问题在创建时同步返回 400({"code": 400, "msg": "..."}),不会建任务、不扣费。下表 msg 是当前原文;括号里的字段名是你实际发送的那个。
| msg | 原因 / 怎么改 |
|---|---|
prompt is required | 没传提示词,或只有空白。带首帧或参考图的请求也要提示词。 |
prompt must be at most 4000 characters | 提示词超过 4000 个字符,删短。 |
duration must be a whole number of seconds from 4 to 30 | duration(或 seconds)不在 4-30 之间、带小数,或不是数字。传整数秒;"10" 这样的字符串也可以。 |
muse-video outputs 720p only (resolution: 720p) | resolution 传了 1080p 等其他值。不传,或传 720p。 |
muse-video supports 16:9 (1280x720) or 9:16 (720x1280) only — set aspect_ratio to 16:9 or 9:16 | 传了其他比例或尺寸(如 1:1、1920x1080),或 aspect_ratio 和 size 不一致。 |
muse-video takes either a first frame (image_url) or reference images (images), not both | 同一个请求里既传了首帧(image_url、first_frame_url、image、input_reference),又传了参考图(images、image_urls、reference_image_urls)。二选一:要视频从这张图开始就只传首帧,要保留人物或主体就只传参考图。 |
muse-video takes at most 4 reference images (images / image_urls) | 参考图数组超过 4 张。最多留 4 张,挑最能代表这个人物或主体的。 |
muse-video does not support a last frame (last_frame_url) | 传了尾帧字段。Muse Video 没有尾帧,去掉它。 |
muse-video does not accept video or audio input (video_urls) | 传了视频或音频输入。Muse Video 只接受提示词,外加可选的一张首帧图或最多 4 张参考图。 |
muse-video does not support negative_prompt — describe what you want in prompt instead | 传了 negative_prompt。Muse Video 没有反向提示词:去掉它,把想要的画面正面写进 prompt。 |
muse-video does not support seed: results are not repeatable | 传了 seed。Muse Video 没有 seed,同一请求每次出的片子都不同;去掉它。 |
muse-video cannot turn sound off: the model decides whether a clip has sound | 传了 generate_audio: false。声音关不掉:去掉这个字段或传 true;需要无声视频就自己去掉音轨。 |
first-frame image must be PNG, JPEG or WebP;超过 20 MB 时为 first-frame image is larger than 20 MB。都不扣费。ffprobe -v error -select_streams a -show_entries stream=codec_name -of csv=p=0 clip.mp4:有音轨会输出 aac,没有则什么都不输出。试一试:Playground。
只有 720p(没有 1080p、2K、4K、480p),只有 16:9 横屏 1280×720 或 9:16 竖屏 720×1280(没有方形和其他比例)。时长为 4-30 的整数秒,5、6、8、10、15、20、25、30 秒精确出片,其他秒数向上取整。图片二选一:1 张首帧,或最多 4 张参考图(保留同一个人物或主体),不能同时传;PNG、JPEG 或 WebP,每张最大 20 MB;不支持尾帧。不接视频或音频输入,不能按你的音频对口型,不能编辑或续写视频。声音由模型生成,不保证每条都有,也关不掉。没有 negative_prompt、seed 和运镜参数,提示词最多 4000 个字符。不支持的字段在建任务前返回 400。成功率不是 100%:模型可能拒绝内容,生成可能遇到临时错误,横竖或时长不对的成片会被作废。失败的任务不扣费,我们也不公布成功率。
按请求秒数每秒 $0.037:5 秒(默认)$0.185,8 秒 $0.296,10 秒 $0.37,15 秒 $0.555,20 秒 $0.74,30 秒 $1.11。带首帧或参考图不加价。计费按请求的秒数:请求 4 秒收 $0.148,交回 5 秒的片子。被 400 拒掉的请求不建任务,生成失败不扣费。
成片时长按档位出。请求 5、6、8、10、15、20、25、30 秒,成片就是这么长;4-30 之间的其他整数秒向上取到下一档(4 → 5 秒、7 → 8 秒、11-14 → 15 秒、26-29 → 30 秒),成片不会比付费的秒数短。时长要紧时直接请求精确档位。
只有 720p 两种形状:16:9 的 1280×720(默认)和 9:16 的 720×1280,用 aspect_ratio 或 size 1280x720 / 720x1280 指定。没有方形和 1080p,请求了会在建任务前返回 400。输出是 H.264 MP4,24 fps。
在请求里加一张首帧图,字段 image_url(first_frame_url、image、input_reference 也可):公网 URL 或 base64 data URI,PNG、JPEG 或 WebP,最大 20 MB。视频从这张图开始,价格和文生视频相同。首帧最好和成片同方向;不支持尾帧。首帧不要放进 image_urls 数组:图片数组一律按参考图处理。
可以,用参考图。把 1-4 张这个人物或主体的图放进 images(image_urls、reference_image_urls 也可),不要和首帧同时传。模型保留脸和样子,但视频不从这些图开始,场景由提示词决定。2026-10-30 我们测了一次:四张同一位年轻女性的照片,提示词写她在日落的海滩上散步,88 秒返回一条 5.0 秒、720×1280、带音轨的视频:同一张脸、同样的发型、相近的衣服,还用上了照片里的动作。这只是一次测试,不代表每次都能做到。参考图不加价;超过 4 张返回 400。
Meta 介绍 Muse Video 会把声音和画面一起生成。我们上线测试时,横屏那条带 AAC 音轨,竖屏那条没有声音;流程需要音频的话,请检查每条成片有没有音轨。声音关不掉:generate_audio: false 会返回 400。