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

请求参数

响应参数

返回 200 OK 和 Video 对象。 本响应没有 links,因此不包含创建渲染响应中的 selfeventsdownload 快捷链接。继续查询时使用同一 video_id;Render 来源的 ID 还可使用下载渲染结果

完成时间

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

Render 来源示例

H3 来源示例

角色动画来源示例

没有 seed 字段;该字段仅适用于 H3。

失败示例

示例

授权

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_。

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>
必填

queuedprocessingreadyfailedcancelled

可用选项:
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