> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viggle.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 渲染任务

> 准备输入、创建、监听和下载异步 V1 视频渲染。

渲染任务（Render）将一个角色来源、一个动作来源及可选背景设置合成为视频。所有接口均需 `Authorization: Bearer YOUR_API_KEY`。

`POST /v1/renders` 支持直接 `multipart/form-data`，或基于[准备渲染](/zh/v1/api-reference/renders/prepare)草稿的 JSON 请求。逐字段说明见[准备](/zh/v1/api-reference/renders/prepare)、[创建](/zh/v1/api-reference/renders/create)、[监听](/zh/v1/api-reference/renders/events)及[下载](/zh/v1/api-reference/renders/download)。

状态读取已迁移到统一 Video 资源，也涵盖 H3 视频生成。[列出视频](/zh/v1/api-reference/videos/list)和[获取视频](/zh/v1/api-reference/videos/get)替代旧 Render 列表与详情接口。

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

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

## 直接创建渲染

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

<Note>
  每个角色、每秒成品视频收费 \$0.01。当前每次仅支持 1 个角色，因此实际为 \$0.01/秒，无单次最低消费。创建时预留预计金额，完成后按实际时长结算，见[计费](/zh/v1/pricing#video-remix)。
</Note>

### 角色输入

| 字段             | 类型     |  必填 | 说明                                                        |
| -------------- | ------ | :-: | --------------------------------------------------------- |
| `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`。两组输入都完全省略时使用预配置默认角色和动作；只提供一组则报错。默认值依项目及环境变化，仅适合连通性检查，生产中应明确提供双方来源。

```bash theme={null}
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"
```

```json theme={null}
{
  "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 调用[获取视频](/zh/v1/api-reference/videos/get)。`links.events` 和 `links.download` 不受影响。

### Python 创建与轮询示例

```python theme={null}
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`。完整流程见[准备渲染](/zh/v1/api-reference/renders/prepare)。

## 获取与列出渲染

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

* [获取视频](/zh/v1/api-reference/videos/get)：`GET /v1/videos/{video_id}`，每 3–5 秒轮询至终态，或使用[监听渲染](/zh/v1/api-reference/renders/events)。
* [列出视频](/zh/v1/api-reference/videos/list)：`GET /v1/videos`，支持 `status`、`cursor`、`limit` 游标分页。

## 下载渲染结果

`GET /v1/renders/{render_id}/download`

```bash theme={null}
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` | —                   | 已停用，改用[列出视频](/zh/v1/api-reference/videos/list)。                         |
| `GET /v1/renders/{render_id}`          | `405` | —                   | 已停用，改用[获取视频](/zh/v1/api-reference/videos/get)。失败任务仍返回 `200`，需检查响应状态和错误。 |
| `GET /v1/renders/{render_id}/events`   | `200` | `text/event-stream` | 终态事件后关闭。                                                                |
| `GET /v1/renders/{render_id}/download` | `302` | 重定向                 | 仅就绪时可用。                                                                 |

## 渲染响应字段

以下为[创建渲染](/zh/v1/api-reference/renders/create)的对象结构。[获取视频](/zh/v1/api-reference/videos/get)不包含 `links`；[视频列表](/zh/v1/api-reference/videos/list)仅返回摘要，不包含媒体 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` 已停用，改用[获取视频](/zh/v1/api-reference/videos/get)。 |