VisionStory 数字人形象 API 为数字人视频提供出镜角色。你可以浏览即用的公共形象，或通过一张肖像创建可复用的专属形象，再将其 avatar_id 传入每次视频生成请求。
数字人形象接口
| 方法 | 路径 | 功能 |
|---|---|---|
GET | /api/v1/avatars | 列出公共形象和你的专属形象 |
POST | /api/v1/avatar | 通过图片创建专属形象 |
DELETE | /api/v1/avatar | 删除你的一个专属形象 |
查询公共形象与专属形象
列表响应分为两组：public_avatars 是无需设置即可使用的公共形象，my_avatars 是你创建的形象。每个形象还包含 default_voice_id；如果该角色已配置声音，此字段会给出对应的声音 ID：
Shell
curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" https://openapi.visionstory.ai/api/v1/avatars
Python
import os
import requests
headers = {"X-API-Key": os.environ["VISIONSTORY_API_KEY"]}
response = requests.get("https://openapi.visionstory.ai/api/v1/avatars", headers=headers, timeout=10)
resp_data = response.json()
print(len(resp_data["data"]["public_avatars"]))
print(len(resp_data["data"]["my_avatars"]))
始终从该接口返回的结果中选择 avatar_id，不要在代码中写死。要使用形象已配置的声音，请将其非空的 default_voice_id 复制到 text_script.voice_id。
通过照片创建数字人形象
提交一张肖像图片，即可获得 avatar_id。图片来源必须二选一：可公开访问的 HTTPS URL，或包含 Base64 数据的 inline_data：
Shell
curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" -H "Content-Type: application/json" -d '{"img_url": "https://your.site/portrait.jpg"}' https://openapi.visionstory.ai/api/v1/avatar
使用本地文件时，先将其编码为 Base64，再放入 inline_data：
Python
import base64
import os
import requests
headers = {"X-API-Key": os.environ["VISIONSTORY_API_KEY"]}
with open("/path/to/image.jpg", "rb") as f:
encoded = base64.b64encode(f.read()).decode("utf-8")
payload = {"inline_data": {"mime_type": "image/jpg", "data": encoded}}
response = requests.post("https://openapi.visionstory.ai/api/v1/avatar", json=payload, headers=headers)
print(response.json()["data"]["avatar_id"])
保存返回的 avatar_id，之后需要该形象出镜的视频请求都可以使用它。
照片要求： 建议使用单人、清晰、正面的肖像，以获得更好的效果。支持 JPEG、PNG、WEBP 和 HEIC，文件不超过 10 MB。
在数字人视频中使用形象
创建视频时传入 avatar_id：
JSON
{
"model_id": "vs_character_v4",
"avatar_id": "YOUR_AVATAR_ID",
"text_script": { "text": "Hello!", "voice_id": "YOUR_VOICE_ID" }
}
完整的生成、轮询和下载流程见快速开始。
删除专属形象
只能删除你自己的专属形象；删除不会影响此前已使用该形象生成的视频：
Shell
curl -s -X DELETE -H "X-API-Key: $VISIONSTORY_API_KEY" "https://openapi.visionstory.ai/api/v1/avatar?avatar_id=YOUR_AVATAR_ID"