Avatars/List avatars

List avatars

GET/api/v1/avatars

List either your own avatars or the public avatar library (is_public=true), newest first. Pass the previous page's next_cursor to paginate; next_cursor=0 means no more pages.

Query parameters

is_publicbooleanOptionalDefault false

false lists your own avatars (with their framing); true lists the public avatar library instead.

cursorintegerOptionalDefault 0

Pagination cursor from the previous page's next_cursor. Omit or pass 0 for the first page.

limitintegerOptionalDefault 20

Maximum avatars to return per page. Range 1–100; defaults to 20.

Headers

X-API-KeystringRequired

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

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)

avatarsarray of AvatarDtoRequired

Avatars on this page, newest first: your own avatars, or the public library when the request sets is_public=true.

Show 6 propertiesHide 6 properties

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.

next_cursorintegerOptionalDefault 0

Cursor for the next page; pass it back as cursor. 0 means no more pages.

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 GET 'https://openapi.visionstory.ai/api/v1/avatars?is_public=False&cursor=0&limit=20' \
  -H 'X-API-Key: sk-vs-xxxxxxxxxxxxxxxxxxx'

import requests

url = "https://openapi.visionstory.ai/api/v1/avatars?is_public=False&cursor=0&limit=20"
headers = {
    "X-API-Key": "sk-vs-xxxxxxxxxxxxxxxxxxx",
}
response = requests.get(url, headers=headers)
print(response.json())

const response = await fetch("https://openapi.visionstory.ai/api/v1/avatars?is_public=False&cursor=0&limit=20", {
  method: "GET",
  headers: {
    "X-API-Key": "sk-vs-xxxxxxxxxxxxxxxxxxx",
  },
});
const data = await response.json();
console.log(data);

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://openapi.visionstory.ai/api/v1/avatars?is_public=False&cursor=0&limit=20", nil)
	req.Header.Set("X-API-Key", "sk-vs-xxxxxxxxxxxxxxxxxxx")
	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/avatars?is_public=False&cursor=0&limit=20"))
    .header("X-API-Key", "sk-vs-xxxxxxxxxxxxxxxxxxx")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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/avatars?is_public=False&cursor=0&limit=20");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: sk-vs-xxxxxxxxxxxxxxxxxxx",
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

require "net/http"
require "uri"

uri = URI("https://openapi.visionstory.ai/api/v1/avatars?is_public=False&cursor=0&limit=20")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = "sk-vs-xxxxxxxxxxxxxxxxxxx"
response = http.request(request)
puts response.body

import Foundation

var request = URLRequest(url: URL(string: "https://openapi.visionstory.ai/api/v1/avatars?is_public=False&cursor=0&limit=20")!)
request.httpMethod = "GET"
request.setValue("sk-vs-xxxxxxxxxxxxxxxxxxx", forHTTPHeaderField: "X-API-Key")
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.Get, "https://openapi.visionstory.ai/api/v1/avatars?is_public=False&cursor=0&limit=20");
request.Headers.Add("X-API-Key", "sk-vs-xxxxxxxxxxxxxxxxxxx");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());

Response

200

{
  "data": {
    "avatars": [
      {
        "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"
          }
        ]
      }
    ],
    "next_cursor": 0
  },
  "message": "success",
  "server_time": "2026-09-04T00:00:00Z"
}