渲染任务

渲染任务（Render）将一个角色来源、一个动作来源及可选背景设置合成为视频。所有接口均需 Authorization: Bearer YOUR_API_KEY。 POST /v1/renders 支持直接 multipart/form-data，或基于准备渲染草稿的 JSON 请求。逐字段说明见准备、创建、监听及下载。状态读取已迁移到统一 Video 资源，也涵盖 H3 视频生成。列出视频和获取视频替代旧 Render 列表与详情接口。

没有公开的客户端取消操作。任务可能自行进入 cancelled，但客户端不能主动请求取消。

GET /v1/renders 和 GET /v1/renders/{render_id} 已停用，返回 405 Method Not Allowed，而非 404。相关渲染路由仍注册有其他操作，因此停用方法返回 405。旧接入若通过 404 判断停用，请同时接受 405，或直接改用统一视频接口。

直接创建渲染

使用 POST /v1/renders 的 multipart 形式，为角色和动作分别选择可复用 ID 或直接输入。

每个角色、每秒成品视频收费 $0.01。当前每次仅支持 1 个角色，因此实际为 $0.01/秒，无单次最低消费。创建时预留预计金额，完成后按实际时长结算，见计费。

角色输入

字段	类型	必填	说明
`character_id`	string	三选一	就绪角色的完整 ID，如 `char_550e8400-e29b-41d4-a716-446655440000`。
`image`	file	三选一	直接上传的图片。
`image_url`	string	三选一	角色图片公开 URL。

动作输入

字段	类型	必填	说明
`motion_id`	string	三选一	就绪动作的完整 ID，如 `mot_550e8400-e29b-41d4-a716-446655440000`。
`motion_video`	file	三选一	直接上传的驱动视频。
`motion_video_url`	string	三选一	驱动视频公开 URL。

渲染设置

字段	类型	必填	默认值	说明
`background_mode`	string	否	`original`	`original`、`solid`、`transparent`，或等同于 `original` 的 `inpaint`。
`bg_color`	string	`solid` 时	—	`R,G,B` 格式 RGB 颜色，如 `0,255,0`。

非 solid 模式使用 bg_color 会被拒绝。透明模式就绪后额外返回 alpha_url。两组输入都完全省略时使用预配置默认角色和动作；只提供一组则报错。默认值依项目及环境变化，仅适合连通性检查，生产中应明确提供双方来源。

curl -X POST "https://apis.viggle.ai/v1/renders" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F "character_id=char_123abc" \
  -F "motion_id=mot_456def" \
  -F "background_mode=transparent"

{
  "id": "render_789ghi",
  "status": "queued",
  "progress": 0,
  "stage": null,
  "video_url": null,
  "alpha_url": null,
  "created_at": "2026-07-17T10:00:00+00:00",
  "completed_at": null,
  "error": null,
  "links": {
    "self": "/v1/renders/render_789ghi",
    "events": "/v1/renders/render_789ghi/events",
    "download": "/v1/renders/render_789ghi/download"
  }
}

links.self 指向已停用的旧查询接口，请改用同一 ID 调用获取视频。links.events 和 links.download 不受影响。

Python 创建与轮询示例

import os
import time
import requests

headers = {"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"}
with open("character.png", "rb") as image, open("dance.mp4", "rb") as motion:
    response = requests.post(
        "https://apis.viggle.ai/v1/renders",
        headers=headers,
        files={"image": image, "motion_video": motion},
        data={"background_mode": "original"},
    )
response.raise_for_status()
render = response.json()

while render["status"] in {"queued", "processing"}:
    time.sleep(3)
    response = requests.get(
        f"https://apis.viggle.ai/v1/videos/{render['id']}", headers=headers
    )
    response.raise_for_status()
    render = response.json()

if render["status"] == "ready":
    print(render["video_url"])
else:
    print(render["error"])

从草稿创建渲染

POST /v1/renders/prepare 返回 draft_id 及所需上传计划。上传声明的素材后，以 JSON 调用 POST /v1/renders，提供 draft_id 和必填 Idempotency-Key。此形式返回 202，不是 200。完整流程见准备渲染。

获取与列出渲染

旧 Render 查询接口返回 405，请使用统一视频资源：

获取视频：GET /v1/videos/{video_id}，每 3–5 秒轮询至终态，或使用监听渲染。
列出视频：GET /v1/videos，支持 status、cursor、limit 游标分页。

下载渲染结果

GET /v1/renders/{render_id}/download

curl -L "https://apis.viggle.ai/v1/renders/render_789ghi/download" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -o output.mp4

接口重定向到成品视频，也可直接下载就绪响应中的 video_url。

响应与状态规则

接口	状态	响应	说明
`POST /v1/renders/prepare`	`200`	草稿与上传计划	仅 JSON。
`POST /v1/renders`（multipart）	`200`	Render 对象	初始 `queued`，忽略幂等请求头。
`POST /v1/renders`（JSON）	`202`	Render 对象	必填幂等键，按键与标准化输入判断幂等。
`GET /v1/renders`	`405`	—	已停用，改用列出视频。
`GET /v1/renders/{render_id}`	`405`	—	已停用，改用获取视频。失败任务仍返回 `200`，需检查响应状态和错误。
`GET /v1/renders/{render_id}/events`	`200`	`text/event-stream`	终态事件后关闭。
`GET /v1/renders/{render_id}/download`	`302`	重定向	仅就绪时可用。

渲染响应字段

以下为创建渲染的对象结构。获取视频不包含 links；视频列表仅返回摘要，不包含媒体 URL 和错误详情。

字段	类型	说明
`id`	string	公开 ID，如 `render_8f50b2c2c2b84ae0`，状态和下载请求请原样使用。
`status`	string	`queued`、`processing`、`ready`、`failed` 或 `cancelled`。
`progress`	integer 或 null	可用时为 0–100。
`stage`	string 或 null	可用时提供大致阶段。
`video_url`	string 或 null	`ready` 时的成品 URL。
`alpha_url`	string 或 null	透明输出的 Alpha 蒙版视频。
`created_at` / `completed_at`	ISO 8601 string 或 null	渲染时间。
`error`	object 或 null	失败时的详情。
`links`	object	`{self, events, download}`，旧版迁移代理可能省略。`self` 已停用，改用获取视频。

Get Started

Guides

Production

直接创建渲染

角色输入

动作输入

渲染设置

Python 创建与轮询示例

从草稿创建渲染

获取与列出渲染

下载渲染结果

响应与状态规则

渲染响应字段

​直接创建渲染

​角色输入

​动作输入

​渲染设置

​Python 创建与轮询示例

​从草稿创建渲染

​获取与列出渲染

​下载渲染结果

​响应与状态规则

​渲染响应字段

直接创建渲染

角色输入

动作输入

渲染设置

Python 创建与轮询示例

从草稿创建渲染

获取与列出渲染

下载渲染结果

响应与状态规则

渲染响应字段