什麼是 AI 虛擬人像影片 API？

AI 虛擬人像影片 API 能將數位主持人加上文字或錄製音訊，轉為口型同步的影片，讓應用程式可用程式方式生成。VisionStory 會接受已驗證的伺服器端請求，立即回傳影片 ID，以非同步方式渲染任務，並在生成完成後提供 MP4 URL。

如何使用 VisionStory API 生成 AI 虛擬人像影片？

建立 VisionStory API key、確認你的點數、取得目前的模型／虛擬人像／音色 ID，接著以 text_script 或 audio_script 其中一種提交到 POST /api/v1/video。API 會立即回傳影片 ID。大約每 5 秒輪詢一次任務，直到狀態為 created，然後從 video_url 下載 MP4。

我應該使用 REST API、Python SDK，還是 CLI？

需要不受語言限制的控制時使用 REST；要打造 Python 服務或 notebook 時使用 Python SDK；需要終端機自動化、CI 或批次生成時使用 CLI。這三種介面都使用相同的 VisionStory 資源與非同步影片工作流程。

Codex、Claude Code 或 Cursor 可以幫我生成虛擬人像影片嗎？

可以。安裝 VisionStory Agent Skill 或連接 VisionStory MCP server。支援的 coding agent 可確認點數、列出目前的模型／虛擬人像／音色、準備有效請求、啟動影片任務、監控進度並下載結果，同時讓 API key 保留在你的環境變數或 MCP 密鑰儲存中。

我可以用音訊而不是文字來生成虛擬人像影片嗎？

可以。當你希望虛擬人像依據錄製音訊說話時，請送出 audio_script；當你希望 VisionStory 合成語音時，請送出帶有音色 ID 的 text_script。每次請求請只使用一種 script 類型，不要同時送出兩種。

正式環境整合應該如何處理影片生成？

將影片製作視為非同步任務。保存你的 client request ID 與回傳的影片 ID，大約每 5 秒輪詢一次，任務到達 created 或 failed 時停止。完成的影片 URL 會保留 7 天，因此有需要時請把成品媒體複製到你自己的永久儲存空間。

我應該把 VisionStory API key 存在哪裡？

請將 VISIONSTORY_API_KEY 存放在伺服器環境變數、CI secret 或 MCP client secret store，並透過 X-API-Key request header 傳送。切勿把 key 嵌入瀏覽器程式碼、行動應用程式 bundle、公開 repo、螢幕截圖、log，或任何 AI 聊天訊息中。

Avatar Video API 可以搭配哪些功能？

你可以將虛擬人像影片與文字轉語音、公開或複製音色、可重複使用的圖片與音訊素材、轉錄、AI 圖片生成，以及前沿影片模型組合使用。這些基礎能力可支援在地化解說影片、個人化外聯、自動化學習內容，以及 AI agent 媒體工作流程。

VisionStory API
為開發者打造

使用 VisionStory REST API 或 Python SDK，從文字或音訊生成口型同步的說話虛擬人像影片。探索目前可用的模型、虛擬人像與音色，送出非同步任務並下載完成的 MP4；或透過 CLI、MCP server 或 Agent Skill，把同樣的流程自動化。

瀏覽開發者文件

POST /api/v1/video

REST API
Python SDK
CLI
MCP
Agent Skill

Agent 就緒

你的 Agent 在哪裡工作，它就在哪裡運作。

複製一段設定訊息給你的程式編寫 Agent，或連接 MCP 伺服器，將 VisionStory 作為可重複使用的工具提供給它。

VisionStory CLI

安裝一次，在終端機使用所有 API。

安裝程式會在隔離環境中升級到最新的 PyPI 版本，讓你現有的 Python 專案完全不受影響。

curl -fsSL https://developers.visionstory.ai/cli | bash

macOS · Linux · WSL安裝選項

把這段設定提示詞傳給 Claude Code

Help me set up VisionStory and generate a talking-avatar video.1. Install or update the CLI and Agent Skill:   curl -fsSL https://developers.visionstory.ai/cli | bash   npx skills add visionstory-ai/skills --skill visionstory-api2. Run visionstory doctor. If I need a key, send me to https://developers.visionstory.ai/api-keys, wait while I create one, then ask me to run visionstory login in my terminal. Never ask me to paste the key into chat or expose it.3. Verify access with visionstory credits. Stop and help me if it fails.4. Discover current models, avatars, and voices, then use the CLI and visionstory-api skill to create and download the video. Never delete anything unless I explicitly request and confirm it.

第一次使用嗎？

建立 API Key，然後把這段提示詞傳給你的程式編寫 Agent。它會帶你完成 visionstory 登入、確認點數，並在不暴露你的 Key 的情況下製作影片。

VisionStory 開發者工具

選擇最適合你技術棧的 API 整合方式。

REST、Python SDK、CLI、MCP server 與 Agent Skill 都共用同一套已驗證的 VisionStory API 與資源 ID。你可以先從任一介面開始，再把同一套虛擬人像影片流程搬進後端、CI pipeline 或 coding agent。

01REST

呼叫 REST API

用任何後端語言呼叫 VisionStory。列出目前的模型、虛擬人像與音色；將一份 text_script 或 audio_script 送到 POST /api/v1/video；輪詢任務直到建立完成；接著下載 MP4。

查看 REST API 參考文件 02PYTHON

用 Python SDK 開發

使用具型別、零相依的 Python client，完成以環境變數驗證、payload 組裝、上傳、任務輪詢與下載。適用於 Python 應用程式、notebook 與內部媒體服務。

閱讀 Python SDK 快速開始 03CLI

用 CLI 自動化

執行 visionstory doctor、確認點數、探索資源 ID、生成虛擬人像影片、檢視任務，並在終端機、shell script 或 CI job 中下載結果——無需先打造完整應用程式。

安裝並驗證 CLI 04MCP / SKILL

連接 AI coding agent

連接 VisionStory MCP server 或安裝 Agent Skill，讓 Codex、Claude Code、Cursor、Windsurf、Cline 與 Gemini 能夠探索資源、生成媒體並下載結果，同時讓 API key 仍保留在本機的 secret storage。

連接 MCP 或 Agent Skill

說話虛擬人像 API 快速開始

生成你的第一支說話虛擬人像影片。

建立伺服器端 API key、確認你的點數餘額，並取得目前的模型、虛擬人像與音色 ID。將一份 text_script 或 audio_script 送到 POST /api/v1/video，每 5 秒左右輪詢一次直到任務建立完成，接著下載 MP4。已完成影片的 URL 會保留 7 天。

create_video.py

from pathlib import Pathfrom visionstory import VisionStoryClient, build_video_payload client = VisionStoryClient.from_env()payload = build_video_payload(    avatar_id="YOUR_AVATAR_ID",    text="Hello from my product.",    voice_id="YOUR_VOICE_ID",)video = client.generate_video(payload)client.download(video["video_url"], Path("result.mp4"))

VisionStory 模型目錄

選擇符合你輸出需求的模型。

先從你要完成的任務出發，再在執行階段抓取最新的模型目錄。可用的 ID、可接受的參數與輸出限制，皆以 API 回應為準。

使用 VisionStory V-Character 說話虛擬人像模型生成的主持人

說話虛擬人像VisionStory

V-Character 4.0

vs_character_v4

VisionStory 原生角色模型可將一張人像照片加上文字或錄製音訊，轉換為身分一致的演出，具備富表情的動作與自然口型同步。

文字或錄製音訊
720p、1080p 或 2K
最長 10 分鐘

AI 影片ByteDance

Seedance 2.5

seedance-2.5

以文字提示或圖片引導生成影片，具備連貫的動作、電影感鏡頭運動，並支援更長的單段片段。

文字轉影片
圖片轉影片
4–30 秒片段

AI 圖片Google

Nano Banana 2

nano-banana-2

生成高解析度圖片、穩定呈現文字，並透過對話式、參考引導的編輯來精修成果。

提示詞轉圖片
參考引導式編輯
1K 與 2K 輸出

可組合的 AI 媒體 API

整合虛擬人像、音色與 AI 影片 API。

用一組 API key 就能打造會說話的主持人、合成自然語音、重用自訂虛擬人像與音色及媒體資產，並生成輔助影片片段。無需拼接多家供應商，即可製作在地化解說、個人化新手導引、教學內容、銷售外聯或由 agent 生成的媒體。

核心虛擬人像流程

說話虛擬人像影片 API

從文字或錄製音訊生成口型同步的主持人影片。選擇公開虛擬人像，或用一張人像建立可重用的自訂虛擬人像；再挑選公開或複製的音色，待非同步任務完成後即可取得可下載的 MP4。

音色與語音層

文字轉語音與音色 API

將文字轉換為自然的 MP3 語音，可使用公開音色或複製音色，並在虛擬人像影片與在地化內容中重複使用同一個音色。以執行階段查詢音色目錄，取代硬編碼音色 ID。

Agent 指揮式創作

AI 影片生成 API

從即時目錄中選擇模型，生成文字轉影片、圖片轉影片與參考引導片段。AI agent 可準備提示詞與素材、估算點數、提交任務，並將結果與虛擬人像主持人合成。

AI 虛擬人像影片 API 常見問題

針對驗證、請求、非同步任務、SDK、CLI 自動化、MCP 與正式環境使用的直接解答。

AI 虛擬人像影片 API 能將數位主持人加上文字或錄製音訊，轉為口型同步的影片，讓應用程式可用程式方式生成。VisionStory 會接受已驗證的伺服器端請求，立即回傳影片 ID，以非同步方式渲染任務，並在生成完成後提供 MP4 URL。
建立 VisionStory API key、確認你的點數、取得目前的模型／虛擬人像／音色 ID，接著以 text_script 或 audio_script 其中一種提交到 POST /api/v1/video。API 會立即回傳影片 ID。大約每 5 秒輪詢一次任務，直到狀態為 created，然後從 video_url 下載 MP4。
需要不受語言限制的控制時使用 REST；要打造 Python 服務或 notebook 時使用 Python SDK；需要終端機自動化、CI 或批次生成時使用 CLI。這三種介面都使用相同的 VisionStory 資源與非同步影片工作流程。
可以。安裝 VisionStory Agent Skill 或連接 VisionStory MCP server。支援的 coding agent 可確認點數、列出目前的模型／虛擬人像／音色、準備有效請求、啟動影片任務、監控進度並下載結果，同時讓 API key 保留在你的環境變數或 MCP 密鑰儲存中。
可以。當你希望虛擬人像依據錄製音訊說話時，請送出 audio_script；當你希望 VisionStory 合成語音時，請送出帶有音色 ID 的 text_script。每次請求請只使用一種 script 類型，不要同時送出兩種。
將影片製作視為非同步任務。保存你的 client request ID 與回傳的影片 ID，大約每 5 秒輪詢一次，任務到達 created 或 failed 時停止。完成的影片 URL 會保留 7 天，因此有需要時請把成品媒體複製到你自己的永久儲存空間。
請將 VISIONSTORY_API_KEY 存放在伺服器環境變數、CI secret 或 MCP client secret store，並透過 X-API-Key request header 傳送。切勿把 key 嵌入瀏覽器程式碼、行動應用程式 bundle、公開 repo、螢幕截圖、log，或任何 AI 聊天訊息中。
你可以將虛擬人像影片與文字轉語音、公開或複製音色、可重複使用的圖片與音訊素材、轉錄、AI 圖片生成，以及前沿影片模型組合使用。這些基礎能力可支援在地化解說影片、個人化外聯、自動化學習內容，以及 AI agent 媒體工作流程。

從一次已驗證的請求開始

打造你的第一個 AI 虛擬人像影片整合。

建立 API key、確認你的點數，並執行 5 步驟的會說話虛擬人像快速開始。先從 REST 或 Python 上手，接著隨著流程成長再加入 CLI 自動化、MCP 工具或 Agent Skill。請改用即時資源端點查詢，而不是硬編碼模型、虛擬人像或音色 ID。

建立 VisionStory API key 查看開發者文件