Talking Avatar Video/Generate video

Generate video

POST/api/v1/video

Generate a talking-avatar video: an avatar speaks a script provided either as text-to-speech (text_script) or pre-recorded audio (audio_script). Generation is asynchronous — poll GET /api/v1/video for status. Finished videos are retained for 7 days, so download promptly.

Pass client_request_id to make retries idempotent (no double charge).

Headers

X-API-KeystringRequired

Your VisionStory API key (sk-vs-...), kept server-side. Create one at OpenApi (Pro plan and up).

Request body

avatar_idstringRequired

Avatar that speaks the script. Use an id from GET /api/v1/avatars (public or your own).

client_request_idstring | nullOptional

Optional idempotency key. Resubmitting with the same value within 24h returns the original task instead of creating (and charging) a new one. Safe for retries.

model_idstringOptionalDefault "vs_character_v4"

Rendering model to use; see GET /api/v1/models. Defaults to vs_character_v4. Note: when omitted and resolution is 480p, vs_talk_v1 is selected automatically.

text_scriptTextScript | nullOptional

Text-to-speech script (text + voice). Provide either text_script or audio_script.

Show 3 propertiesHide 3 properties

textstringRequired

The script to speak; converted to speech with the selected voice.

voice_idstringRequired

Voice to synthesize the script with. Use an id from GET /api/v1/voices (a public or your own cloned voice).

speech_ratestring | nullOptionalDefault "normal"

Speaking speed of the synthesized voice; defaults to normal.

Allowed values slow normal fast

audio_scriptAudioScript | nullOptional

Pre-recorded narration audio to drive the avatar. Provide either audio_script or text_script.

Show 5 propertiesHide 5 properties

audio_urlstring | nullOptional

Publicly reachable URL of narration audio to drive the avatar. Provide either this or inline_data.

inline_dataInlineDataModel | nullOptional

Narration audio as inline base64 data. Provide either this or audio_url.

Show 2 propertiesHide 2 properties

mime_typestringRequired

MIME type of the inline data, used to detect image vs audio. Audio: ['audio/avi', 'audio/mpeg', 'audio/mp3', 'audio/mp4', 'audio/m4a', 'audio/wav']; images: ['image/jpeg', 'image/jpg', 'image/png', 'image/webp', 'image/heic'].

datastringRequired

The file's raw bytes encoded as a base64 string (no data: URI prefix).

voice_changebooleanOptionalDefault false

If true, re-synthesize the uploaded audio with the voice in voice_id (voice conversion) while keeping the original timing.

voice_idstring | nullOptional

Target voice for conversion when voice_change is true. Use an id from GET /api/v1/voices.

denoisebooleanOptionalDefault false

If true, apply noise reduction to the uploaded audio before generation.

aspect_ratiostringOptionalDefault "9:16"

Output aspect ratio for the rendered video; defaults to 9:16.

Allowed values 9:16 16:9 1:1

resolutionstringOptionalDefault "720p"

Output resolution. Higher values cost more credits and take longer to render; defaults to 720p. Note: vs_talk_v1 does not support 2k.

Allowed values 480p 720p 1080p 2k

emotionstringOptionalDefault "cheerful"

Expressive tone the avatar performs; defaults to cheerful.

Allowed values cheerful angry marketing news singing

background_colorstringOptionalDefault ""

Optional solid background as a 6-digit hex color, e.g. #00b140. Leave empty to keep the avatar's original background; setting it renders the avatar on this color (chroma-key friendly).

Response

200Successful Response

Successful calls return a standard envelope: the endpoint payload under data (its fields are documented below), plus a message string ("success") and an ISO 8601 server_time.

Response fields (data)

video_idstringRequired

Identifier of the newly created video task. Poll GET /api/v1/video with it to track progress.

Errors

All error responses share one JSON envelope: an error object with a numeric code, a human-readable message, an optional details string, and an optional hint giving an actionable next step (handy for AI agents).

errorErrorDetailRequired

Error payload returned with every non-2xx response. Present only on failure; successful calls use the standard success envelope instead.

Show 4 propertiesHide 4 properties

codeintegerRequired

Machine-readable error code. Mirrors the HTTP status for transport-level failures (e.g. 401, 404, 422, 500) and may carry a business-specific code otherwise.

messagestringRequired

Human-readable explanation of what went wrong. Safe to log or surface to end users; not localized.

detailsstring | nullOptional

Optional structured detail about the failure, e.g. a JSON string of per-field validation errors on a 422. Absent when there is nothing extra to report.

hintstring | nullOptional

Actionable next step for resolving the error, written for both humans and AI agents (e.g. how to fix the request, or where to obtain an API key). May be absent.

Request

curl -X POST 'https://openapi.visionstory.ai/api/v1/video' \
  -H 'X-API-Key: sk-vs-xxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "client_request_id": "client_request_a1b2c3d4e5f6",
  "model_id": "vs_character_v4",
  "avatar_id": "4321918387609092991",
  "text_script": {
    "text": "string",
    "voice_id": "Alice",
    "speech_rate": "normal"
  },
  "audio_script": {
    "audio_url": "https://cdn.visionstory.ai/example.png",
    "inline_data": null,
    "voice_change": false,
    "voice_id": "Alice",
    "denoise": false
  },
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "emotion": "cheerful",
  "background_color": ""
}'

import requests

url = "https://openapi.visionstory.ai/api/v1/video"
headers = {
    "X-API-Key": "sk-vs-xxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
}
payload = {
  "client_request_id": "client_request_a1b2c3d4e5f6",
  "model_id": "vs_character_v4",
  "avatar_id": "4321918387609092991",
  "text_script": {
    "text": "string",
    "voice_id": "Alice",
    "speech_rate": "normal"
  },
  "audio_script": {
    "audio_url": "https://cdn.visionstory.ai/example.png",
    "inline_data": None,
    "voice_change": False,
    "voice_id": "Alice",
    "denoise": False
  },
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "emotion": "cheerful",
  "background_color": ""
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

const response = await fetch("https://openapi.visionstory.ai/api/v1/video", {
  method: "POST",
  headers: {
    "X-API-Key": "sk-vs-xxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "client_request_id": "client_request_a1b2c3d4e5f6",
    "model_id": "vs_character_v4",
    "avatar_id": "4321918387609092991",
    "text_script": {
      "text": "string",
      "voice_id": "Alice",
      "speech_rate": "normal"
    },
    "audio_script": {
      "audio_url": "https://cdn.visionstory.ai/example.png",
      "inline_data": null,
      "voice_change": false,
      "voice_id": "Alice",
      "denoise": false
    },
    "aspect_ratio": "9:16",
    "resolution": "720p",
    "emotion": "cheerful",
    "background_color": ""
  }),
});
const data = await response.json();
console.log(data);

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload := []byte(`{
  "client_request_id": "client_request_a1b2c3d4e5f6",
  "model_id": "vs_character_v4",
  "avatar_id": "4321918387609092991",
  "text_script": {
    "text": "string",
    "voice_id": "Alice",
    "speech_rate": "normal"
  },
  "audio_script": {
    "audio_url": "https://cdn.visionstory.ai/example.png",
    "inline_data": null,
    "voice_change": false,
    "voice_id": "Alice",
    "denoise": false
  },
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "emotion": "cheerful",
  "background_color": ""
}`)
	req, _ := http.NewRequest("POST", "https://openapi.visionstory.ai/api/v1/video", bytes.NewBuffer(payload))
	req.Header.Set("X-API-Key", "sk-vs-xxxxxxxxxxxxxxxxxxx")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://openapi.visionstory.ai/api/v1/video"))
    .header("X-API-Key", "sk-vs-xxxxxxxxxxxxxxxxxxx")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
        {
          "client_request_id": "client_request_a1b2c3d4e5f6",
          "model_id": "vs_character_v4",
          "avatar_id": "4321918387609092991",
          "text_script": {
            "text": "string",
            "voice_id": "Alice",
            "speech_rate": "normal"
          },
          "audio_script": {
            "audio_url": "https://cdn.visionstory.ai/example.png",
            "inline_data": null,
            "voice_change": false,
            "voice_id": "Alice",
            "denoise": false
          },
          "aspect_ratio": "9:16",
          "resolution": "720p",
          "emotion": "cheerful",
          "background_color": ""
        }"""))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

<?php
$ch = curl_init("https://openapi.visionstory.ai/api/v1/video");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: sk-vs-xxxxxxxxxxxxxxxxxxx",
    "Content-Type: application/json",
]);
$payload = <<<'JSON'
{
  "client_request_id": "client_request_a1b2c3d4e5f6",
  "model_id": "vs_character_v4",
  "avatar_id": "4321918387609092991",
  "text_script": {
    "text": "string",
    "voice_id": "Alice",
    "speech_rate": "normal"
  },
  "audio_script": {
    "audio_url": "https://cdn.visionstory.ai/example.png",
    "inline_data": null,
    "voice_change": false,
    "voice_id": "Alice",
    "denoise": false
  },
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "emotion": "cheerful",
  "background_color": ""
}
JSON;
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

require "net/http"
require "uri"

uri = URI("https://openapi.visionstory.ai/api/v1/video")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = "sk-vs-xxxxxxxxxxxxxxxxxxx"
request["Content-Type"] = "application/json"
request.body = <<~JSON
  {
    "client_request_id": "client_request_a1b2c3d4e5f6",
    "model_id": "vs_character_v4",
    "avatar_id": "4321918387609092991",
    "text_script": {
      "text": "string",
      "voice_id": "Alice",
      "speech_rate": "normal"
    },
    "audio_script": {
      "audio_url": "https://cdn.visionstory.ai/example.png",
      "inline_data": null,
      "voice_change": false,
      "voice_id": "Alice",
      "denoise": false
    },
    "aspect_ratio": "9:16",
    "resolution": "720p",
    "emotion": "cheerful",
    "background_color": ""
  }
  JSON
response = http.request(request)
puts response.body

import Foundation

var request = URLRequest(url: URL(string: "https://openapi.visionstory.ai/api/v1/video")!)
request.httpMethod = "POST"
request.setValue("sk-vs-xxxxxxxxxxxxxxxxxxx", forHTTPHeaderField: "X-API-Key")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = """
{
  "client_request_id": "client_request_a1b2c3d4e5f6",
  "model_id": "vs_character_v4",
  "avatar_id": "4321918387609092991",
  "text_script": {
    "text": "string",
    "voice_id": "Alice",
    "speech_rate": "normal"
  },
  "audio_script": {
    "audio_url": "https://cdn.visionstory.ai/example.png",
    "inline_data": null,
    "voice_change": false,
    "voice_id": "Alice",
    "denoise": false
  },
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "emotion": "cheerful",
  "background_color": ""
}
""".data(using: .utf8)
let (data, _) = try await URLSession.shared.data(for: request)
print(String(data: data, encoding: .utf8) ?? "")

using System;
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://openapi.visionstory.ai/api/v1/video");
request.Headers.Add("X-API-Key", "sk-vs-xxxxxxxxxxxxxxxxxxx");
var payload = """
{
  "client_request_id": "client_request_a1b2c3d4e5f6",
  "model_id": "vs_character_v4",
  "avatar_id": "4321918387609092991",
  "text_script": {
    "text": "string",
    "voice_id": "Alice",
    "speech_rate": "normal"
  },
  "audio_script": {
    "audio_url": "https://cdn.visionstory.ai/example.png",
    "inline_data": null,
    "voice_change": false,
    "voice_id": "Alice",
    "denoise": false
  },
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "emotion": "cheerful",
  "background_color": ""
}
""";
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());

Response

200

{
  "data": {
    "video_id": "7241059991822401536"
  },
  "message": "success",
  "server_time": "2026-01-01T00:00:00Z"
}