可用模型（测试中）#
| 模型 | 时长 | 是否需要seconds | 状态 |
|---|
| Minimax-H3-768p-933-10s | 固定 10 秒 | 不需要 | 可用 |
| Minimax-H3-768p-933-15s | 固定 15 秒 | 不需要 | 可用 |
| Minimax-H3-768p-933-10s-15s | 10–15 秒可变 | 需要，按秒计费 | 暂未开放 |
上游存在 Minimax-H3-768p-933-10s-15s（10–15 秒任意时长、按秒计费）档位，当前没有配置可用渠道。请求它会返回 503 加 model_not_found：分组 minimax-h3 下模型 Minimax-H3-768p-933-10s-15s 无可用渠道（distributor）。请使用上表中两个固定档，或以 GET /v1/models 的实时返回为准。
Authorization: Bearer sk-你的APIKey
X-Api-Key 头不被接受，只用它会返回 401 未提供令牌。部分 SDK 默认发 X-Api-Key，接入时请确认发出的是 Authorization: Bearer。
快速开始#
只有 status 为 completed 时视频地址才可用。在那之前 metadata.url 是空串，不要拿它去下载。也不要用 completed_at 判断是否完成 —— 该字段在 queued 阶段就已经有值了，只有 status 是可靠依据。
接口一览#
| 方法 | 路径 | 说明 |
|---|
| POST | /v1/videos | 提交视频生成任务 |
| POST | /v1/videos/generations | 同上，Sora 风格别名，两个路径等价 |
| GET | /v1/videos/{task_id} | 查询任务状态，完成后返回视频地址 |
| GET | /v1/videos/{task_id}/content | 带鉴权代理下载视频本体 |
| GET | /v1/models | 该分组可用模型列表 |
GET /v1/videos（任务列表）和 DELETE /v1/videos/{task_id}（删除任务）不对外开放，调用返回 404 Invalid URL。请自行记录提交后拿到的 task_id。
请求参数#
| 参数 | 类型 | 必填 | 说明 |
|---|
| model | string | 是 | 模型档位，见上方可用模型表 |
| prompt | string | 是 | 视频内容描述，支持中文，建议 ≤2000 字；可用 @图片1 / @视频1 / @音频1 引用参考素材 |
| aspect_ratio | string | 否 | 画面比例，默认 16:9。上游支持 16:9、9:16、1:1、4:3、3:4、21:9、3:2、2:3 |
| seconds | integer | 否 | 仅可变时长档需要，取 10–15 整数。当前两个固定档由模型决定时长，传了也无效 |
| images | array | 否 | 参考图，≤9 张，公网 URL 或 base64 |
| metadata.video_urls | array | 否 | 参考视频，≤3 段，每段 ≤15 秒 |
| metadata.audio_urls | array | 否 | 参考音频，≤3 段，每段 ≤15 秒 |
分辨率固定 768p 档，不需要传 resolution 或 size。model、prompt、aspect_ratio（16:9）已实测验证。seconds、images、metadata.* 及其余比例值的约束来自上游文档，请求体原样转发、本站不做校验 —— 参数不合法时由上游返回错误。
多模态参考素材#
图片：≤9 张，提示词中用 @图片1 ~ @图片9 引用
视频：≤3 段（每段 ≤15 秒），用 @视频1 ~ @视频3 引用
音频：≤3 段（每段 ≤15 秒），用 @音频1 ~ @音频3 引用
提交响应#
id 与 task_id 值相同，任取其一用于后续查询。查询与状态流转#
curl "https://api.tsbys.com/v1/videos/task_xxx" -H "Authorization: Bearer $KEY"| status | progress | 含义 |
|---|
| queued | 0 | 已入队，等待上游排期 |
| in_progress | 0–98 | 正在生成 |
| in_progress | 99 | 上游已出片，正在把视频转存到自有存储（此阶段仍不返回地址） |
| completed | 100 | 视频已就绪，metadata.url 可直接下载 |
| failed | -- | 失败，查看 error 字段 |
progress=99 是本站特有的「转存期」。这一设计保证了：只要拿到 completed，地址就一定能下载，不存在链接已返回但文件还没就绪的中间态。
完成后的响应：顶层 url 与 metadata.url 值相同，兼容两种取值习惯。响应中不包含 seconds 和 size 字段，请勿依赖它们。下载视频#
| 方式 | 地址 | 鉴权 | 适用场景 |
|---|
| 直链 | metadata.url | 不需要 | 交给浏览器、播放器、CDN 或前端直接播放 |
| 代理下载 | /v1/videos/{task_id}/content | 需要 | 不想暴露存储域名， 或希望统一走 API 鉴权 |
两种方式都支持 Range 断点续传与拖动进度条（返回 206），响应头带 Content-Type: video/mp4 和 Accept-Ranges: bytes。出片的 MP4 文件 ftyp brand 为 qt（QuickTime），这是 Minimax 的原始容器，扩展名与 Content-Type 均为 mp4。主流浏览器和播放器都能正常播放；个别严格的播放器如果挑剔，用 ffmpeg -i in.mp4 -c copy out.mp4 重新封装一次即可。
常见错误#
| 标题 | | |
|---|
| 401 | 无效的令牌 | API Key 错误或已禁用。检查 Authorization: Bearer 的值。 |
| 401 | 未提供令牌 | 没有发 Authorization 头。只发 X-Api-Key 也会命中这条。 |
| 503 | model_not_found | 无可用渠道（distributor）或模型名拼错，或该档位当前无可用渠道（如 10s-15s）。用 GET /v1/models 确认实时可用列表。 |
| 404 | Invalid URL | 调用了未开放的接口（任务列表、删除任务），或路径拼错。 |
| 400 | invalid_request | 缺少 prompt、参考素材合计超 12 个等参数问题。 |
| -- | status: failed | 任务已提交但生成失败，读 error.message。提示词触发内容审核也会走到这里。 |
每个响应都带 X-Oneapi-Request-Id 头，反馈问题时请一并提供该 ID。接入建议#
轮询间隔 1015 秒。10 秒档整体耗时通常在 56 分钟量级，更密的轮询没有意义。
设置超时上限。建议 15 分钟仍未到终态就按失败处理并告警。
只信 status。不要根据 progress 或 completed_at 推断完成。
及时转存。视频保留 7 天，需要长期留存请在自己这侧另存一份（已关闭）。
以 Minimax-H3-768p-933-10s 跑通完整链路：提交 3.1 秒返回 task_id；状态按 queued → in_progress(30) → in_progress(99) → completed(100) 推进；端到端 350 秒（约 5 分 50 秒）出片。返回地址为 videos.tsbys.com 下的日期分目录，实测下载 2.95 MB（3,095,685 字节）合法 MP4，免鉴权、支持 Range（206）；/content 代理下载字节数与直链一致。Minimax-H3-768p-933-15s 在模型列表中可见但本次未跑；10s-15s 档确认无可用渠道。
