API 文档

视频生成车站 · 万相 3.0 视频生成 · 最后更新 2026-10-20
① 快速开始（3 分钟跑通） ② 鉴权 ③ 提交任务 ④ 参考素材规则（重点） ④.5 文件上传接口（图在本地时用） ⑤ 提示词怎么写 ⑥ 查询任务 / 取成片 ⑦ 修改 / 取消任务 ⑧ 错误码 ⑨ 限制与计费

① 快速开始

三步就能出片：

# 1. 拿 token（登录后返回）
curl -X POST https://yuanmengstudio.com/vr/api/student/login \
  -H "Content-Type: application/json" \
  -d '{"name":"你的学员名","pass":"你的口令"}'
# → {"ok":true,"token":"xxxxx","name":"...","credits":1840}

# 2. 提交任务（带参考图）
#    ★ 参考图直接给公网 URL 是最优解：24ms 提交完，服务端零处理
#      （图在本地的话先 POST /api/upload 换成 URL，见 ④.5）
curl -X POST https://yuanmengstudio.com/vr/api/tasks \
  -H "Content-Type: application/json" \
  -H "X-Token: xxxxx" \
  -d '{
    "title": "海边日落",
    "prompt": "图1 里的人站在 图2 的海边，夕阳低垂。无台词。",
    "duration": 15,
    "ratio": "16:9",
    "resolution": "1080P",
    "audio": true,
    "refs": [
      "https://your-oss.com/person.jpg",
      "https://your-oss.com/beach.jpg"
    ]
  }'

# 3. 查询（每隔 30~60 秒查一次）
curl "https://yuanmengstudio.com/vr/api/tasks?pageSize=20" -H "X-Token: xxxxx"

② 鉴权

所有接口都要带 X-Token 头（登录接口除外）：

X-Token: 登录返回的 token
token 长期有效，丢了重新登录拿一个即可（不会扣次数）。

③ 提交任务 · POST /api/tasks

参数必填说明
prompt必填提示词，5~20000 字符。写法见 ⑤
title可选任务标题，方便你在列表里认
duration可选时长秒数，2~30 的整数，或 -1 让平台智能决定。传了参考视频时：视频时长 + 生成长度 ≤ 30 秒（见 ④）
ratio可选16:9 / 9:16 / 1:1 / 4:3 / 3:4 / adaptive
resolution可选480P / 720P / 1080P（同价，选高的不吃亏）
audio可选true 出声音（台词/BGM/音效），false 静音
promptExtend可选是否让平台「智能改写/扩写」你的提示词。默认 false（不扩写 = 完全按你写的原文生成）。
· 不传 = false，适合提示词已经写得很详细（推荐）
· 传 true = 平台在生成前先自动「智能改写」一遍提示词（会自己补充细节），但会多等 20–60 秒，且可能改掉你想强调的内容
· 平台官方默认值是 true，本站为贴合创作者原意已改为默认 false
cabin可选已废弃，不传即可。历史兼容字段，传任何值都不影响计费与排队（每次生成固定 1 次）
mode可选reference（默认，全模态参考）/ first_frame（首帧）/ first_last（首尾帧）
refs可选参考图数组（最多 10 张）。推荐直接传公网 URL（"https://..."），也可传 base64 或先用 /api/upload 换 URL。详见 ④
audioRefs可选参考音频数组（最多 5 段，总时长 ≤15 秒）
videoRefs可选参考视频数组（最多 5 段，总时长 ≤15 秒）
docFile可选文档（dataURI），≤100MB，格式 docx/doc/xlsx/xls/pptx/ppt/pdf/txt/md
docLink可选公开网页链接（无需登录）。与 docFile 二选一
firstFrame可选首帧图（dataURI），mode=first_frame 或 first_last 用
lastFrame可选尾帧图（dataURI），mode=first_last 用

返回

{"ok": true, "task": {"id":"T130", "status":"pending", "creditsCost":10, ...}}

④ 参考素材规则（重点，写错会白跑）

三种传法，选一种

传法写法什么时候用
① 直接给公网 URL
推荐		 "refs": ["https://your-cdn.com/a.jpg", "https://your-cdn.com/b.jpg"] 图已经在 OSS / CDN / 图床 / 任意公网空间
24 毫秒提交完，服务端零处理
② 先上传拿 URL 先 POST /api/upload 传文件 → 拿到 url → 放进 refs
见 ④.5		 图在本地、没有公网空间
③ base64 "refs": ["data:image/jpeg;base64,/9j/4AAQ..."] 一次性提交、图很小（<1MB）
首选「直接给公网 URL」，原因：
· 24 毫秒提交完（实测），base64 传 10 张大图要 80 秒以上
· 服务端不中转、不下载、不压缩、不转 base64，原样把链接交给模型
· 不占我们的带宽和内存，你传多少条都不会把服务器拖慢
· 画质无损——没有二次编码
· 唯一要求：链接必须公网可访问，且能存活到任务被调度（建议有效期 ≥2 小时）
强烈建议用 URL。原因：
· 请求体只有几十字节，秒提交
· base64 会让体积膨胀 33%：10 张 10MB 图 = 134MB 请求体，提交要等 1 分多钟
· base64 方式 10 张 20MB 图会超过服务器限制直接报 413（详见下面的上限说明）
· URL 方式服务端不中转、不压缩，原样交给模型，画质无损
用 URL 的硬要求：
· 必须 http:// 或 https:// 开头
· 必须公网可访问，不能带登录、不能是内网地址
· 链接要能存活到任务被调度（建议有效期 ≥2 小时）。任务提交后到真正生成最多间隔 1 小时，链接中途失效会导致出片失败
· 单张 ≤20MB

base64 方式的上限

单张大小10 张 base64 合计结果
500KB（建议压到）约 5MB✅ 秒提交
5MB约 67MB✅ 可提交（约 40 秒）
10MB约 134MB⚠️ 可提交但慢（约 80 秒）
15MB约 200MB⚠️ 正好临界
20MB约 266MB❌ 报 413
服务端会把超过 1MB 的图自动压到 1920px 长边（画质接近原图），但压缩发生在传输之后——传 26MB 的等待时间省不掉。所以 base64 方式请先把图压到 1920px 以内（任何看图软件都能做，单张约 500KB）。

⚠ 参考视频会占用时长额度

平台规则：参考视频时长 + 生成时长 ≤ 30 秒。

参考视频生成时长最多说明
不传视频30 秒可以拉满
5 秒25 秒
10 秒20 秒
15 秒（上限）15 秒参考视频本身也不能超过 15 秒
违反会怎样：提交时直接报错，不会扣次数；但如果绕过校验提交，平台会在生成阶段报 input_video_duration(9.5s) + duration(30.0s) = 39.5s exceeds 30s limit 并失败（次数会退回，但白等一场）。

其他素材也能用 URL

首帧 firstFrame、尾帧 lastFrame、音频 audioRefs、视频 videoRefs 同样支持公网 URL 或 base64，规则一样。

数量和大小

类型上限单文件
参考图 reference_image10 张≤20MB
参考音频 reference_audio5 段，合计 ≤15 秒≤15MB
参考视频 reference_video5 段，合计 ≤15 秒≤100MB
文档 file 或 网页 link二选一，各限 1 个文档 ≤100MB
单次总共最多 20 个素材（所有类型加起来）

怎么在提示词里指代素材

图片、视频、音频分别独立编号：
第 1 张图叫「图1」，第 2 张叫「图2」；
第 1 段视频叫「视频1」；第 1 段音频叫「音频1」。
视频不会占用图的编号（4 张图 + 2 段视频 = 图1~图4 + 视频1~视频2）。

官方示例写法：

视频1 抱着 图3，在 图4 的椅子上弹奏一首舒缓的乡村民谣，并说道："今天的阳光真好。"
图1 手中拿着 图2，路过 视频1，把手中的 图2 放到 视频1 旁边的桌子上。
⚠ 不写「图1」会怎样：模型自己猜哪张图是什么，容易用错图。
顺序决定编号：上传顺序就是编号顺序，改了顺序记得同步改提示词。

模式不能混用

首帧/首尾帧模式（first_frame / first_last）只能传首尾帧，不能同时传参考图/音频/视频/文档。
文档和网页也不能和首尾帧一起用。

④.5 文件上传接口

图在本地、又没有公网空间时用这个。上传一次拿到 URL，之后可以反复用于多条任务。

接口

POST https://yuanmengstudio.com/vr/api/upload
Content-Type: multipart/form-data
X-Token: 你的卡密
表单字段：file（单个文件）

示例

curl -X POST https://yuanmengstudio.com/vr/api/upload \
  -H "X-Token: xxxxx" \
  -F "file=@/path/to/person.jpg"

返回

{
  "ok": true,
  "fileId": "596f1c757eab9eb0af86076a2fde9f97.jpg",
  "url": "https://yuanmengstudio.com/vr/api/pub/596f1c757eab9eb0af86076a2fde9f97.jpg",
  "kind": "image",
  "size": 1127664,
  "kb": 1101
}

拿到的 url 直接放进 refs 即可：

{
  "prompt": "图1 里的人走进房间。无台词。",
  "refs": ["https://yuanmengstudio.com/vr/api/pub/596f1c...jpg"],
  "duration": 15
}

说明

项目说明
支持格式图片 jpg/jpeg/png/webp/gif、音频 mp3/wav/m4a/aac/ogg/amr、视频 mp4/mov/webm、文档 pdf/docx/doc/xlsx/xls/pptx/ppt/txt/md
大小上限图片 20MB、音频 15MB、视频 100MB、文档 100MB（官方标准）
自动压缩图片 >1MB 自动压到 1920px 长边（画质接近原图），大图上传后体积会小很多
URL 有效期长期有效（7 天浏览器缓存），同一张图可以反复用于多条任务
是否公开文件名是 32 位随机码，猜不到；只要不主动分享别人拿不到
为什么推荐这个而不是 base64：
· base64 会让体积膨胀 33%，19MB 的图变成 25.5MB 请求体
· 上传一次拿到 URL，提交 100 条任务只用传 1 次图；base64 要传 100 次
· 大图不会撞 413（分两次请求，都在各自限制内）

⑤ 提示词怎么写

纯画面一定要写「无台词」

不然模型可能自己加人声。想静音就写：无台词，无旁白。

台词直接写进提示词

男人抬头看向门口，说道："你终于来了。"
用中文引号包住台词原文，模型会直接生成原生人声（配合 audio:true）。
不要写书面符号：省略号「……」、破折号「——」真人口播说不出来，模型看到会把后面的话掐掉。要停顿就写「稍停」。

描述要有画面感

❌ 太抽象✅ 具体可拍
一个很漂亮的女孩二十岁出头的短发女孩，齐刘海，穿米白色针织衫
在跑站立、上身前倾 25°，右腿在前右脚掌着地，左腿在后
风景很美傍晚海边，夕阳贴近海平线，浪花拍在黑色礁石上溅起白沫

镜头语言

可以直接写：中景，镜头缓慢右移、特写，微微仰拍、全景俯拍。

官方文档

提示词进阶写法参考： 万相 3.0 视频生成官方文档

⑥ 查询任务 / 取成片

查列表 · GET /api/tasks

参数说明
page页码，从 1 开始
pageSize每页条数：20 / 50 / 100
daytoday（默认）/ yesterday / 7d / all / 具体日期 2026-10-19
{"ok":true, "tasks":[...], "total":749, "page":1, "pages":38,
 "counts":{"today":8,"yesterday":668,"d7":749,"all":749}, "remaining":1694}

任务状态

status含义
pending候车中（等攒够一车发走）
submitted已提交给平台，排队生成
running生成中
done完成，video 字段是成片地址
failed失败，看 failReason（次数已退）
cancelled已取消
排队是正常现象：任务按提交时间依次生成，队尾的可能要等几小时。只要状态不是 failed，就说明还在队列里。

取成片

// task.video 直接就是可播放地址（带签名，有效期长）
https://yuanmengstudio.com/vr/api/video/T130?dl=xxxxx

⑦ 修改 / 取消任务

只有 pending（候车中）且还没分配上车的任务能改/取消。已上车就改不了了。

修改 · POST /api/tasks/:id/update

curl -X POST https://yuanmengstudio.com/vr/api/tasks/T130/update \
  -H "Content-Type: application/json" -H "X-Token: xxx" \
  -d '{"title":"新标题","prompt":"新的提示词...","refs":[...]}'

可改：title / prompt / refs / params / mode

取消 · POST /api/tasks/:id/cancel

curl -X POST https://yuanmengstudio.com/vr/api/tasks/T130/cancel -H "X-Token: xxx"
# → {"ok":true, "credits":10}   ← 按实扣次数退回

⑧ 错误码

返回原因怎么办
未登录 / 401token 无效或过期重新登录
次数不足余额不够这一条补充次数后再提交
refs 超过 10 张参考图超限删到 10 张以内
文档和网页只能二选一同时传了 docFile 和 docLink删掉一个
这个文件的格式无法识别文件不是标准图片/音频/视频转成 jpg / mp3 / mp4
这段音频读不出时长编码不受支持转 mp3 或 wav（手机录音先导出）
任务 failed平台生成失败看 failReason；次数已退，改提示词重提
input_video_duration(Ns) + duration(Ms) = ... exceeds 30s limit参考视频 + 生成时长超过 30 秒把 duration 改成 30 - 视频时长 以内

⑨ 限制与计费

计费（次卡制，只记次数不记钱）

每条任务扣 1 次，与清晰度（480P / 720P / 1080P）、时长档无关，同价。

余额字段名仍是 credits（历史兼容），语义为剩余次数。任务取消或生成失败时，按任务实际扣减的次数原路退回。

排队规则

任务按提交时间先来先发（FIFO），系统按批次统一提交发车。任务提交后先「候车」，凑够一批才统一提交到平台生成，所以从提交到出片通常需要等待。加急需求请联系管理员调整。

实际出片时间取决于队列位置和素材复杂度，通常需要数小时。队列越短出得越快。

为什么我的任务一直在候车？
任务需要按批次统一发车，候车表示还在排队等待发车，不是卡住了。
发车之后也要等平台按顺序生成，任务状态会依次变成「排队生成」→「生成中」→「完成」。
只要状态不是「失败」，就说明任务还在正常队列里，耐心等就好。
提交前请检查：任务一旦发车就不能再修改或取消，提示词和素材务必先确认好。 不确定效果的话，先用一条短任务（5 秒）试水，满意再批量提交。

⑩ 图片生成（快速通道，独立计费）

除了「提交任务排队发车」，还有一个不用排队的快速通道，可以直接出图（也能出短视频）。 它走的是另一套额度池，按张计费、费用远低于视频，而且图片结果是永久链接（不会 24 小时过期）。

10.1 先查当前可用模型 · GET /api/free/models

不同时期可用的模型不一样（取决于池里还有没有额度），务必先查再调，不要写死模型名。

curl "https://yuanmengstudio.com/vr/api/free/models" -H "X-Token: 你的卡密"

返回（节选）：

{
  "ok": true,
  "models": [
    {
      "model": "qwen-image-2.0-pro",
      "kind": "image",              // image=出图，video=出片
      "label": "高质量大图 2048",
      "credits": 0.02,              // 每张扣多少次
      "ref": "images-opt",          // none=不要参考图 / images-opt=可选 / images=必须
      "maxImg": 2,                  // 最多几张参考图
      "sizes": ["1024*1024", "2048*1152", "..."]   // 可选尺寸（星号格式）
    }
  ],
  "credits": 1234.5
}
规则：ref=none 的模型不接受参考图；ref=images 的必须带图；sizes 为空表示该模型不接受 size 参数（走平台默认）。

10.2 出图 · POST /api/free/image

curl -X POST https://yuanmengstudio.com/vr/api/free/image \
  -H "X-Token: 你的卡密" -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0-pro",
    "prompt": "一只橘猫坐在窗台上，午后阳光，浅景深",
    "size": "2048*1152",
    "images": ["https://.../参考图.jpg"]
  }'
字段必填说明
model否默认 qwen-image-2.0-pro；必须是 /api/free/models 里 kind=image 的模型
prompt是提示词
size否格式是星号 1024*1024（不是字母 x），且必须在该模型 sizes 白名单里
images视模型参考图 URL 数组（先用 ④.5 上传接口 拿 URL），最多 4 张、按模型 maxImg 限制

返回：

{
  "ok": true,
  "model": "qwen-image-2.0-pro",
  "url": "https://yuanmeng-agent-updates-002.oss-cn-shanghai.aliyuncs.com/vr-refs/freeimg-1793....png",
  "creditsUsed": 0.02,
  "ms": 41200,
  "credits": 1234.48
}
url 是永久链接（已转存到对象存储），不像视频成片只有 24 小时，可以放心存库。
出图通常 10~60 秒；后端总预算 150 秒，超时会自动换下一把 key 重试。

10.3 出短视频 · POST /api/free/video

同一套通道，参数多一个 duration（秒）和 size（如 1280*720）， 按模型的 ref 可能要 images（首帧/参考图）或 videoUrl（参考视频）。 视频按秒/按条扣得比图片贵得多（见 /api/free/models 的 credits 与 quotaUnit）， 排队时间也长，量大仍建议走「提交任务」通道。

关于这个快速通道的真实情况（先说清，免得误会）：它用的是平台免费额度池， 额度是一次性的，撞到某个账号没额度时系统会自动换下一把 key（一次请求最多试 20 把、跨 20 个不同账号）。 所以它不是无限量供应：能出就出，全池都撞完会返回「出片失败（已退回 N 次）」。 失败会自动退次，不会白扣。
视频生成车站 · 万相 3.0 · 有问题联系管理员