List avatars
October 7, 2026 (November 16, 2026)
Table of contents
List the avatars saved in your accounts’ Vids documents, each with an avatarId ready to pass as avatar to POST /videos/avatar (a talking-head video of a script), as avatar_1..avatar_3 to POST /videos, or as avatar to POST /avatars to make a changed copy. The list is read live from Google, so it includes avatars made in the Google Vids web app on that document as well as those made with POST /avatars.
An avatar made in the web app with one of Google’s older narrator voices is listed with voice: null and a note. It cannot be used in a video through the API, but it can be the start of a new avatar with another voice: pass its avatarId as avatar to POST /avatars. Make a new avatar with POST /avatars instead.
Each avatar comes with previewMediaId, its picture, which downloads with GET /media/mediaId. A fresh one is made on every call, so download it soon after listing. It is for download only: to start a new avatar from this one, pass its avatarId as avatar to POST /avatars.
Without email, every healthy account is read. An account that could not be read is listed under errors, and the others are still returned.
https://api.useapi.net/v1/google-vids/avatars?email=
Request Headers
Authorization: Bearer {API token}
API tokenis required, see Setup useapi.net for details.
Query Parameters
emailis optional, read one account only. URL-encode it.
Responses
-
{ "avatars": [ { "avatarId": "user:[email protected]:eyJnIjoiaDMy…", "name": "Ruby", "voice": "Kaci", "voiceId": "Autonoe", "voiceStyle": "Bright", "voicePreview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Autonoe.wav", "previewMediaId": "user:[email protected]:eyJ1IjoiaHR0cHM6Ly9kb2NzLmdvb2dsZS5jb20v…", "email": "[email protected]" }, { "avatarId": "user:[email protected]:eyJnIjoiaDMy…", "name": "Marco", "voice": "Holt", "voiceId": "Charon", "voiceStyle": "Informative", "voicePreview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Charon.wav", "previewMediaId": "user:[email protected]:eyJ1IjoiaHR0cHM6Ly9kb2NzLmdvb2dsZS5jb20v…", "email": "[email protected]" } ] }avatarsis[]when no account has an avatar.
-
400 Bad Request —
emailis not a valid email, or no account is connected yet.{ "error": "Please configure at least one account at https://useapi.net/docs/api-google-vids-v1/post-google-vids-accounts", "code": 400 } -
Invalid API token.
{ "error": "useapi.net ⁝ Unauthorized", "code": 401 } -
404 Not Found — the account named by
emailis not connected.{ "error": "Account [email protected] is not configured", "code": 404 }
Model
Your accounts’ avatars, each with its avatarId, name, voice, preview picture and account, plus errors for accounts that could not be read.
The list of avatars, field by field
{ // TypeScript, all fields are optional
avatars: {
avatarId: string // pass it as avatar_1..avatar_3 to POST /videos
name: string
voice: string | null // the Vids voice name, null for an older narrator voice
voiceId?: string // Google's voice id
voiceStyle?: string // Google's label for the voice
voicePreview?: string // a public English sample of the voice (WAV)
previewMediaId?: string // the avatar's picture: download it with GET /media/{mediaId}
note?: string // voice null: why the avatar cannot be used in a video
email: string // the account the avatar is saved on
}[]
errors?: { // accounts that could not be read
email: string
error: string
}[]
}
Examples
-
curl "https://api.useapi.net/v1/google-vids/avatars?email=user%40example.com" \ -H "Authorization: Bearer …" -
const token = "API token"; const apiUrl = "https://api.useapi.net/v1/google-vids/avatars"; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); -
import requests token = "API token" apiUrl = "https://api.useapi.net/v1/google-vids/avatars" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json())