Muse Video · 完整接入文档
muse-video 是 Meta Muse 视频模型,支持用文字或图片生成带声音的 720P 视频,单条 4 到 180 秒。接口与 OpenAI 视频接口格式一致(POST /v1/videos),异步三步:提交任务 → 查询状态 → 下载视频。
1. 接入信息
| 项目 | 值 |
|---|---|
| 接口根地址 | https://api.a7w.cn/api/v1 |
| 提交视频 | POST https://api.a7w.cn/api/v1/videos |
| 查询任务 | GET https://api.a7w.cn/api/v1/videos/{id} |
| 鉴权请求头 | Authorization: Bearer <你的 API 密钥> |
| 模型名 | muse-video |
密钥在控制台「API 密钥」里创建,只放在服务端,不要写进前端代码。
兼容路径:POST /api/v1/videos/generations与/api/v1/videos等价,两者都能用。
2. 快速开始
第 1 步:提交任务
curl https://api.a7w.cn/api/v1/videos \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "muse-video",
"prompt": "金色的枫叶在微风中飘落,阳光穿过树梢,电影感",
"seconds": "5",
"size": "1280x720"
}'
返回任务 ID(task_ 开头):
{
"id": "task_9xQe2Lm7Vb4R...",
"object": "video",
"model": "muse-video",
"status": "queued",
"progress": 0,
"created_at": 1793962453
}
第 2 步:每 10–15 秒查询一次,直到 status 为 completed 或 failed
curl https://api.a7w.cn/api/v1/videos/task_9xQe2Lm7Vb4R... \
-H "Authorization: Bearer $API_KEY"
第 3 步:下载视频(用返回的 video_url,浏览器/播放器可直接打开)
curl -o out.mp4 "https://cdn3.saasos.cn/vr/xxxx.mp4"
出片时间(提交到 completed):
| 请求秒数 | 一般耗时 |
|---|---|
| 4–10 秒 | 1.5–2.5 分钟,慢的 4 分钟左右 |
| 11–30 秒 | 3–5.5 分钟,慢的 7 分钟左右 |
| 31–60 秒 | 5–13 分钟 |
| 61–180 秒 | 8–15 分钟 |
高峰排队会更久。程序里的等待上限建议设 60 分钟;到上限任务可能仍在生成,继续用同一个 id 查询,不要重新提交(重新提交会再扣一次费)。
3. 创建任务
POST /api/v1/videos,请求体 JSON。只上传一张本地首帧图时,也可以用 multipart/form-data。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
model | 是 | 固定 muse-video |
prompt | 是 | 画面描述,中英文都行,最多 4000 字 |
seconds | 否 | 视频秒数,4–180 的整数,字符串或数字都行;不填按 4 秒 |
size | 否 | 1280x720(横屏)或 720x1280(竖屏);不填出横屏,建议总是填 |
input_reference | 否 | 首帧图,一张。JSON 里传图片 URL 或 data URL;multipart 里直接传文件 |
images | 否 | 多张参考图,最多 4 张:第 1 张是开头画面,其余当人物/场景/画风参考;只能用 JSON 传,值是图片 URL 或 data URL 数组 |
resolution | 否 | 只能是 720p,可以不传 |
秒数与实际时长
seconds 填 4–180 之间任何整数都行,按填的秒数收费;出片时长往上凑到最近一档,不会比买的短:
| 请求秒数 | 实际出片 |
|---|---|
| 4、5 | 5 秒 |
| 6 | 6 秒 |
| 7、8 | 8 秒 |
| 9、10 | 10 秒 |
| 11 以上 | 往上凑到 5 的倍数(11–15 → 15 秒,16–20 → 20 秒 …… 176–180 → 180 秒) |
即 5、6、8、10 秒,以及 15–180 之间 5 的倍数,出多少就是多少。填 4、7、9、11 也能用,只是出片比买的长一点,钱按填的算。
小于 4、大于 180 或带小数(如 8.5)返回 HTTP 400,不扣费。
镜头结构
- 10 秒以内:一个连续镜头;
- 11–60 秒:分成每段 5–10 秒生成,后一段从前一段最后一帧接着拍,最后拼成一条,接缝处画面连续;提示词里写「硬切」「分镜」多半会变成长镜头里的运镜和转场;
- 61–180 秒:分成 2–3 部分同时生成,每部分 ≤60 秒且尽量等长(90 秒 = 45+45,120 秒 = 60+60,180 秒 = 60+60+60),再按顺序拼接。部分之间会换镜头,人物外貌/服装/场景可能有变化;需要人物一致时请传参考图,每一部分都会用同一组参考图。
横屏还是竖屏
size | 画面 |
|---|---|
1280x720 | 横屏 16:9(不填默认) |
720x1280 | 竖屏 9:16 |
只支持这两种。不支持方形,也不支持 1080P 及以上。
图片输入
- 一张图:用
input_reference,这张图就是首帧,视频从它开始动; - 多张图:用 JSON 的
images数组,最多 4 张。第 1 张是开头画面,第 2–4 张是参考图(人物长相、衣服、场景、画风、配色);最后一张不会当结尾画面; - multipart 只能传一个
input_reference文件;要传多张本地图片,请转成 data URL 放进 JSON 的images; - 多张图全放进
images,不要再另传input_reference; - 支持 PNG、JPEG、WebP;可传图片 URL 或 data URL(
data:image/jpeg;base64,<内容>),不支持文件 ID; - 图片 URL 必须公网可直接打开,不能是内网地址或需登录的地址;带签名的临时链接要确认提交时未过期;
- 单张 ≤10 MB,合计 ≤24 MB;data URL 比原图大约 1/3,图尽量先压小;
- 首帧图横竖要和
size一致(竖图配720x1280,横图配1280x720); - 传图不加价,价格和文生视频一样。
示例:图生视频(JSON 传图片 URL)
curl https://api.a7w.cn/api/v1/videos \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "muse-video",
"prompt": "镜头缓慢推进,山间的云雾慢慢飘动,草地随风轻摇",
"seconds": "5",
"size": "1280x720",
"input_reference": "https://example.com/first-frame.jpg"
}'
示例:图生视频(multipart 直接传文件)
curl https://api.a7w.cn/api/v1/videos \
-H "Authorization: Bearer $API_KEY" \
-F model=muse-video \
-F prompt="镜头缓慢推进,山间的云雾慢慢飘动" \
-F seconds=5 \
-F size=1280x720 \
-F input_reference=@first-frame.jpg
每个字段只传一次,文件只能有一个 input_reference。
示例:竖屏 8 秒 + 首帧图
curl https://api.a7w.cn/api/v1/videos \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "muse-video",
"prompt": "女孩在海边转身走向镜头,海风吹起头发,镜头缓慢推近",
"seconds": "8",
"size": "720x1280",
"input_reference": "https://example.com/first-frame-portrait.jpg"
}'
出片 720×1280、正好 8 秒、带声音。
示例:多图参考(images 数组)
curl https://api.a7w.cn/api/v1/videos \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "muse-video",
"prompt": "镜头跟着人物走进森林小屋,人物照第二张图,画面色调照第三张图",
"seconds": "10",
"size": "1280x720",
"images": [
"https://example.com/first-frame.jpg",
"https://example.com/character.jpg",
"data:image/png;base64,<base64 内容>"
]
}'
示例:180 秒长片
curl https://api.a7w.cn/api/v1/videos \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "muse-video",
"prompt": "一位穿红色外套的年轻女孩的四季旅行,按时间顺序分三幕:第一幕,春天在樱花树下出发,夏天到了海边;第二幕,山间篝火的夜晚,秋天穿过枫林;第三幕,冬天登上雪山,最后坐火车回家,车窗外四季闪回。电影感,自然光",
"seconds": "180",
"size": "1280x720",
"images": ["https://example.com/girl-red-coat.jpg"]
}'
180 秒分三部分生成;提示词按时间顺序写清整个故事、分成三幕最合适;传一张人物图能让三部分人物更一致。
4. 查询任务
GET /api/v1/videos/{id}
状态
status | 含义 | 下一步 |
|---|---|---|
queued | 排队中 | 继续查 |
in_progress | 生成中,progress 是大致进度 | 继续查 |
completed | 完成 | 去下载 |
failed | 失败,暂扣金额全额退回 | 看 error.message,改一下再提交 |
unknown | 平台正在确认状态 | 继续查;确认前费用保持暂扣,不会重复扣费 |
返回字段
| 字段 | 说明 |
|---|---|
id | 任务 ID |
object | 固定 video |
model | muse-video |
status | 任务状态 |
progress | 进度 0–100,仅供参考,判断完成看 status |
created_at | 创建时间(Unix 秒) |
completed_at | 完成时间(Unix 秒) |
seconds | 你请求的秒数(= 计费秒数),不是实际时长 |
size | 出片尺寸 |
video_url | 完成后才有:成片链接(不需要密钥) |
expires_at | video_url 过期时间(Unix 秒) |
progress到 99 时平台在核对成片(时长、横竖),这时in_progress可能多持续几分钟;核对通过才变completed,成片不会比买的短。
返回示例(完成)
{
"id": "task_9xQe2Lm7Vb4R...",
"object": "video",
"model": "muse-video",
"status": "completed",
"progress": 100,
"created_at": 1793962453,
"completed_at": 1793962532,
"seconds": "5",
"size": "1280x720",
"video_url": "https://cdn3.saasos.cn/vr/xxxx.mp4",
"expires_at": 1794567332
}
返回示例(失败)
{
"id": "task_9xQe2Lm7Vb4R...",
"object": "video",
"model": "muse-video",
"status": "failed",
"error": { "code": "video_generation_failed", "message": "视频生成失败,请重试" }
}
5. 下载视频
- 直接用完成状态里的
video_url,不需要带密钥,在expires_at之前有效;适合交给播放器或下载工具; - 支持
Range请求,可续传、可拖动进度条; - 成片是 MP4、带声音;10 秒以内一般几 MB,60 秒几十 MB,180 秒可能超过 100 MB;
- 下载超时按文件大小给足(长片建议 10 分钟以上),边收边写盘,不要整个读进内存;
- 平台成品只保留 24 小时,出片后请尽快下载转存。
6. 计费
| 模型 | 能做 | 输出 | 时长 | 计费 |
|---|---|---|---|---|
muse-video | 文生视频、图生视频(首帧图或最多 4 张参考图) | 720P MP4,带声音 | 4–180 秒 | 11 点/秒(¥0.11) |
| 秒数 | 价格 | 秒数 | 价格 |
|---|---|---|---|
| 4 秒 | 44 点(¥0.44) | 10 秒 | 110 点(¥1.10) |
| 5 秒 | 55 点(¥0.55) | 15 秒 | 165 点(¥1.65) |
| 6 秒 | 66 点(¥0.66) | 30 秒 | 330 点(¥3.30) |
| 8 秒 | 88 点(¥0.88) | 60 秒 | 660 点(¥6.60) |
- 按请求秒数计费:费用 =
seconds× 11 点;seconds填几就收几秒,不填按 4 秒算; - 凑档不加钱:填 17 秒出 20 秒,只收 17 秒;
- 传图不加钱:不传图、传 1 张、传 4 张价格一样;
- 提交时预扣:按请求秒数预扣,余额不足直接报错、不创建任务;
- 失败全额退回:任务失败(含成片不合格作废),预扣金额全额退回;
- 参数不对不扣费:秒数、尺寸、分辨率、图片不符合要求时直接 HTTP 400,不创建任务;
- 任务一旦创建就会跑完:客户端断开、等待超时都不影响任务,完成后照常结算;超时后请用
id继续查,不要重复提交。
7. Python 完整示例
import base64, os, time, requests
BASE = "https://api.a7w.cn/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}
def to_ref(src):
if src.startswith(("http://", "https://")):
return src
with open(src, "rb") as f:
blob = f.read()
mime = ("image/png" if blob[:4] == b"\x89PNG" else
"image/webp" if blob[8:12] == b"WEBP" else "image/jpeg")
return f"data:{mime};base64,{base64.b64encode(blob).decode()}"
def create(prompt, seconds=5, size="1280x720", first_frame=None, refs=None):
data = {"model": "muse-video", "prompt": prompt, "seconds": str(seconds), "size": size}
if refs:
data["images"] = [to_ref(x) for x in refs]
r = requests.post(f"{BASE}/videos", headers=HEADERS, json=data, timeout=120)
elif first_frame:
with open(first_frame, "rb") as f:
r = requests.post(f"{BASE}/videos", headers=HEADERS, data=data,
files={"input_reference": (os.path.basename(first_frame), f)}, timeout=120)
else:
r = requests.post(f"{BASE}/videos", headers=HEADERS, json=data, timeout=60)
if r.status_code != 200:
raise RuntimeError(f"提交失败 HTTP {r.status_code}: {r.text}")
return r.json()["id"]
def wait(video_id, every=15, limit=3600):
end = time.time() + limit
while time.time() < end:
r = requests.get(f"{BASE}/videos/{video_id}", headers=HEADERS, timeout=30)
if r.status_code >= 500:
time.sleep(every); continue
r.raise_for_status()
s = r.json()
if s["status"] == "completed":
return s
if s["status"] == "failed":
raise RuntimeError(s.get("error"))
time.sleep(every)
raise TimeoutError(f"{video_id} 还没完成,稍后用这个 id 继续查,不要重新提交")
def download(video_id, path):
s = wait(video_id)
url = s.get("video_url")
with requests.get(url, stream=True, timeout=900) as r:
r.raise_for_status()
with open(path, "wb") as f:
for chunk in r.iter_content(1 << 16):
f.write(chunk)
vid = create("金色的枫叶在微风中飘落,阳光穿过树梢,电影感", seconds=5)
print("task:", vid)
wait(vid)
download(vid, "maple.mp4")
print("saved maple.mp4")
- 图生视频(本地首帧):
create("镜头缓慢推进,云雾慢慢飘动", first_frame="first-frame.jpg") - 竖屏 8 秒:
create("镜头缓慢推进", seconds=8, size="720x1280", first_frame="portrait.jpg") - 多图参考:
create("女孩转身走向镜头,人物照第二张图", seconds=8, refs=["first.jpg", "https://example.com/character.jpg"])
8. 错误与排查
提交返回 400(不扣费、不创建任务)
| 情况 | 提示中会出现 |
|---|---|
| 没写 prompt | prompt is required |
| prompt 超 4000 字 | prompt 不能超过 4000 个字 |
| 秒数不在 4–180 或带小数 | seconds 只支持 4 到 180 的整数 |
| 要了 720p 以外分辨率 | muse-video 只出 720p |
| 尺寸不是 1280x720 / 720x1280 | 只支持横屏 1280x720 或竖屏 720x1280 |
| 图片传了文件 ID | 参考图要给图片 URL 或 data URL,不支持 file id |
| 图片格式不对 | 参考图只支持 png/jpeg/webp |
| 参考图超过 4 张 | 参考图最多 4 张 |
| 图片链接打不开/过期/非公网 | 第 N 张参考图…… 后接具体原因 |
| 单张 >10 MB 或合计 >24 MB | 超过 10 MiB / 参考图总大小超过 24 MiB |
任务失败(failed,预扣全额退回)
error.code | 原因 | 怎么办 |
|---|---|---|
video_generation_failed | 模型没出片:内容不合规、提示词与参数冲突、上游临时出错 | 改写提示词或稍后重试 |
video_rejected | 成片不合格(横竖不对、比买的短、没画面),已作废 | 直接重试 |
not_found | 任务记录丢失 | 重新提交 |
其他常见问题
- 余额不足:先充值再提交;
- 400
task_not_exist:任务 ID 不存在或不属于你的账户; - 提交返回 503:服务临时维护,几分钟内恢复,稍后重提;
- 查询偶尔 5xx:隔十几秒再查,任务不受影响;
- 下载报错:任务还没
completed,或已失败,先查状态。
9. 使用建议
- prompt 写清三件事:主体是什么、怎么动、镜头怎么走;
- 时长和横竖以参数为准:提示词里别写与
seconds、size矛盾的内容,否则模型可能反问而不出片(任务失败退款);首帧图横竖也要和size一致; - 多张图写清用处:第 1 张开头画面,其余作人物/场景/画风参考,prompt 里写明每张图干什么;
- 要准确时长就买整档:5、6、8、10 秒,以及 15–180 之间 5 的倍数,出多少就是多少;
- 60 秒以内适合一个连贯场景:写清场景和镜头运动,比写分镜效果好;
- 60 秒以上按时间顺序写故事:120 秒写前后两半,180 秒写三幕,人物要一致就传人物参考图;
- 长片多等一会:30 秒以上通常 5–15 分钟;轮询间隔 15 秒,上限 60 分钟;
- 任务多时会排队:
queued会久一点,耐心多查几次; - 及时下载:平台成品只保留 24 小时,请尽快转存到你自己的存储。