AI 아바타 비디오 API란 무엇인가요?

AI 아바타 비디오 API는 디지털 진행자와 텍스트 또는 녹음 오디오를 립싱크된 비디오로 변환해, 애플리케이션이 프로그래밍 방식으로 생성할 수 있게 해줍니다. VisionStory는 인증된 서버 측 요청을 받아 즉시 비디오 ID를 반환하고, 작업을 비동기로 렌더링한 뒤 생성이 완료되면 MP4 URL을 제공합니다.

VisionStory API로 AI 아바타 비디오를 어떻게 생성하나요?

VisionStory API 키를 생성하고 크레딧을 확인한 다음, 최신 모델·아바타·음성 ID를 가져와 POST /api/v1/video에 text_script 또는 audio_script 중 하나를 제출하세요. API는 즉시 비디오 ID를 반환합니다. 약 5초마다 작업을 폴링해 상태가 created가 될 때까지 확인한 뒤, video_url에서 MP4를 다운로드하면 됩니다.

REST API, Python SDK, CLI 중 무엇을 사용해야 하나요?

언어에 독립적인 제어가 필요할 때는 REST를, Python 서비스나 노트북을 만들 때는 Python SDK를, 터미널 자동화·CI·배치 생성에는 CLI를 사용하세요. 세 가지 인터페이스 모두 동일한 VisionStory 리소스와 비동기 비디오 워크플로를 사용합니다.

Codex, Claude Code, Cursor로 아바타 비디오를 생성할 수 있나요?

가능합니다. VisionStory Agent Skill을 설치하거나 VisionStory MCP 서버에 연결하세요. 지원되는 코딩 에이전트는 API 키를 환경 변수 또는 MCP 시크릿 스토리지에 안전하게 유지한 채로, 크레딧 확인, 최신 모델·아바타·음성 목록 조회, 유효한 요청 준비, 비디오 작업 시작, 진행 모니터링, 결과 다운로드까지 수행할 수 있습니다.

텍스트 대신 오디오로 아바타 비디오를 생성할 수 있나요?

네. 녹음된 오디오로 아바타가 말하게 하려면 audio_script를 보내고, VisionStory가 음성을 합성해야 한다면 음성 ID와 함께 text_script를 보내세요. 두 가지를 함께 보내지 말고, 요청당 한 가지 스크립트 타입만 사용하세요.

프로덕션 연동에서는 비디오 생성을 어떻게 처리해야 하나요?

비디오 생성은 비동기 작업으로 처리하세요. 클라이언트 요청 ID와 반환된 비디오 ID를 저장하고 약 5초마다 폴링한 뒤, 작업 상태가 created 또는 failed에 도달하면 중단합니다. 완료된 비디오 URL은 7일간 유지되므로, 필요하다면 완료된 미디어를 자체 영구 스토리지로 복사해 보관하세요.

VisionStory API 키는 어디에 보관해야 하나요?

VISIONSTORY_API_KEY는 서버 환경 변수, CI 시크릿, 또는 MCP 클라이언트 시크릿 스토어에 보관하고 X-API-Key 요청 헤더로 전송하세요. 키를 브라우저 코드, 모바일 앱 번들, 공개 저장소, 스크린샷, 로그, 또는 AI 채팅 메시지에 절대 포함하지 마세요.

Avatar Video API와 무엇을 함께 사용할 수 있나요?

아바타 비디오는 텍스트 음성 변환, 공개 또는 클론 음성, 재사용 가능한 이미지·오디오 에셋, 전사, AI 이미지 생성, 그리고 최신 비디오 모델과 조합할 수 있습니다. 이러한 구성요소를 활용하면 현지화된 설명 콘텐츠, 개인화된 아웃리치, 자동화된 학습 콘텐츠, AI 에이전트 기반 미디어 워크플로를 구현할 수 있습니다.

VisionStory API
개발자를 위해 만들었습니다

VisionStory REST API 또는 Python SDK로 텍스트나 오디오에서 립싱크가 적용된 토킹 아바타 비디오를 제작하세요. 최신 모델·아바타·음성을 확인하고, 비동기 작업을 제출한 뒤 완성된 MP4를 다운로드할 수 있습니다. 또는 CLI, MCP 서버, Agent Skill로 동일한 워크플로우를 자동화하세요.

개발자 문서 보기

POST /api/v1/video

REST API
Python SDK
CLI
MCP
Agent Skill

에이전트 준비 완료

에이전트가 일하는 곳에서 그대로 작동합니다.

코딩 에이전트용 설정 메시지를 한 번만 복사하거나, 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 키를 만든 뒤 이 프롬프트를 코딩 에이전트에게 보내세요. 키를 노출하지 않은 채 visionstory 로그인 안내부터 크레딧 확인, 비디오 생성까지 도와줍니다.

VisionStory 개발자 도구

스택에 맞는 API 연동 방식을 선택하세요.

REST, Python SDK, CLI, MCP 서버, Agent Skill은 모두 동일한 인증된 VisionStory API와 리소스 ID를 사용합니다. 한 가지 인터페이스로 시작한 뒤, 같은 아바타 비디오 워크플로우를 백엔드, CI 파이프라인 또는 코딩 에이전트로 옮겨 확장하세요.

01REST

REST API 호출

어떤 백엔드 언어에서든 VisionStory를 호출하세요. 최신 모델·아바타·음성을 조회한 다음, text_script 또는 audio_script를 POST /api/v1/video로 전송하세요. 작업이 생성될 때까지 폴링한 뒤 MP4를 다운로드하면 됩니다.

REST API 레퍼런스 보기 02PYTHON

Python SDK로 구축

타입이 지정된 무의존성(zero-dependency) Python 클라이언트로 환경 기반 인증, 페이로드 구성, 업로드, 작업 폴링, 다운로드를 처리하세요. Python 애플리케이션, 노트북, 내부 미디어 서비스에 잘 맞습니다.

Python SDK 퀵스타트 읽기 03CLI

CLI로 자동화

애플리케이션을 먼저 만들지 않아도 터미널, 셸 스크립트 또는 CI 작업에서 visionstory doctor 실행, 크레딧 확인, 리소스 ID 조회, 아바타 비디오 생성, 작업 점검, 결과 다운로드까지 처리할 수 있습니다.

CLI 설치 및 확인 04MCP / SKILL

AI 코딩 에이전트 연결

VisionStory MCP 서버를 연결하거나 Agent Skill을 설치하면, Codex, Claude Code, Cursor, Windsurf, Cline, Gemini가 리소스를 탐색하고 미디어를 생성하며 결과를 다운로드할 수 있습니다. API 키는 로컬 시크릿 스토리지에 안전하게 유지됩니다.

MCP 또는 Agent Skill 연결

토킹 아바타 API 퀵스타트

첫 토킹 아바타 비디오를 생성하세요.

서버용 API 키를 만들고 크레딧 잔액을 확인한 다음, 최신 모델·아바타·음성 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의 네이티브 캐릭터 모델은 인물 사진 1장과 텍스트 또는 녹음된 오디오를 바탕으로, 정체성이 일관되게 유지되는 연기와 풍부한 모션, 자연스러운 립싱크를 구현합니다.

텍스트 또는 녹음된 오디오
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 키로 토킹 프레젠터를 만들고 자연스러운 음성을 합성하며, 커스텀 아바타·음성·미디어 자산을 재사용하고, 보조 비디오 클립까지 생성하세요. 여러 제공업체를 따로 연결할 필요 없이 현지화된 설명 영상, 개인화 온보딩, 교육, 영업 아웃리치 또는 에이전트 생성 미디어를 구축할 수 있습니다.

핵심 아바타 워크플로우

토킹 아바타 비디오 API

텍스트 또는 녹음된 오디오에서 립싱크가 적용된 프레젠터 비디오를 생성하세요. 공개 아바타를 선택하거나 인물 사진 1장으로 재사용 가능한 커스텀 아바타를 만들고, 공개 음성 또는 클론 음성을 선택한 뒤, 비동기 작업이 완료되면 다운로드 가능한 MP4를 받을 수 있습니다.

VisionStory 텍스트 음성 변환 API를 통해 스크립트가 오디오 파형으로 변환되는 모습

음성 및 발화 레이어

텍스트 음성 변환 및 음성 API

텍스트를 공개 또는 클론 음성으로 자연스러운 MP3 음성으로 변환한 뒤, 아바타 비디오와 현지화 콘텐츠 전반에서 같은 음성을 재사용하세요. 음성 ID를 하드코딩하는 대신, 런타임에 음성 카탈로그를 조회할 수 있습니다.

VisionStory AI 비디오 API를 통해 프롬프트가 생성 비디오로 변환되는 모습

에이전트 주도 생성

AI 비디오 생성 API

라이브 카탈로그에서 선택한 모델로 텍스트-투-비디오, 이미지-투-비디오, 레퍼런스 가이드 클립을 생성하세요. AI 에이전트가 프롬프트와 에셋을 준비하고, 크레딧을 추정하며, 작업을 제출한 뒤 결과를 아바타 진행자와 결합할 수 있습니다.

AI 아바타 비디오 API FAQ

인증, 요청, 비동기 작업, SDK, CLI 자동화, MCP 및 프로덕션 사용에 대한 핵심 답변을 확인하세요.

AI 아바타 비디오 API는 디지털 진행자와 텍스트 또는 녹음 오디오를 립싱크된 비디오로 변환해, 애플리케이션이 프로그래밍 방식으로 생성할 수 있게 해줍니다. VisionStory는 인증된 서버 측 요청을 받아 즉시 비디오 ID를 반환하고, 작업을 비동기로 렌더링한 뒤 생성이 완료되면 MP4 URL을 제공합니다.
VisionStory API 키를 생성하고 크레딧을 확인한 다음, 최신 모델·아바타·음성 ID를 가져와 POST /api/v1/video에 text_script 또는 audio_script 중 하나를 제출하세요. API는 즉시 비디오 ID를 반환합니다. 약 5초마다 작업을 폴링해 상태가 created가 될 때까지 확인한 뒤, video_url에서 MP4를 다운로드하면 됩니다.
언어에 독립적인 제어가 필요할 때는 REST를, Python 서비스나 노트북을 만들 때는 Python SDK를, 터미널 자동화·CI·배치 생성에는 CLI를 사용하세요. 세 가지 인터페이스 모두 동일한 VisionStory 리소스와 비동기 비디오 워크플로를 사용합니다.
가능합니다. VisionStory Agent Skill을 설치하거나 VisionStory MCP 서버에 연결하세요. 지원되는 코딩 에이전트는 API 키를 환경 변수 또는 MCP 시크릿 스토리지에 안전하게 유지한 채로, 크레딧 확인, 최신 모델·아바타·음성 목록 조회, 유효한 요청 준비, 비디오 작업 시작, 진행 모니터링, 결과 다운로드까지 수행할 수 있습니다.
네. 녹음된 오디오로 아바타가 말하게 하려면 audio_script를 보내고, VisionStory가 음성을 합성해야 한다면 음성 ID와 함께 text_script를 보내세요. 두 가지를 함께 보내지 말고, 요청당 한 가지 스크립트 타입만 사용하세요.
비디오 생성은 비동기 작업으로 처리하세요. 클라이언트 요청 ID와 반환된 비디오 ID를 저장하고 약 5초마다 폴링한 뒤, 작업 상태가 created 또는 failed에 도달하면 중단합니다. 완료된 비디오 URL은 7일간 유지되므로, 필요하다면 완료된 미디어를 자체 영구 스토리지로 복사해 보관하세요.
VISIONSTORY_API_KEY는 서버 환경 변수, CI 시크릿, 또는 MCP 클라이언트 시크릿 스토어에 보관하고 X-API-Key 요청 헤더로 전송하세요. 키를 브라우저 코드, 모바일 앱 번들, 공개 저장소, 스크린샷, 로그, 또는 AI 채팅 메시지에 절대 포함하지 마세요.
아바타 비디오는 텍스트 음성 변환, 공개 또는 클론 음성, 재사용 가능한 이미지·오디오 에셋, 전사, AI 이미지 생성, 그리고 최신 비디오 모델과 조합할 수 있습니다. 이러한 구성요소를 활용하면 현지화된 설명 콘텐츠, 개인화된 아웃리치, 자동화된 학습 콘텐츠, AI 에이전트 기반 미디어 워크플로를 구현할 수 있습니다.

인증된 요청 1번으로 시작하세요

첫 AI 아바타 비디오 연동을 만들어보세요.

API 키를 만들고 크레딧을 확인한 다음, 5단계 말하는 아바타 퀵스타트를 실행하세요. REST 또는 Python으로 시작한 뒤, 워크플로가 성장하면 CLI 자동화, MCP 도구, 또는 Agent Skill을 추가할 수 있습니다. 모델·아바타·음성 ID를 하드코딩하는 대신, 라이브 리소스 엔드포인트를 조회하세요.

VisionStory API 키 만들기 개발자 문서 살펴보기