List avatars

October 7, 2026

Table of contents

  1. Request Headers
  2. Query Parameters
  3. Responses
  4. Model
  5. Examples
  6. Try It

List the avatars saved in your accounts’ Vids documents, each with an avatarId ready to pass as avatar_1..avatar_3 to POST /videos. 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. 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.

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=email

Request Headers 
Authorization: Bearer {API token}
Query Parameters
  • email is optional, read one account only. URL-encode it.
Responses

  • 200 OK

    {
  "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]"
    }
  ]
}
    • avatars is [] when no account has an avatar.

  • 400 Bad Request — email is 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
}

  • 401 Unauthorized

    Invalid API token.

    {
  "error": "useapi.net ⁝ Unauthorized",
  "code": 401
}

  • 404 Not Found — the account named by email is not connected.

    {
  "error": "Account [email protected] is not configured",
  "code": 404
}
Model 
{ // 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())
Try It