导出 3D 角色(用于 3D/游戏引擎)
curl --request GET \
--url https://apis.viggle.ai/v1/characters/{character_id}/export \
--header 'Authorization: Bearer <token>'import requests
url = "https://apis.viggle.ai/v1/characters/{character_id}/export"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://apis.viggle.ai/v1/characters/{character_id}/export', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://apis.viggle.ai/v1/characters/{character_id}/export",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://apis.viggle.ai/v1/characters/{character_id}/export"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://apis.viggle.ai/v1/characters/{character_id}/export")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://apis.viggle.ai/v1/characters/{character_id}/export")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "<string>",
"status": "queued",
"download_type": "vsplat",
"vsplat_url": "<string>",
"thumbnail_url": "<string>",
"created_at": "<string>",
"updated_at": "<string>",
"error": {
"code": "<string>",
"message": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "authentication_required",
"message": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "authentication_required",
"message": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "authentication_required",
"message": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "authentication_required",
"message": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "authentication_required",
"message": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "authentication_required",
"message": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "authentication_required",
"message": "<string>",
"request_id": "<string>"
}
}角色
导出 3D 角色(用于 3D/游戏引擎)
获取角色 vsplat 提取结果的签名下载链接。
GET
/
v1
/
characters
/
{character_id}
/
export
导出 3D 角色(用于 3D/游戏引擎)
curl --request GET \
--url https://apis.viggle.ai/v1/characters/{character_id}/export \
--header 'Authorization: Bearer <token>'import requests
url = "https://apis.viggle.ai/v1/characters/{character_id}/export"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://apis.viggle.ai/v1/characters/{character_id}/export', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://apis.viggle.ai/v1/characters/{character_id}/export",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://apis.viggle.ai/v1/characters/{character_id}/export"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://apis.viggle.ai/v1/characters/{character_id}/export")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://apis.viggle.ai/v1/characters/{character_id}/export")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "<string>",
"status": "queued",
"download_type": "vsplat",
"vsplat_url": "<string>",
"thumbnail_url": "<string>",
"created_at": "<string>",
"updated_at": "<string>",
"error": {
"code": "<string>",
"message": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "authentication_required",
"message": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "authentication_required",
"message": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "authentication_required",
"message": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "authentication_required",
"message": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "authentication_required",
"message": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "authentication_required",
"message": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "authentication_required",
"message": "<string>",
"request_id": "<string>"
}
}仅适用于以
角色创建时设置
同一角色省略
type=vsplat 或 all 创建的角色;仅 render 的角色无可导出内容。本接口替代已移除的 GET /v1/avatars/{avatar_id}。
vsplat_url 与 thumbnail_url 的返回条件不同:
vsplat_url仅在传入download_type=vsplat且就绪时返回,每次调用重新签名。thumbnail_url只要缩略图已生成并就绪就会返回,与download_type无关,即使省略该参数也会返回。需在创建角色时设置render_thumbnail=true,而非在导出时选择缩略图。
glb。download_type 仅接受 vsplat;GLB 属于动作输出,见导出 3D 动作。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
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:
{
"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 仍有值:
{
"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
}
示例
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()
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();
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()
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 导出相互独立。具备该能力且就绪后,可通过渲染视频使用 character_id。授权
服务端 SDK 使用项目 API 密钥,Remote MCP 使用 OAuth 访问令牌。不要在浏览器代码中暴露项目密钥。
请求头
可选的调用者自定义关联 ID,最长 128 字符。服务会在响应头返回实际使用的值,便于追踪和支持排查。
Required string length:
1 - 128可选来源标签,最长 128 字符,用于识别 SDK、集成、产品入口或内部工作流。
Required string length:
1 - 128路径参数
创建或列出角色时返回的公开 ID,通常以 char_ 开头,必须属于当前调用者。
Minimum string length:
1查询参数
选择要返回的签名输出。提取就绪后使用 vsplat;仅查询状态或缩略图时可省略。
可用选项:
vsplat 响应
请求成功。
角色 vsplat 下载结果。仅请求 download_type=vsplat 时返回 vsplat_url;已生成的缩略图会独立于 download_type 返回。下载链接短期有效,每次读取重新签名。本结构替代旧 AvatarResource 和已移除的 GET /v1/avatars/{avatar_id}。
所请求的角色公开 ID。
Minimum string length:
1queued、processing、ready 或 failed。
可用选项:
queued, processing, ready, failed, cancelled 返回请求的值,只会是 vsplat 或 null,不会是 thumbnail。
可用选项:
vsplat, null 仅 download_type=vsplat 且提取就绪时有值。
已渲染且就绪的缩略图 URL,与 download_type 无关。默认 render_thumbnail=false 或尚未就绪时为 null。
带 UTC 偏移的 ISO 8601 时间。尚未记录时间的任务可能返回空字符串。
最近更新时间,ISO 8601 格式。
status=failed 时的结构化错误详情。
Show child attributes
Show child attributes

