Avatars/Create avatar

Create avatar

POST/api/v1/avatar

Create a custom avatar from a single portrait image (JPEG/PNG/WEBP/HEIC, up to 10MB). The returned avatar_id can then speak any script via POST /api/v1/video.

The avatar starts with automatic framing; the response includes it as framing. Change it with POST /api/v1/avatar/framing.

Headers

X-API-KeystringRequired

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

Request body

img_urlstring | nullOptional

Publicly reachable URL of the source image. Provide either this or inline_data. Formats: JPEG/PNG/WEBP/HEIC, up to 10MB.

inline_dataInlineDataModel | nullOptional

Source image as inline base64 data. Provide either this or img_url.

Show 2 propertiesHide 2 properties

mime_typestringRequired

MIME type of the inline data; the gateway uses it to tell image / audio / video apart. The accepted set depends on the endpoint — see the field carrying this object. Talking video accepts audio ['audio/avi', 'audio/mpeg', 'audio/mp3', 'audio/mp4', 'audio/m4a', 'audio/wav'] and 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).

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)

avatar_idstringRequired

Unique avatar identifier. Pass it as avatar_id when generating a talking video.

thumbnail_urlstringRequired

URL of the avatar's preview thumbnail image.

aspect_ratiosarray of stringOptional

Aspect ratios this avatar was prepared for (1:1 / 9:16 / 16:9). Choose a matching aspect_ratio when generating a video.

created_atintegerOptionalDefault 0

Unix timestamp (seconds) when the avatar was created.

default_voice_idstringOptionalDefault ""

The voice this avatar was set up with. voice_id is required in a text script, so copy this value when you want the avatar's own voice (rather than guessing one). May be empty for avatars without a preset voice.

framingarray of AvatarFraming | nullOptional

Current framing per aspect ratio, always 3 entries in the order 9:16, 16:9, 1:1. New avatars start with automatic framing; change it with POST /api/v1/avatar/framing. It is shared with the web editor. Always null for public avatars, which cannot be reframed through the API.

Show 5 propertiesHide 5 properties

aspect_ratiostringRequired

Aspect ratio this framing applies to.

Allowed values 9:16 16:9 1:1

zoomnumber | nullOptional

Zoom level, at least 1. 1 is the largest area of this aspect ratio that fits in the avatar's source image (the widest framing, e.g. full body); 2 halves the framed width and height, making the person appear twice as large. null for avatars created before framing was supported.

offset_xnumber | nullOptional

Horizontal position of the framed area within the room it can move, from -1 to 1: -1 touches the left edge, 0 is centered, 1 touches the right edge. It has no effect when the framed area already spans the full width. null when zoom is null.

offset_ynumber | nullOptional

Vertical position of the framed area within the room it can move, from -1 to 1: -1 touches the top edge, 0 is centered, 1 touches the bottom edge. It has no effect when the framed area already spans the full height. null when zoom is null.

image_urlstring | nullOptional

URL of the reference image videos in this aspect ratio currently use.

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/avatar' \
  -H 'X-API-Key: sk-vs-xxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "img_url": "https://cdn.visionstory.ai/example.png",
  "inline_data": {
    "mime_type": "string",
    "data": "string"
  }
}'

import requests

url = "https://openapi.visionstory.ai/api/v1/avatar"
headers = {
    "X-API-Key": "sk-vs-xxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
}
payload = {
  "img_url": "https://cdn.visionstory.ai/example.png",
  "inline_data": {
    "mime_type": "string",
    "data": "string"
  }
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

const response = await fetch("https://openapi.visionstory.ai/api/v1/avatar", {
  method: "POST",
  headers: {
    "X-API-Key": "sk-vs-xxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "img_url": "https://cdn.visionstory.ai/example.png",
    "inline_data": {
      "mime_type": "string",
      "data": "string"
    }
  }),
});
const data = await response.json();
console.log(data);

package main

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

func main() {
	payload := []byte(`{
  "img_url": "https://cdn.visionstory.ai/example.png",
  "inline_data": {
    "mime_type": "string",
    "data": "string"
  }
}`)
	req, _ := http.NewRequest("POST", "https://openapi.visionstory.ai/api/v1/avatar", 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/avatar"))
    .header("X-API-Key", "sk-vs-xxxxxxxxxxxxxxxxxxx")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
        {
          "img_url": "https://cdn.visionstory.ai/example.png",
          "inline_data": {
            "mime_type": "string",
            "data": "string"
          }
        }"""))
    .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/avatar");
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'
{
  "img_url": "https://cdn.visionstory.ai/example.png",
  "inline_data": {
    "mime_type": "string",
    "data": "string"
  }
}
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/avatar")
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
  {
    "img_url": "https://cdn.visionstory.ai/example.png",
    "inline_data": {
      "mime_type": "string",
      "data": "string"
    }
  }
  JSON
response = http.request(request)
puts response.body

import Foundation

var request = URLRequest(url: URL(string: "https://openapi.visionstory.ai/api/v1/avatar")!)
request.httpMethod = "POST"
request.setValue("sk-vs-xxxxxxxxxxxxxxxxxxx", forHTTPHeaderField: "X-API-Key")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = """
{
  "img_url": "https://cdn.visionstory.ai/example.png",
  "inline_data": {
    "mime_type": "string",
    "data": "string"
  }
}
""".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/avatar");
request.Headers.Add("X-API-Key", "sk-vs-xxxxxxxxxxxxxxxxxxx");
var payload = """
{
  "img_url": "https://cdn.visionstory.ai/example.png",
  "inline_data": {
    "mime_type": "string",
    "data": "string"
  }
}
""";
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());

Response

200

{
  "data": {
    "avatar_id": "example_avatar_id",
    "thumbnail_url": "https://example.com/avatar.jpg",
    "aspect_ratios": [
      "9:16",
      "16:9",
      "1:1"
    ],
    "created_at": 1788480000,
    "default_voice_id": "example_voice_id",
    "framing": [
      {
        "aspect_ratio": "9:16",
        "zoom": 1.0,
        "offset_x": 0.0,
        "offset_y": 0.0,
        "image_url": "https://example.com/avatar-9x16.png"
      },
      {
        "aspect_ratio": "16:9",
        "zoom": 1.0,
        "offset_x": 0.0,
        "offset_y": -0.4312,
        "image_url": null
      },
      {
        "aspect_ratio": "1:1",
        "zoom": 1.25,
        "offset_x": 0.0,
        "offset_y": -0.6,
        "image_url": "https://example.com/avatar-1x1.png"
      }
    ]
  },
  "message": "success",
  "server_time": "2026-09-04T00:00:00Z"
}