Skip to main content
GET
获取视频
GET /v1/videos/{video_id} 接受四类 ID 并返回当前持久化状态:渲染的 render_、H3 生成的 vid_、Viggle-Animate 生成的 anim_,以及视频 2 倍超分的 vsr_。每 3–5 秒轮询一次,直到进入终态。Render 来源的 ID 也支持监听渲染推送。 本接口替代已停用的 GET /v1/renders/{render_id}。
旧接口现返回 405 Method Not Allowed,而不是 404,因为该路径仍注册有其他方法。只有路径完全没有注册方法时才返回 404。如旧集成通过 404 判断接口已停用,请同时处理 405,或直接迁移到本接口。

请求参数

响应参数

返回 200 OK 和 Video 对象。
系统生成的 seed 是 63 位随机整数(0 到 2^63 − 1),几乎总是大于 Number.MAX_SAFE_INTEGER(2^53 − 1)。JavaScript 的 JSON.parse 会静默丢失精度——下方示例中的 4271960385017522688 会被读成另一个数,用它重新提交也无法复现同一视频。如需精确值,请使用支持 64 位整数的 JSON 解析器(例如 json-bigint),或在创建视频时自行传入不大于 2^53 − 1 的 seed。
本响应没有 links,因此不包含创建渲染响应中的 self、events、download 快捷链接。继续查询时使用同一 video_id;Render 来源的 ID 还可使用下载渲染结果。

完成时间

Render 来源的视频在 status 变为 ready 后,completed_at 可能延迟约 30 秒回填,并非永久缺失。判断视频是否完成,应检查 status == "ready" 或 video_url 是否有值,不应依赖 completed_at 非空。

Render 来源示例

H3 来源示例

角色动画来源示例

没有 seed 字段;该字段仅适用于 H3。queue_position 与 estimated_wait_seconds 两种来源都会返回,进入终态后为 null。

失败示例

示例

授权

Authorization
string
header
必填

服务端 SDK 使用项目 API 密钥,Remote MCP 使用 OAuth 访问令牌。不要在浏览器代码中暴露项目密钥。

请求头

X-Request-Id
string

可选的调用者自定义关联 ID,最长 128 字符。服务会在响应头返回实际使用的值,便于追踪和支持排查。

Required string length: 1 - 128
X-Viggle-Source
string

可选来源标签,最长 128 字符,用于识别 SDK、集成、产品入口或内部工作流。

Required string length: 1 - 128

路径参数

video_id
string
必填

当前调用者拥有的视频公开 ID:渲染为 render_,H3 为 vid_,角色动画为 anim_,视频超分为 vsr_。

Minimum string length: 1

响应

请求成功。

统一、只读的视频完整状态,支持 render_、vid_ 和 anim_。不包含 links 或 self/events/download 快捷链接。stage 仅 Render 来源且 processing 时有值,其余为 null。alpha_url 仅透明背景 Render 就绪时有值。seed 仅 H3 包含,Render 和角色动画完全省略该字段,而不是返回 null。

id
string
必填

所请求的视频 ID。

Minimum string length: 1
status
enum<string>
必填

queued、processing、ready、failed 或 cancelled。

可用选项:
queued,
processing,
ready,
failed,
cancelled
stage
enum<string> | null
必填

仅 Render 来源且 status=processing 时有值,其他情况为 null;H3 始终为 null。不存在 stage: "ready"。

可用选项:
queued,
preparing,
generating,
finalizing,
ready,
failed,
cancelled,
analyzing,
rendering,
finishing
progress
integer | null
必填

0–100 的进度,或 null。

必填范围: 0 <= x <= 100
video_url
string<uri> | null
必填

就绪后的输出下载地址;此前为 null。

alpha_url
string<uri> | null
必填

仅透明背景(background_mode=transparent)的 Render 在就绪后有值。H3 始终为 null。

created_at
string<date-time> | null
必填

Render 来源时间戳精确到纳秒;H3 来源精确到秒。

completed_at
string<date-time> | null
必填

见下方完成时间说明。

error
object | null
必填

status=failed 时的结构化错误详情。

seed
integer<int64>

实际使用的随机种子:传入时原样返回,未传入时返回生成的值。仅 vid_ 视频包含该字段;Render、角色动画及视频超分来源会省略此字段,而非返回 null。系统生成的种子是 63 位随机整数(0 到 2^63−1),通常大于 2^53 − 1,请用支持 64 位整数的 JSON 解析器读取;JavaScript 的 JSON.parse 会静默丢失精度。

queue_position
integer | null

H3(vid_)与角色动画(anim_)视频返回。处于 queued 状态时表示前方任务数;开始处理或进入终态后为 null。Render 与视频超分来源完全省略该字段。

必填范围: x >= 0
estimated_wait_seconds
integer | null

H3(vid_)与角色动画(anim_)视频返回。根据全局平均渲染时长及当前队列或调度状态估算的剩余秒数:排队时为预计完成所需时间,处理中为剩余的平均渲染时长。进入终态、位于非最高优先级队列(可能被新的最高优先级任务持续插队),或无法给出有界估算时为 null。Render 与视频超分来源完全省略该字段。

必填范围: x >= 0