角色 - Viggle API

角色（Character）是图片中人物的可复用表示。创建一次并等待 ready 后，可将其 char_... ID 用于渲染。type 还可选择是否从同一图片提取 3D vsplat。所有接口都需要 Authorization: Bearer YOUR_API_KEY。逐字段说明见创建、列表、获取、删除和导出。

创建角色

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

1 积分 = $0.01。render 为 1 积分，vsplat 默认 30 积分，enhance=false 时为 25 积分（替代原价，不叠加）。增强对 render 不生效、不收费。all 为 31 或 26 积分，见计费。

字段	类型	必填	默认值	说明
`image`	file	二选一	—	上传的角色图片。
`image_url`	string	二选一	—	角色图片的公开 URL。
`name`	string	否	`""`	显示名称。
`type`	string	否	`render`	`render`、`vsplat` 或 `all`，按上述价格计费。
`enhance`	boolean	否	`true`	是否执行更高保真度的 vsplat 提取，默认开启，固定 30 积分；设为 `false` 使用更便宜的标准提取，25 积分。
`enhance_prompt`	string	否	—	描述角色，最多 1000 个字符。单独传入（仅限 `type=vsplat`）时从文字生成角色；配图时引导增强。要求 `enhance=true`，不额外收费。

图片来源必须二选一，上传文件支持 PNG、JPEG 和 WebP。唯一例外是 type=vsplat 搭配 enhance_prompt，此时可以不传图片，见从图片创建角色。 type=vsplat/all 还接受 model_precision、joint_set、render_thumbnail 和 task_id。joint_set 可为 full、expression 或默认 body，驱动动作需匹配。缩略图是否生成由调用者选择，来源和姿势由内部决定。限制和默认值见从图片创建角色。

curl -X POST "https://apis.viggle.ai/v1/characters" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F "[email protected]" \
  -F "name=Presenter"

{
  "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，提取参数见创建角色。

获取角色

GET /v1/characters/{character_id}

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

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 条，无游标。

curl "https://apis.viggle.ai/v1/characters" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"

删除角色

DELETE /v1/characters/{character_id}

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 返回。

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 对象	一个图片来源（`type=vsplat` 也可只传 `enhance_prompt`）；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`。

Get Started

Guides

Production

角色

创建角色

获取角色

列出角色

删除角色

导出角色 vsplat

角色响应字段

接口响应规则

​创建角色

​获取角色

​列出角色

​删除角色

​导出角色 vsplat

​角色响应字段

​接口响应规则

创建角色

获取角色

列出角色

删除角色

导出角色 vsplat

角色响应字段

接口响应规则