VisionStory 数字人形象 API 为数字人视频提供出镜角色。你可以查询自己的形象或公共形象库，通过一张肖像创建可复用的专属形象，并控制专属形象在各个支持画幅中的取景。
数字人形象接口
| 方法 | 路径 | 功能 |
|---|---|---|
GET | /api/v1/avatars | 分页查询专属形象或公共形象库 |
POST | /api/v1/avatar | 通过图片创建专属形象 |
POST | /api/v1/avatar/framing | 更新专属形象在一个画幅下的取景 |
DELETE | /api/v1/avatar | 删除你的一个专属形象 |
查询专属形象或公共形象
每次请求只返回一种形象。GET /api/v1/avatars 默认查询当前账户拥有的形象；设置 is_public=true 后改为查询公共形象库。结果按创建时间从新到旧排列，并使用 cursor 分页：
curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" "https://openapi.visionstory.ai/api/v1/avatars?is_public=false&limit=20"
import os
import requests
headers = {"X-API-Key": os.environ["VISIONSTORY_API_KEY"]}
params = {"is_public": False, "limit": 20}
while True:
response = requests.get(
"https://openapi.visionstory.ai/api/v1/avatars",
headers=headers,
params=params,
timeout=10,
)
data = response.json()["data"]
for avatar in data["avatars"]:
print(avatar["avatar_id"], avatar["default_voice_id"])
if not data["next_cursor"]:
break
params["cursor"] = data["next_cursor"]
响应结构为 { "avatars": [...], "next_cursor": 0 }；next_cursor=0 表示没有下一页。limit 可取 1–100，默认值为 20。专属形象会返回真实的 created_at，以及按 9:16、16:9、1:1 顺序排列的三项 framing；公共形象始终返回 framing: null。
始终从该接口返回的结果中选择 avatar_id，不要在代码中写死。要使用形象已配置的声音，请将非空的 default_voice_id 复制到 text_script.voice_id。
通过照片创建数字人形象
提交一张肖像图片，即可获得 avatar_id。图片来源必须二选一：可公开访问的 HTTPS URL，或包含 Base64 数据的 inline_data：
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：
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。
调整形象取景
专属形象会返回三个画幅的当前取景。先读取 GET /api/v1/avatars 返回的值，每次调整一个画幅，并提交全部五个必填字段：
curl -s -X POST -H "X-API-Key: $VISIONSTORY_API_KEY" -H "Content-Type: application/json" -d '{"avatar_id":"YOUR_AVATAR_ID","aspect_ratio":"9:16","zoom":1.2,"offset_x":0,"offset_y":-0.25}' https://openapi.visionstory.ai/api/v1/avatar/framing
zoom=1 表示在源图内能够完整容纳所选画幅的最宽取景；数值越大，人物越近。offset_x 和 offset_y 的范围都是 -1 到 1，其中 0 表示居中。API 会确保取景框位于源图范围内，确认其中存在清晰人脸后保存，并用于该画幅之后生成的视频。
只能调整当前账户拥有的形象。缺少源图尺寸的旧形象可能返回 framing_unavailable。源图过小、无法用于某个画幅时，该画幅的 zoom、offset_x 和 offset_y 返回 null；其 image_url 仍可使用，其他画幅也可能仍可调整。写回构图前请逐一检查画幅。如果 zoom 使裁剪区域过小，400 响应的 details 中会提供 max_zoom。当 max_zoom 为 null 时，请使用更大的源图重新创建形象，或选择构图参数不为空的画幅。
在数字人视频中使用形象
创建视频时传入 avatar_id：
{
"model_id": "vs_character_v4",
"avatar_id": "YOUR_AVATAR_ID",
"text_script": { "text": "Hello!", "voice_id": "YOUR_VOICE_ID" }
}
完整的生成、轮询和下载流程见快速开始。
删除专属形象
只能删除你自己的专属形象；删除不会影响此前已使用该形象生成的视频：
curl -s -X DELETE -H "X-API-Key: $VISIONSTORY_API_KEY" "https://openapi.visionstory.ai/api/v1/avatar?avatar_id=YOUR_AVATAR_ID"
相关 VisionStory API 指南
- 声音 — 选择或克隆数字人使用的声音。
- 快速开始 — 生成第一个视频。
- 形象取景 API 参考 — 查看准确的取景字段、取值范围、响应和错误说明。
- API 参考 — 查看完整请求和响应结构。