VisionStory Python SDK 指南

visionstory 是 VisionStory API 的官方 Python SDK。这个无运行时依赖的客户端仅使用 Python 标准库，负责认证、JSON 处理、Base64 上传、异步轮询、错误处理和媒体下载。

需要 Python 3.10 或更高版本。

安装 VisionStory Python SDK

Shell

pip install visionstory

发现 SDK 新功能

在交互式 Python 会话中，SDK 每天最多检查一次 VisionStory 版本清单；有新版时，每周最多显示一次升级提醒，包含最新版本、版本标题、升级命令和更新日志。离线时会静默跳过检查，不会修改已安装的包。

在 Notebook、服务端进程或 CI 任务中，可以主动检查更新：

Python

from visionstory import check_for_updates

print(check_for_updates())
# installed_version, latest_version, update_available, highlights, update_command

设置 VISIONSTORY_UPDATE_CHECK=0 可关闭被动提醒；设置 VISIONSTORY_UPDATE_CHECK=1 可强制启用交互式提醒行为。机器可读版本清单位于 /releases/latest.json。

配置 Python 客户端认证

默认配置：连接官方 API

一般情况下，只需配置 VISIONSTORY_API_KEY，然后使用 from_env()。不需要填写域名，也不必调整超时时间。

先到 API Key 页面创建密钥，再通过应用的环境变量或部署平台的密钥存储提供给 Python 进程。不要把真实密钥写入代码、聊天或提交到 Git 的环境文件。

Python

from visionstory import VisionStoryClient

client = VisionStoryClient.from_env()
print(client.get_credits())  # Read-only authentication check; does not generate media

如果只是本地测试，还没有配置环境变量，可在自己的终端中先运行下面的 Python 代码，再创建客户端。输入会隐藏；密钥仅在当前 Python 进程内有效，不会保存到后续终端：

Python

import getpass
import os

os.environ["VISIONSTORY_API_KEY"] = getpass.getpass("VisionStory API key (hidden): ")

配置项	默认行为	自定义方式
API Key	`from_env()` 读取 `VISIONSTORY_API_KEY`；缺失或为空时会报错	设置环境变量，或在构造函数中传入 `api_key`
API 地址	未设置 `VISIONSTORY_API_BASE` 时使用 `https://openapi.visionstory.ai`	为 `from_env()` 设置 `VISIONSTORY_API_BASE`，或在构造函数中传入 `base_url`
HTTP 超时	未被具体操作覆盖的请求默认为 60 秒	传入 `request_timeout`，单位为秒

SDK 与 CLI 的认证相互独立。 from_env() 只读取当前进程的环境变量，不会自动加载 .env 文件，也不会读取 visionstory login 保存的密钥。请在创建客户端前，由应用加载或注入环境变量。

自定义配置：使用其他 API 地址

仅在需要使用可信且兼容 VisionStory API 的代理、网关或测试服务时配置。最简单的方式是修改环境变量，Python 代码保持不变：

Shell

# macOS / Linux / WSL shell; applies to this terminal and its child processes
export VISIONSTORY_API_BASE="https://your-api.example.com"

Python

from visionstory import VisionStoryClient

client = VisionStoryClient.from_env(request_timeout=120)

恢复官方地址时，移除覆盖设置（在同一 Shell 中执行 unset VISIONSTORY_API_BASE），然后重新创建客户端。不要将变量设为空字符串。

需要为单个客户端指定配置时，直接传入参数：

Python

import os
from visionstory import VisionStoryClient

client = VisionStoryClient(
    api_key=os.environ["VISIONSTORY_API_KEY"],
    base_url="https://your-api.example.com",
    request_timeout=120,
)

配置优先级： from_env() 读取密钥与地址两个环境变量；直接调用构造函数则使用传入参数和默认值，不读取 VISIONSTORY_API_BASE。因此，构造函数省略 base_url 时，即使设置了该环境变量，也仍使用官方地址。修改环境变量不会改变已创建的客户端。

仅使用可信的 HTTPS 地址。 SDK 会将密钥放在 X-API-Key 请求头中发送给目标服务。基础地址末尾不要加 /api/v1，SDK 方法会自动拼接 /api/v1/models 等路径。更换域名并不代表可以调用不兼容的其他 API。

request_timeout 控制 HTTP 请求超时，不是整个视频的渲染等待时间；部分操作使用自己的请求超时。异步等待通过 wait_for_video(..., timeout=600) 单独设置，下载则使用 client.download(url, path, timeout=120)。

在 Python 中生成数字人视频

generate_video 会提交任务并轮询至完成，一次调用即可取得生成好的视频：

Python

from pathlib import Path
from visionstory import VisionStoryClient, build_video_payload

client = VisionStoryClient.from_env()

payload = build_video_payload(
    avatar_id="YOUR_AVATAR_ID",        # select from client.list_avatars()
    text="Hello World, this is my first video.",
    voice_id="YOUR_VOICE_ID",          # select from client.list_voices()
)
video = client.generate_video(payload)          # submit + poll until "created"
client.download(video["video_url"], Path("result.mp4"))
print("saved result.mp4")

build_video_payload 接受 text 或 audio_url / audio_file（三者只能选一个），以及可选的 model_id、aspect_ratio、resolution、speech_rate 等参数，直接映射到 POST /api/v1/video 请求体。

使用 VisionStory CLI

独立的 visionstory-cli 包提供 visionstory 命令，覆盖相同能力，无需编写代码：

Shell

visionstory create-video --avatar-id YOUR_AVATAR_ID --text "Hello from VisionStory." --voice-id YOUR_VOICE_ID --output result.mp4

完整命令、参数和示例见 CLI 指南。

查询模型、形象、声音和点数

不要写死资源 ID，应在运行时查询并选择：

Python

client.list_models()      # avatar render models
client.list_avatars()     # your avatars + public ones
client.list_voices(locale="es-MX", provider="minimax", limit=50)
client.get_credits()      # remaining balance

检查 SDK、CLI 与 MCP 的兼容性

Python

from visionstory import get_contract_info

print(get_contract_info())
# contract_version, SHA-256 contract_hash, and operation_count=27

可以通过 visionstory contract 和 MCP 资源 visionstory://contract 获取相同指纹。指纹一致意味着 SDK、CLI 和 MCP Server 基于同一份 OpenAPI 及渠道映射构建。

创建形象、克隆声音与上传素材

Python

client.create_avatar(image_url="https://your.site/face.jpg")   # or image_file=Path("face.jpg")
client.clone_voice(audio_url="https://your.site/sample.mp3")   # or audio_file=Path("sample.mp3")
client.upload_asset(url="https://your.site/clip.mp4")          # or file_path=Path("clip.mp4")

upload_asset 返回可复用的 asset_id，可以在 AI 视频请求中引用。

转写音频与创建字幕

使用本地路径、公开 URL 或可复用素材转写 WAV 或 MP3 音频。设置 diarize=True 返回说话人标签，设置 srt=True 输出字幕：

Python

from pathlib import Path

transcript = client.transcribe_audio(
    audio_file=Path("interview.mp3"),
    diarize=True,
    srt=True,
)
Path("interview.srt").write_text(transcript["srt"], encoding="utf-8")

alignment = client.align_audio(
    text="Welcome to VisionStory.",
    asset_id="YOUR_AUDIO_ASSET_ID",
)

请求结构、限制、词级时间戳和计费方式见音频转写与对齐。

合成指定语言地区的语音

Python

speech = client.create_speech(
    text="Welcome to VisionStory.",
    voice_id="YOUR_VOICE_ID",
    locale="en-GB",
)
Path("speech.mp3").write_bytes(speech["audio"])

控制异步轮询

需要展示进度或在等待期间执行其他操作时，可以分开提交和轮询：

Python

created = client.create_video(payload)          # returns immediately with a video_id
video = client.wait_for_video(created["video_id"], poll_interval=5, timeout=600)

generate_video(payload, wait=False) 等同于 create_video。

处理 SDK 错误与超时

Python

from visionstory import VisionStoryAPIError, VideoTimeoutError

try:
    video = client.generate_video(payload)
except VideoTimeoutError:
    ...   # still not finished after `timeout` seconds
except VisionStoryAPIError as e:
    ...   # API returned an error, or the task failed — credits for failed tasks are refunded automatically

快速开始 — 分步骤完成相同流程。
面向 Agent — 让 AI Agent 通过 Skill 或 MCP Server 调用 API。
音频转写与对齐 — 语音转文字、SRT 和强制对齐。
API 参考 — 查看 SDK 封装的全部接口。

结构化媒体提取与语速

使用 understand_media 从图片、音频或视频中提取符合 Schema 约束的 JSON。必填参数为 prompt、inputs 和 schema；同步等待最长 180 秒，返回 output、usage 和 cost_credit。

Python

from visionstory import VisionStoryClient

client = VisionStoryClient.from_env()
result = client.understand_media(
    prompt="Identify the subject",
    inputs=[{"asset_id": "YOUR_ASSET_ID"}],
    schema={"type": "object", "properties": {"subject": {"type": "string"}}, "required": ["subject"]},
)
print(result["output"])

speech = client.create_speech(text="Hello", voice_id="YOUR_VOICE_ID", speech_rate="slow")
# Save speech["audio"] as MP3. Omit speech_rate to keep normal speed.

speech_rate 接受 slow、normal 或 fast，传入 None 时不发送此字段。输入限制、计费和超时处理见媒体理解；二进制响应见文本转语音。