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、55 秒
66 秒
7、88 秒
9、1010 秒
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
modelmuse-video
status任务状态
progress进度 0–100,仅供参考,判断完成看 status
created_at创建时间(Unix 秒)
completed_at完成时间(Unix 秒)
seconds你请求的秒数(= 计费秒数),不是实际时长
size出片尺寸
video_url完成后才有:成片链接(不需要密钥)
expires_atvideo_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(不扣费、不创建任务)
情况提示中会出现
没写 promptprompt 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 小时,请尽快转存到你自己的存储。

同类文章