> ## 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 API 参考

> 按资源组织的 Viggle V1 API 参考文档。

基础 URL：

```text theme={null}
https://apis.viggle.ai/v1
```

所有接口均需 `Authorization: Bearer YOUR_API_KEY`。

## 请求与响应约定

| 项目      | V1 约定                                                                                                |
| ------- | ---------------------------------------------------------------------------------------------------- |
| 基础 URL  | `https://apis.viggle.ai/v1`                                                                          |
| 身份验证    | 每个接口都需 `Authorization: Bearer YOUR_API_KEY`，包括状态查询和下载。                                               |
| 媒体上传    | 使用 `multipart/form-data`，或草稿渲染的直传 `PUT` URL。使用 `FormData` 时不要手动设置 `Content-Type`，客户端会添加正确的 boundary。 |
| JSON 请求 | 动作模板导入、文本生成动作、`renders/prepare`、草稿渲染和 Viggle-Animate 支持 JSON。                                        |
| 请求追踪    | 每个响应均有 `X-Request-Id`，也可自行传入以关联日志。                                                                   |
| 来源追踪    | 使用 `X-Viggle-Source` 标注调用渠道或集成来源。                                                                    |
| 幂等性     | JSON 草稿渲染必须提供 `Idempotency-Key`，其他接口忽略该请求头。部分 3D 创建接口另提供 `task_id`，见对应参数说明。                          |
| ID      | 公开 ID 使用类型前缀：`char_`、`mot_`、`render_`、`vid_`、`anim_`。不同资源类型不能混用。                                     |

### 公开 ID 格式

ID 是 Viggle 生成的不透明值，请原样保留，不要自行构造、缩短或删除前缀。3D 提取不再维护旧版独立 `avatar_`/`anim_` 资源，而是通过所属角色、动作的 `type`、`vsplat`、`glb` 和 `/export` 管理。当前视频生成中的 `anim_` 指角色动画视频，与旧版 3D 动画资源不同。

| 资源     | 前缀        | 示例                                          |
| ------ | --------- | ------------------------------------------- |
| 角色     | `char_`   | `char_550e8400-e29b-41d4-a716-446655440000` |
| 动作     | `mot_`    | `mot_550e8400-e29b-41d4-a716-446655440000`  |
| 渲染任务   | `render_` | `render_8f50b2c2c2b84ae0`                   |
| H3 视频  | `vid_`    | `vid_3f2a9c1b7e0d4f6a`                      |
| 角色动画视频 | `anim_`   | `anim_7c1e4b9a2d0f6e3c`                     |

[视频接口](/zh/v1/api-reference/videos/list)的 `video_id` 接受 `render_`、`vid_` 和 `anim_`，三者通过统一 Video 资源查询。

### 成功与错误响应

创建接口返回 `200 OK`（草稿渲染为 `202 Accepted`），资源通常处于 `queued`。状态查询返回 `200 OK` 也可能包含 `status: "failed"`，因此需同时检查 HTTP 状态和响应内容。

```json theme={null}
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Request failed validation",
    "retryable": false,
    "request_id": "req_123abc",
    "details": {},
    "remediation": { "action": "fix_request", "retry_after_ms": null }
  }
}
```

全部错误码及 `retryable`/`remediation` 的用法见[错误与恢复](/zh/v1/production/errors)。

## 资源

| 资源                                     | 用途                                                 |
| -------------------------------------- | -------------------------------------------------- |
| [角色](/zh/v1/api-reference/characters)  | 从图片创建可复用角色，可选提取 3D vsplat。                         |
| [动作](/zh/v1/api-reference/motions)     | 从视频或文本创建动作，可选提取或生成 3D GLB。                         |
| [渲染任务](/zh/v1/api-reference/renders)   | 直接或通过草稿将角色与动作异步生成为视频。                              |
| [视频](/zh/v1/api-reference/videos/list) | H3 文本、首帧、首尾帧、参考素材生成，以及独立后端的角色动画生成；同时统一查询渲染和全部生成模式。 |
| [积分](/zh/v1/api-reference/credits)     | 当前账户余额。                                            |

<Card title="代码示例" icon="code-xml" href="/zh/v1/api-reference/code-examples">
  当前 V1 接口的 Go、JavaScript、Python 和 cURL 示例。
</Card>

<Note>
  **H3 视频生成**使用经 Viggle 优化的 MiniMax H3，每个视频自带原生音频。`quality=low` 速度更快，`quality=high` 保真度更高，两者都是 \$0.01/生成秒。见[文本生成视频](/zh/v1/api-reference/videos/create-from-text)及[计费](/zh/v1/pricing#h3-video)。同一接口的**角色动画模式**使用独立后端，每次固定 \$0.11，与时长无关；可输入角色图片，或驱动视频加角色图片，详见[使用 Viggle-Animate](/zh/v1/api-reference/videos/create-from-character-animation)。
</Note>

## 资源模型

V1 区分可复用内容与对内容执行的操作：

| 层级   | 示例                                                             | 含义                                                                          |
| ---- | -------------------------------------------------------------- | --------------------------------------------------------------------------- |
| 素材   | Character、Motion                                               | 有稳定 ID 的可复用资源，可供多个渲染任务引用。`type` 决定是否提取角色 vsplat 或动作 GLB。                    |
| 操作   | Render、H3 视频生成                                                 | 有输入、状态、错误和输出的异步任务，不是可复用输入素材。均可通过[视频资源](/zh/v1/api-reference/videos/list)查询。 |
| 输出文件 | `video_url`、`alpha_url`、`vsplat_url`、`thumbnail_url`、`glb_url` | 操作或导出产生的可下载结果，URL 短期有效，每次读取重新签名。                                            |

直接提交到 `POST /v1/renders` 的 `image` 和 `motion_video` 是一次性输入，不会在素材列表中创建角色或动作。需要复用时，请显式创建素材。

## 接口索引

| 方法       | 接口                                     | 说明                                                      |
| -------- | -------------------------------------- | ------------------------------------------------------- |
| `POST`   | `/v1/renders/prepare`                  | 准备渲染草稿和直传计划。                                            |
| `POST`   | `/v1/renders`                          | multipart 直接创建，或 JSON 提交草稿。                             |
| `GET`    | `/v1/renders/{render_id}/events`       | 通过 SSE 监听状态。                                            |
| `GET`    | `/v1/renders/{render_id}/download`     | 下载就绪的渲染结果。                                              |
| `POST`   | `/v1/videos`                           | 从文本、首帧、首尾帧或参考素材生成 H3 视频，或从驱动视频及角色图片生成角色动画。              |
| `GET`    | `/v1/videos`                           | 游标分页列出当前身份的视频，合并三种来源；替代 `GET /v1/renders`。              |
| `GET`    | `/v1/videos/{video_id}`                | 通过 `render_`、`vid_` 或 `anim_` ID 获取状态和输出；替代旧 Render 查询。 |
| `GET`    | `/v1/credits`                          | 查询余额。                                                   |
| `POST`   | `/v1/characters`                       | 创建可复用角色，可选提取 vsplat。                                    |
| `GET`    | `/v1/characters`                       | 列出角色。                                                   |
| `GET`    | `/v1/characters/{character_id}`        | 获取角色。                                                   |
| `DELETE` | `/v1/characters/{character_id}`        | 删除角色。                                                   |
| `GET`    | `/v1/characters/{character_id}/export` | 下载角色 vsplat。                                            |
| `POST`   | `/v1/motions`                          | 从视频或 JSON 文本创建动作，可选提取或生成 GLB。                           |
| `POST`   | `/v1/motions/import`                   | 导入官方动作模板。                                               |
| `GET`    | `/v1/motions`                          | 列出动作。                                                   |
| `GET`    | `/v1/motions/{motion_id}`              | 获取动作。                                                   |
| `DELETE` | `/v1/motions/{motion_id}`              | 删除动作。                                                   |
| `GET`    | `/v1/motions/{motion_id}/export`       | 下载 3D 动画。                                               |

## 通用约定

* 媒体上传使用 multipart 或草稿流程的直传 `PUT` URL。
* ID 保留资源前缀，例如 `char_...`、`render_...`。
* 角色和动作使用 `queued`、`processing`、`ready`、`failed`；渲染还可能进入 `cancelled`，客户端只能观察，不能主动请求取消。
* 错误使用 `{ "error": { "code", "message", "retryable", "request_id", "details", "remediation" } }`，不暴露内部工作进程或流水线错误码。