Skip to main content
GET
导出 3D 角色(用于 3D/游戏引擎)
仅适用于以 type=vsplatall 创建的角色;仅 render 的角色无可导出内容。本接口替代已移除的 GET /v1/avatars/{avatar_id} vsplat_urlthumbnail_url 的返回条件不同:
  • vsplat_url 仅在传入 download_type=vsplat 且就绪时返回,每次调用重新签名。
  • thumbnail_url 只要缩略图已生成并就绪就会返回,与 download_type 无关,即使省略该参数也会返回。需在创建角色时设置 render_thumbnail=true,而非在导出时选择缩略图。
角色导出不提供 glbdownload_type 仅接受 vsplat;GLB 属于动作输出,见导出 3D 动作

请求参数

响应参数

返回 200 OK 角色创建时设置 render_thumbnail=true,并以 download_type=vsplat 导出时,会同时返回两个 URL:
同一角色省略 download_type 时,vsplat_url 不返回链接,但 thumbnail_url 仍有值:

示例

下载链接有效期较短,每次读取都会重新签名。需要时请再次指定 download_type 获取,不要长期缓存。

下一步

同一角色的 2D 渲染能力(capabilities: ["video_render"])与 vsplat 导出相互独立。具备该能力且就绪后,可通过渲染视频使用 character_id

授权

Authorization
string
header
必填

服务端 SDK 使用项目 API 密钥,Remote MCP 使用 OAuth 访问令牌。不要在浏览器代码中暴露项目密钥。

请求头

X-Request-Id
string

可选的调用者自定义关联 ID,最长 128 字符。服务会在响应头返回实际使用的值,便于追踪和支持排查。

Required string length: 1 - 128
X-Viggle-Source
string

可选来源标签,最长 128 字符,用于识别 SDK、集成、产品入口或内部工作流。

Required string length: 1 - 128

路径参数

character_id
string
必填

创建或列出角色时返回的公开 ID,通常以 char_ 开头,必须属于当前调用者。

Minimum string length: 1

查询参数

download_type
enum<string>

选择要返回的签名输出。提取就绪后使用 vsplat;仅查询状态或缩略图时可省略。

可用选项:
vsplat

响应

请求成功。

角色 vsplat 下载结果。仅请求 download_type=vsplat 时返回 vsplat_url;已生成的缩略图会独立于 download_type 返回。下载链接短期有效,每次读取重新签名。本结构替代旧 AvatarResource 和已移除的 GET /v1/avatars/{avatar_id}。

id
string
必填

所请求的角色公开 ID。

Minimum string length: 1
status
enum<string>
必填

queuedprocessingreadyfailed

可用选项:
queued,
processing,
ready,
failed,
cancelled
download_type
enum<string> | null
必填

返回请求的值,只会是 vsplatnull,不会是 thumbnail

可用选项:
vsplat,
null
vsplat_url
string | null
必填

download_type=vsplat 且提取就绪时有值。

thumbnail_url
string | null
必填

已渲染且就绪的缩略图 URL,与 download_type 无关。默认 render_thumbnail=false 或尚未就绪时为 null

created_at
string | null
必填

带 UTC 偏移的 ISO 8601 时间。尚未记录时间的任务可能返回空字符串。

updated_at
string | null
必填

最近更新时间,ISO 8601 格式。

error
object | null
必填

status=failed 时的结构化错误详情。