POST /v1/characters 的 type=render 模式;如需提取 vsplat,请参阅 3D 角色快速入门。
设置环境变量 VIGGLE_API_KEY,并准备下方示例所需的角色图片。
准备工作
- 在 Viggle 控制台创建 API 密钥,并导出为环境变量
VIGGLE_API_KEY。
示例中的
https://assets.viggle.ai/samples/character.png 是占位地址。请替换为自己的 image/image_url,或在 Viggle 发布示例素材后使用其正式地址。完整示例
#!/usr/bin/env bash
set -euo pipefail
response=$(curl -s -X POST "https://apis.viggle.ai/v1/characters" \
-H "Authorization: Bearer $VIGGLE_API_KEY" \
-F "image_url=https://assets.viggle.ai/samples/character.png" \
-F "name=Quickstart character")
character_id=$(echo "$response" | jq -r '.id')
for _ in $(seq 1 60); do
character=$(curl -s "https://apis.viggle.ai/v1/characters/$character_id" \
-H "Authorization: Bearer $VIGGLE_API_KEY")
status=$(echo "$character" | jq -r '.status')
case "$status" in
ready)
echo "$character_id"
exit 0
;;
failed)
echo "Character failed: $(echo "$character" | jq -c '.error')" >&2
exit 1
;;
esac
sleep 3
done
echo "Timed out waiting for character $character_id" >&2
exit 1
const baseUrl = "https://apis.viggle.ai/v1";
const headers = { Authorization: `Bearer ${process.env.VIGGLE_API_KEY}` };
async function createCharacter() {
const form = new FormData();
form.append("image_url", "https://assets.viggle.ai/samples/character.png");
form.append("name", "Quickstart character");
const response = await fetch(`${baseUrl}/characters`, {
method: "POST",
headers,
body: form,
});
if (!response.ok) {
const body = await response.json().catch(() => ({}));
throw new Error(`HTTP ${response.status}: ${JSON.stringify(body.error ?? body)}`);
}
return response.json();
}
async function waitForCharacter(id) {
for (let attempt = 0; attempt < 60; attempt++) {
const response = await fetch(`${baseUrl}/characters/${id}`, { headers });
if (!response.ok) {
const body = await response.json().catch(() => ({}));
throw new Error(`HTTP ${response.status}: ${JSON.stringify(body.error ?? body)}`);
}
const character = await response.json();
if (["ready", "failed"].includes(character.status)) return character;
await new Promise((resolve) => setTimeout(resolve, 3000));
}
throw new Error(`Timed out waiting for character ${id}`);
}
const created = await createCharacter();
const character = await waitForCharacter(created.id);
if (character.status !== "ready") {
throw new Error(`Character failed: ${JSON.stringify(character.error)}`);
}
console.log(character.id);
import os
import time
import requests
base_url = "https://apis.viggle.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"}
response = requests.post(
f"{base_url}/characters",
headers=headers,
files={"image_url": (None, "https://assets.viggle.ai/samples/character.png")},
data={"name": "Quickstart character"},
)
response.raise_for_status()
character = response.json()
for _ in range(60):
if character["status"] in {"ready", "failed"}:
break
time.sleep(3)
response = requests.get(f"{base_url}/characters/{character['id']}", headers=headers)
response.raise_for_status()
character = response.json()
else:
raise TimeoutError(f"Timed out waiting for character {character['id']}")
if character["status"] != "ready":
error = character.get("error") or {}
raise RuntimeError(f"failed: {error.get('code')} {error.get('message')}")
print(character["id"])
响应
{
"id": "char_550e8400-e29b-41d4-a716-446655440000",
"status": "queued",
"name": "Quickstart character",
"progress": 0,
"capabilities": [],
"created_at": "2026-07-31T09:15:22+00:00",
"completed_at": null,
"error": null,
"type": "render",
"vsplat": null,
"glb": null
}
GET /v1/characters/{character_id},直到 status 为 ready 或 failed。就绪后,id 就是可复用的角色 ID。在渲染视频或视频重混快速入门中将其作为 character_id 使用,即可反复渲染,无需再次上传源图片。
角色创建的费用见计费与保留期限。
从图片创建角色
查看全部请求和响应字段,包括
vsplat/all 提取选项。
