> ## 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.

# 角色

> 创建、获取、列出、删除和导出可复用角色。

角色（Character）是图片中人物的可复用表示。创建一次并等待 `ready` 后，可将其 `char_...` ID 用于渲染。`type` 还可选择是否从同一图片提取 3D vsplat。

所有接口都需要 `Authorization: Bearer YOUR_API_KEY`。逐字段说明见[创建](/zh/v1/api-reference/characters/create)、[列表](/zh/v1/api-reference/characters/list)、[获取](/zh/v1/api-reference/characters/get)、[删除](/zh/v1/api-reference/characters/delete)和[导出](/zh/v1/api-reference/characters/export)。

## 创建角色

`POST /v1/characters`

使用 `multipart/form-data` 创建异步角色资源。

<Note>
  1 积分 = \$0.01。`render` 为 1 积分，`vsplat` 为 25 积分，`enhance=true` 时为 30 积分（替代原价，不叠加）。增强对 `render` 不生效、不收费。`all` 为 26 或 31 积分，见[计费](/zh/v1/pricing)。
</Note>

| 字段          | 类型      |  必填 | 默认值      | 说明                                        |
| ----------- | ------- | :-: | -------- | ----------------------------------------- |
| `image`     | file    | 二选一 | —        | 上传的角色图片。                                  |
| `image_url` | string  | 二选一 | —        | 角色图片的公开 URL。                              |
| `name`      | string  |  否  | `""`     | 显示名称。                                     |
| `type`      | string  |  否  | `render` | `render`、`vsplat` 或 `all`，按上述价格计费。        |
| `enhance`   | boolean |  否  | `false`  | 仅对 vsplat 执行额外 AI 增强，将提取费由 25 改为固定 30 积分。 |

图片来源必须二选一，上传文件支持 PNG、JPEG 和 WebP。

`type=vsplat`/`all` 还接受 `model_precision`、`filter_low_quality`、`joint_set`、`render_thumbnail` 和 `task_id`。`joint_set` 可为 `full`、`expression` 或默认 `body`，驱动动作需匹配。缩略图是否生成由调用者选择，来源和姿势由内部决定。限制和默认值见[从图片创建角色](/zh/v1/api-reference/characters/create)。

```bash theme={null}
curl -X POST "https://apis.viggle.ai/v1/characters" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F "image=@character.png" \
  -F "name=Presenter"
```

```json theme={null}
{
  "id": "char_123abc",
  "status": "queued",
  "name": "Presenter",
  "progress": 0,
  "capabilities": [],
  "created_at": "2026-07-17T10:00:00+00:00",
  "completed_at": null,
  "error": null,
  "type": "render",
  "vsplat": null,
  "glb": null
}
```

提取 3D 时添加 `type=vsplat`，同时保留渲染能力则使用 `all`，提取参数见[创建角色](/zh/v1/api-reference/characters/create)。

## 获取角色

`GET /v1/characters/{character_id}`

| 路径参数           | 类型     |  必填 | 说明                                                     |
| -------------- | ------ | :-: | ------------------------------------------------------ |
| `character_id` | string |  是  | 完整角色 ID，如 `char_550e8400-e29b-41d4-a716-446655440000`。 |

```bash theme={null}
curl "https://apis.viggle.ai/v1/characters/char_123abc" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"
```

轮询至 `ready`，并确认 `capabilities` 包含 `video_render` 后再渲染。`vsplat`/`all` 角色还可通过 `vsplat.status` 查看提取进度。

## 列出角色

`GET /v1/characters`

无查询参数。返回当前账户最近创建的有效角色，从新到旧，最多 100 条，无游标。

```bash theme={null}
curl "https://apis.viggle.ai/v1/characters" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"
```

## 删除角色

`DELETE /v1/characters/{character_id}`

```bash theme={null}
curl -X DELETE "https://apis.viggle.ai/v1/characters/char_123abc" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"
```

返回 `{"status": "deleted"}`。角色不存在、ID 前缀错误或属于其他账户时均返回 `404`。

## 导出角色 vsplat

`GET /v1/characters/{character_id}/export`

仅适用于 `vsplat`/`all`。添加 `download_type=vsplat` 获取模型链接，这是唯一允许值；角色没有 GLB 输出。创建时设置 `render_thumbnail=true` 且缩略图就绪后，`thumbnail_url` 会独立于 `download_type` 返回。

```bash theme={null}
curl "https://apis.viggle.ai/v1/characters/char_123abc/export?download_type=vsplat" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"
```

## 角色响应字段

| 字段                            | 类型                     | 说明                                                                  |
| ----------------------------- | ---------------------- | ------------------------------------------------------------------- |
| `id`                          | string                 | 公开 ID，后续请求请原样保留。                                                    |
| `status`                      | string                 | `queued`、`processing`、`ready` 或 `failed`；`all` 必须等渲染素材和 vsplat 都就绪。 |
| `name`                        | string                 | 创建时传入的名称。                                                           |
| `progress`                    | integer 或 null         | 可用时为 0–100，列表中始终为 `null`。                                           |
| `capabilities`                | string\[]              | 就绪且具备渲染能力时包含 `video_render`。                                        |
| `type`                        | string                 | `render`、`vsplat` 或 `all`。                                          |
| `vsplat`                      | object 或 null          | 请求提取时为 `{status, error}`，否则为 `null`，下载 URL 需通过导出获取。                 |
| `glb`                         | null                   | 角色始终为 `null`。                                                       |
| `created_at` / `completed_at` | ISO 8601 string 或 null | 资源时间。                                                               |
| `error`                       | object 或 null          | 查询时始终为 `null`，请结合 `status` 和 `vsplat.error` 判断失败。                   |

## 接口响应规则

| 接口                                         | 成功状态  | 响应                        | 参数                        |
| ------------------------------------------ | ----- | ------------------------- | ------------------------- |
| `POST /v1/characters`                      | `200` | Character 对象              | 一个图片来源；3D 参数取决于 `type`。   |
| `GET /v1/characters`                       | `200` | `{ "data": [Character] }` | 无。                        |
| `GET /v1/characters/{character_id}`        | `200` | Character 对象              | 必填 `character_id`。        |
| `DELETE /v1/characters/{character_id}`     | `200` | `{ "status": "deleted" }` | 必填 `character_id`。        |
| `GET /v1/characters/{character_id}/export` | `200` | CharacterExport 对象        | 必填 ID，可选 `download_type`。 |