V1 API 参考 - Viggle API

基础 URL：

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`（`POST /v1/images` 即使不带参考图也必须使用），或草稿渲染的直传 `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_`、`img_`。不同资源类型不能混用。

公开 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`
图片生成	`img_`	`img_b16a190d-2d44-41a0-8056-ef68183c3b9e`

视频接口的 video_id 接受 render_、vid_ 和 anim_，三者通过统一 Video 资源查询。img_ 图片生成不属于视频，请用查询图片查询。

成功与错误响应

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

{
  "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 的用法见错误与恢复。

资源

资源	用途
角色	从图片创建可复用角色，可选提取 3D vsplat。
动作	从视频或文本创建动作，可选提取或生成 3D GLB。
渲染任务	直接或通过草稿将角色与动作异步生成为视频。
视频	H3 文本、首帧、首尾帧、参考素材生成，以及独立后端的角色动画生成；同时统一查询渲染和全部生成模式。
Viggle Image	用 `qwen` 模型从文字描述生成 1–6 张 PNG，可选最多 8 张参考图。`1K` 每张 $0.01，`2K` 每张 $0.02。
积分	当前账户余额。

代码示例

当前 V1 接口的 Go、JavaScript、Python 和 cURL 示例。

H3 视频生成使用经 Viggle 优化的 MiniMax H3，每个视频自带原生音频。quality=low 速度更快，quality=high 保真度更高，在 480p/768p/1080p/2k 下两者都是 $0.01/生成秒，4k 下为 $0.05/生成秒。见文本生成视频及计费。同一接口的角色动画模式使用独立后端，按驱动视频时长收取 $0.01/秒（1 积分/秒），向上取整（5–16 积分），无驱动视频时固定 $0.11；需提供一至四张角色图片，配合可选的驱动视频时最多五张，详见使用 Viggle-Animate。

资源模型

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

层级	示例	含义
素材	Character、Motion	有稳定 ID 的可复用资源，可供多个渲染任务引用。`type` 决定是否提取角色 vsplat 或动作 GLB。
操作	Render、H3 视频生成、图片生成	有输入、状态、错误和输出的异步任务，不是可复用输入素材。视频类操作通过视频资源查询，图片生成通过查询图片查询。
输出文件	`video_url`、`alpha_url`、`vsplat_url`、`thumbnail_url`、`mixamo_url`/`metahuman_url`/`metahuman_body_url`、`images[].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 查询。
`POST`	`/v1/images`	从文字描述生成 1–6 张 PNG，可选最多 8 张参考图。
`GET`	`/v1/images/{image_id}`	通过 `img_` ID 获取图片任务状态和 PNG 下载链接。
`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" } }，不暴露内部工作进程或流水线错误码。

​请求与响应约定

​公开 ID 格式

​成功与错误响应

​资源