> ## 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.
# 导出 3D 角色（用于 3D／游戏引擎）
> 获取角色 vsplat 提取结果的签名下载链接。
仅适用于以 `type=vsplat` 或 `all` 创建的角色；仅 `render` 的角色无可导出内容。本接口替代已移除的 `GET /v1/avatars/{avatar_id}`。
`vsplat_url` 与 `thumbnail_url` 的返回条件不同：
* `vsplat_url` 仅在传入 `download_type=vsplat` 且就绪时返回，每次调用重新签名。
* `thumbnail_url` 只要缩略图已生成并就绪就会返回，与 `download_type` 无关，即使省略该参数也会返回。需在[创建角色](/zh/v1/api-reference/characters/create)时设置 `render_thumbnail=true`，而非在导出时选择缩略图。
角色导出不提供 `glb`。`download_type` 仅接受 `vsplat`；GLB 属于动作输出，见[导出 3D 动作](/zh/v1/api-reference/motions/export)。
## 请求参数
| 参数 | 类型 | 必填 | 说明 |
| --------------- | ------ | :-: | ------------------------------------------------------------------------------------- |
| `character_id` | string | 是 | 创建或列出角色时返回的完整 ID，角色须以 `type=vsplat` 或 `all` 创建。 |
| `download_type` | string | 否 | 仅支持 `vsplat`。其他值（包括旧值 `thumbnail` 或动作专用的 `glb`）返回 `400`。省略时仅返回状态及已有的 `thumbnail_url`。 |
## 响应参数
返回 `200 OK`。
| 字段 | 类型 | 始终返回 | 说明 |
| --------------- | ------------- | :--: | ------------------------------------------------------------------------------- |
| `id` | string | 是 | 所请求的角色公开 ID。 |
| `status` | string | 是 | `queued`、`processing`、`ready` 或 `failed`。 |
| `download_type` | string 或 null | 是 | 返回请求的值，只会是 `vsplat` 或 `null`，不会是 `thumbnail`。 |
| `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` 时的结构化错误详情。 |
角色创建时设置 `render_thumbnail=true`，并以 `download_type=vsplat` 导出时，会同时返回两个 URL：
```json theme={null}
{
"id": "char_550e8400-e29b-41d4-a716-446655440000",
"status": "ready",
"download_type": "vsplat",
"vsplat_url": "https://assets.viggle.ai/results/character.vsplat",
"thumbnail_url": "https://assets.viggle.ai/results/character_thumb.png",
"created_at": "2026-07-31T09:15:22+00:00",
"updated_at": "2026-07-31T09:16:40+00:00",
"error": null
}
```
同一角色省略 `download_type` 时，`vsplat_url` 不返回链接，但 `thumbnail_url` 仍有值：
```json theme={null}
{
"id": "char_550e8400-e29b-41d4-a716-446655440000",
"status": "ready",
"download_type": null,
"vsplat_url": null,
"thumbnail_url": "https://assets.viggle.ai/results/character_thumb.png",
"created_at": "2026-07-31T09:15:22+00:00",
"updated_at": "2026-07-31T09:16:40+00:00",
"error": null
}
```
## 示例
```go Go theme={null}
req,_:=http.NewRequest("GET","https://apis.viggle.ai/v1/characters/"+characterID+"/export?download_type=vsplat",nil); req.Header.Set("Authorization","Bearer "+os.Getenv("VIGGLE_API_KEY")); resp,err:=http.DefaultClient.Do(req); if err!=nil {panic(err)}; defer resp.Body.Close()
```
```javascript JavaScript theme={null}
const response=await fetch(`https://apis.viggle.ai/v1/characters/${characterId}/export?download_type=vsplat`,{headers:{Authorization:`Bearer ${process.env.VIGGLE_API_KEY}`}}); const exported=await response.json();
```
```python Python theme={null}
import os, requests
response=requests.get(f"https://apis.viggle.ai/v1/characters/{character_id}/export",params={"download_type":"vsplat"},headers={"Authorization":f"Bearer {os.environ['VIGGLE_API_KEY']}"}); response.raise_for_status(); exported=response.json()
```
```bash cURL theme={null}
curl "https://apis.viggle.ai/v1/characters/$CHARACTER_ID/export?download_type=vsplat" -H "Authorization: Bearer $VIGGLE_API_KEY"
```
下载链接有效期较短，每次读取都会重新签名。需要时请再次指定 `download_type` 获取，不要长期缓存。
## 下一步
同一角色的 2D 渲染能力（`capabilities: ["video_render"]`）与 vsplat 导出相互独立。具备该能力且就绪后，可通过[渲染视频](/zh/v1/api-reference/renders/create)使用 `character_id`。
## OpenAPI
````yaml zh/openapi.yaml GET /v1/characters/{character_id}/export
openapi: 3.0.3
info:
title: Viggle API
description: 使用 AI 生成角色动画视频。
version: 2.0.0
contact:
name: Viggle Support
url: https://viggle.ai
servers:
- url: https://apis.viggle.ai
description: 生产服务器
security:
- bearerAuth: []
tags:
- name: Renders
description: 准备输入、创建渲染、观察进度并获取结果。
- name: Credits
description: 查询当前调用者可用的积分余额。
- name: Characters
description: 创建、列出、查询和删除可复用角色。type 决定是否同时提取 3D vsplat，就绪后通过导出接口获取下载链接。
- name: Motions
description: 创建、列出、查询和删除可复用动作，也可从官方模板导入。type 决定是否提取或生成 3D 动画，就绪后通过导出接口获取下载链接。
- name: Videos
description: 生成 MiniMax H3 视频（vid_）或角色动画视频（anim_），并统一查询调用者的 H3、角色动画及角色动作渲染（render_）结果。
paths:
/v1/characters/{character_id}/export:
parameters:
- $ref: '#/components/parameters/CharacterId'
- $ref: '#/components/parameters/RequestId'
- $ref: '#/components/parameters/SourceChannel'
get:
tags:
- Characters
summary: 导出 3D 角色（用于 3D／游戏引擎）
description: 获取角色 vsplat 提取结果的签名下载链接。
operationId: exportCharacter
parameters:
- name: download_type
in: query
required: false
description: 选择要返回的签名输出。提取就绪后使用 vsplat；仅查询状态或缩略图时可省略。
schema:
type: string
enum:
- vsplat
responses:
'200':
description: 请求成功。
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/CharacterExport'
'400':
$ref: '#/components/responses/ResourceBadRequest'
'401':
$ref: '#/components/responses/ResourceUnauthorized'
'404':
$ref: '#/components/responses/ResourceNotFound'
'409':
$ref: '#/components/responses/ResourceConflict'
'500':
$ref: '#/components/responses/ResourceInternalServerError'
'502':
$ref: '#/components/responses/ResourceBadGateway'
'503':
$ref: '#/components/responses/ResourceServiceUnavailable'
components:
parameters:
CharacterId:
name: character_id
in: path
required: true
description: 创建或列出角色时返回的公开 ID，通常以 char_ 开头，必须属于当前调用者。
schema:
type: string
minLength: 1
example: char_2f1c4b8e9d7a4f2ab6c3d5e7f9a1b3c5
RequestId:
name: X-Request-Id
in: header
required: false
description: 可选的调用者自定义关联 ID，最长 128 字符。服务会在响应头返回实际使用的值，便于追踪和支持排查。
schema:
type: string
minLength: 1
maxLength: 128
SourceChannel:
name: X-Viggle-Source
in: header
required: false
description: 可选来源标签，最长 128 字符，用于识别 SDK、集成、产品入口或内部工作流。
schema:
type: string
minLength: 1
maxLength: 128
headers:
RequestId:
description: 用于支持排查和追踪的稳定请求 ID。
schema:
type: string
schemas:
CharacterExport:
description: >-
角色 vsplat 下载结果。仅请求 download_type=vsplat 时返回 vsplat_url；已生成的缩略图会独立于
download_type 返回。下载链接短期有效，每次读取重新签名。本结构替代旧 AvatarResource 和已移除的 GET
/v1/avatars/{avatar_id}。
type: object
additionalProperties: false
required:
- id
- status
- download_type
- vsplat_url
- thumbnail_url
- created_at
- updated_at
- error
properties:
id:
type: string
description: 所请求的角色公开 ID。
minLength: 1
status:
description: '`queued`、`processing`、`ready` 或 `failed`。'
allOf:
- $ref: '#/components/schemas/ResourceStatus'
download_type:
description: 返回请求的值，只会是 `vsplat` 或 `null`，不会是 `thumbnail`。
type: string
nullable: true
enum:
- vsplat
- null
vsplat_url:
type: string
description: 仅 `download_type=vsplat` 且提取就绪时有值。
nullable: true
thumbnail_url:
type: string
description: >-
已渲染且就绪的缩略图 URL，与 `download_type` 无关。默认 `render_thumbnail=false`
或尚未就绪时为 `null`。
nullable: true
created_at:
description: 带 UTC 偏移的 ISO 8601 时间。尚未记录时间的任务可能返回空字符串。
type: string
nullable: true
updated_at:
type: string
description: 最近更新时间，ISO 8601 格式。
nullable: true
error:
type: object
description: '`status=failed` 时的结构化错误详情。'
nullable: true
allOf:
- $ref: '#/components/schemas/ResourceError'
ResourceStatus:
description: 异步资源共用的公开生命周期，枚举值与 RenderStatus 相同。
type: string
enum:
- queued
- processing
- ready
- failed
- cancelled
ResourceError:
description: >-
异步资源附带的错误。code 为稳定的小写下划线字符串，故意不限制为枚举，工作进程可能新增值；无公开映射时使用
processing_failed。已发布值包括
worker_stopped、motion_model_mismatch、image_required、motion_video_required、unsupported_video_format、video_too_long、video_too_large、video_resolution_too_high、video_unreadable、invalid_background_mode、video_dimensions_must_be_even、result_expired、video_inaccessible、no_humans_detected、all_workers_busy、task_failed、unexpected_error、processing_failed。
type: object
additionalProperties: false
required:
- code
- message
- request_id
properties:
code:
type: string
description: 稳定的小写下划线异步错误码。集合可扩展，客户端应容忍新值。
minLength: 1
message:
type: string
description: 供人阅读的异步处理失败说明。
request_id:
type: string
description: 工作进程或原始请求的关联 ID，不可用时为 null。
nullable: true
ResourceErrorResponse:
type: object
additionalProperties: false
required:
- error
properties:
error:
description: 同步资源操作失败的顶层错误对象。
allOf:
- $ref: '#/components/schemas/ResourceHttpError'
ResourceHttpError:
description: >-
同步资源请求的错误封装。错误码由 API 服务中的固定映射生成，无公开映射的失败使用 processing_failed。资源的异步 error
对象采用 ResourceError 中更广泛、可扩展的错误码集合。
type: object
additionalProperties: false
required:
- code
- message
- request_id
properties:
code:
type: string
description: 同步资源请求的固定小写下划线错误码，用于程序化处理。
enum:
- authentication_required
- invalid_api_key
- insufficient_credits
- invalid_request
- motion_not_ready
- character_not_found
- motion_not_found
- not_found
- id_already_exists
- rate_limited
- service_unavailable
- task_failed
- internal_error
- processing_failed
message:
type: string
description: 供人阅读的同步请求失败说明。
request_id:
description: 同步失败时始终为 null，请通过 X-Request-Id 响应头关联请求。
type: string
nullable: true
responses:
ResourceBadRequest:
description: 请求失败，详情见错误响应。
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceErrorResponse'
ResourceUnauthorized:
description: 请求失败，详情见错误响应。
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceErrorResponse'
ResourceNotFound:
description: 请求失败，详情见错误响应。
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceErrorResponse'
ResourceConflict:
description: 请求失败，详情见错误响应。
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceErrorResponse'
ResourceInternalServerError:
description: 请求失败，详情见错误响应。
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceErrorResponse'
ResourceBadGateway:
description: 请求失败，详情见错误响应。
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceErrorResponse'
ResourceServiceUnavailable:
description: 请求失败，详情见错误响应。
headers:
Retry-After:
schema:
type: integer
minimum: 0
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceErrorResponse'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API key or OAuth access token
description: 服务端 SDK 使用项目 API 密钥，Remote MCP 使用 OAuth 访问令牌。不要在浏览器代码中暴露项目密钥。
````