POST avatars — Google Vids API v1

Create an avatar

October 7, 2026

Request Headers
Request Body
Responses
Model
Examples
Try It

An avatar is a picture of a person plus a fixed voice. Pass its avatarId as avatar_1..avatar_3 to POST /videos, and the clip shows that person speaking the lines you write in the prompt, in the avatar’s voice. One clip can hold several avatars, for a dialogue.

The picture comes from one of two places:

A description: send appearance, plus outfit, shot, expression and details if you like, and Google draws the person. The response carries the picture as previewMediaId, which GET /media/mediaId downloads.
An image made with POST /images: pass its mediaId as image.

An avatar cannot be made from your own photo. An avatar of a real person is Google’s likeness feature, which requires a live selfie video and a phone check in the browser, and an API cannot do that. POST /avatars refuses an uploaded photo with 400.

The voice is one of the 30 voices listed by GET /voices, named by its Vids name (Holt) or its Google voice id (Charon).

The avatar is saved in the account’s Vids document, where GET /avatars lists it and DELETE /avatars/avatarId removes it. It can be used only by videos on that account.

Cost

Drawing the picture from a description uses 1 image of the account’s monthly Vids images.
An avatar from an image made with POST /images costs nothing more. The image was paid for when it was made.
Voices are free.
A video with an avatar costs its seconds like any other clip, and the avatar takes one of its 3 reference slots.

Creating an avatar takes about 20 seconds from a description and about 2 seconds from an image. It answers when the avatar is saved and takes no maxJobs slot.

https://api.useapi.net/v1/google-vids/avatars

Request Headers

Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data

API token is required, see Setup useapi.net for details.

Request Body

From a description:

{
  "name": "Marco",
  "voice": "Holt",
  "appearance": "a middle-aged man with a short grey beard",
  "outfit": "navy blazer over a white shirt",
  "shot": "upper-body",
  "expression": "a calm, friendly smile",
  "details": "warm studio lighting",
  "email": "[email protected]"
}

From an image made with POST /images:

{
  "name": "Ruby",
  "voice": "Kaci",
  "image": "user:[email protected]:eyJ1IjoiaHR0…"
}

name is required, the avatar’s name. It is a label only and plays no part in a video prompt.
Length: 1 to 40 characters.
voice is required, a voice name or voice id from GET /voices, case-insensitive.
image is the image mediaId of a picture made with POST /images. Send either image or appearance. An assetId of an uploaded photo is refused, see above.
appearance is the person to draw, for example their age, hair and features. Send either appearance or image.
Maximum length: 500 characters.
outfit is optional with appearance, what the person wears.
Maximum length: 300 characters.
shot is optional with appearance, the framing of the picture.
Supported values: close-up (head and shoulders), upper-body (from the waist up), full-body (head to feet). Default: close-up.
expression is optional with appearance, the facial expression. When omitted, Google is asked for a smile with teeth.
Maximum length: 200 characters.
details is optional with appearance, anything else about the picture.
Maximum length: 1000 characters.
email is optional, the account to save the avatar on. With image, it defaults to the account that made the image and must match it. Without image, a healthy account with an image allowance is picked when it is omitted.

Responses

201 Created

From a description:

{
  "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",
  "email": "[email protected]",
  "source": "generated",
  "previewMediaId": "user:[email protected]:eyJ1IjoiaHR0…",
  "look": {
    "appearance": "a middle-aged man with a short grey beard",
    "outfit": "navy blazer over a white shirt",
    "shot": "upper-body",
    "expression": "a calm, friendly smile",
    "details": "warm studio lighting"
  }
}

From an image:

{
  "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",
  "email": "[email protected]",
  "source": "image"
}

400 Bad Request — an unknown voice, neither or both of image and appearance, an uploaded photo, an image from another account than email, an invalid parameter, or Google refused the request.

{
  "error": "Unknown voice Bob. GET /voices lists them (name or voice id)",
  "code": 400
}

{
  "error": "Give image (an image mediaId from POST /images) or appearance (a description to generate the picture from)",
  "code": 400
}

{
  "error": "An avatar from your own photo needs Google's identity check (a live selfie video and phone verification in the browser), which an API cannot do. Use an image made with POST /images (pass its mediaId as image), or describe the person with appearance",
  "code": 400
}

{
  "error": "Parameter name is required",
  "code": 400
}

401 Unauthorized

Invalid API token.

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

403 Forbidden — the image id was issued to a different API token.

{
  "error": "image id does not belong to this API token",
  "code": 403
}

404 Not Found — the account named by email or by the image id is not connected.

{
  "error": "Account [email protected] is not configured",
  "code": 404
}

502 Bad Gateway — Google did not save the avatar. Retry.

{
  "error": "Google did not keep the avatar in the Vids document, please retry",
  "code": 502
}

596 Account Error

Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via Setup Google Vids.

{
  "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.",
  "code": 596
}

{
  "error": "Account [email protected]: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-google-vids",
  "code": 596
}

Model

{ // TypeScript, all fields are optional
  avatarId: string            // user:<id>-<email>-avatar:…, pass it as avatar_1..avatar_3 to POST /videos
  name: string
  voice: string               // the Vids voice name, e.g. 'Holt'
  voiceId: string             // Google's voice id, e.g. 'Charon'
  voiceStyle: string          // Google's label for the voice, e.g. 'Informative'
  voicePreview: string        // a public English sample of the voice (WAV)
  email: string               // the account the avatar is saved on
  source: 'generated' | 'image'
  previewMediaId?: string     // source 'generated': the drawn picture, download it with GET /media/{mediaId}
  look?: {                    // source 'generated': the description you sent
    appearance: string
    outfit?: string
    shot: 'close-up' | 'upper-body' | 'full-body'
    expression?: string
    details?: string
  }
  error?: string              // errors only
  code?: number               // errors only
}

Examples

curl -X POST "https://api.useapi.net/v1/google-vids/avatars" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer …" \
   -d '{
     "name": "Marco",
     "voice": "Holt",
     "appearance": "a middle-aged man with a short grey beard",
     "outfit": "navy blazer over a white shirt",
     "shot": "upper-body"
   }'

const token = "API token";
const apiUrl = "https://api.useapi.net/v1/google-vids";
const headers = { "Content-Type": "application/json", "Authorization": `Bearer ${token}` };

const avatar = await (await fetch(`${apiUrl}/avatars`, {
  method: "POST",
  headers,
  body: JSON.stringify({ name: "Marco", voice: "Holt", appearance: "a middle-aged man with a short grey beard", shot: "upper-body" })
})).json();
console.log("avatar", avatar);

const job = await (await fetch(`${apiUrl}/videos`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    prompt: "@avatar_1 looks into the camera and says: \"Hi, I'm Marco. Welcome to our channel.\"",
    avatar_1: avatar.avatarId,
    duration: 4
  })
})).json();
console.log("video", job.result ?? job.error ?? job);

import requests
token = "API token"
apiUrl = "https://api.useapi.net/v1/google-vids"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
data = {
    "name": "Marco",
    "voice": "Holt",
    "appearance": "a middle-aged man with a short grey beard",
    "shot": "upper-body"
}
avatar = requests.post(f"{apiUrl}/avatars", headers=headers, json=data).json()
print(avatar)