Create an avatar

October 7, 2026 (November 16, 2026)

Table of contents

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

An avatar is a picture of a person plus a fixed voice. It can:

  • Read a script as a talking-head video of up to 30 seconds, with POST /videos/avatar.
  • Act in a scene: 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 starts from exactly one of three inputs:

Start Body parameter What Google does
A description appearance, plus optional outfit, shot, expression and details Draws the person.
A photo or an image image: the assetId of a person’s photo uploaded with POST /assets, or the mediaId of an image made with POST /images A photo is reframed into a 16:9 avatar picture: one person, centred, facing the camera with a smile, keeping their face, clothes and accessories. A photo with no visible face comes back unchanged. An image mediaId is used as is.
Another avatar avatar: an avatarId from GET /avatars or an earlier POST /avatars Uses that avatar’s picture, for example to give the same person another name or voice.

Two optional changes then apply to the picture, whatever it started from:

  • refine is a change in words: other clothes, a new background, a hairstyle, glasses.
  • logo is an image placed on the clothes like a small pin or patch, on the left chest unless you say where in refine.

Without refine or logo, an image mediaId or an avatar start keeps its picture unchanged.

Every call makes a new avatar. The avatar you started from stays as it was. All inputs of one request (image, avatar, logo) must live on the same account, and the new avatar is saved there.

Google checks every picture. It refuses photos of prominent people and of minors, and content against its terms, with 422.

The voice is one of the 30 voices listed by GET /voices, named by its Vids name (Holt) or its Google voice id (Charon). To hear a voice with your own words first, use POST /speech.

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

  • Each picture Google makes uses 1 image of the account’s monthly Vids images: a drawing from a description, a photo reframed, and a change with refine and/or logo (both together are one change). So a start plus a change uses 2 images. An avatar copied unchanged from avatar, or an image mediaId used as is, makes no new picture and uses nothing.
  • On an account with no image allowance, such as a free Google account, avatar pictures still work and cost nothing. Name that account with email. Its avatars can talk with POST /videos/avatar when its plan has AI avatar videos, and their pictures (previewMediaId) download like any image.
  • 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. A talking avatar video uses the account’s AI avatar videos, see POST /videos/avatar.

Creating an avatar takes about 15 to 20 seconds from a description, about 10 to 15 seconds from a photo, and a few seconds from an image mediaId or an avatar used as is. A refine or a logo adds about 15 to 25 seconds, so a start plus a change takes about 30 to 45 seconds. The call 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
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 a photo uploaded with POST /assets, with a change and a logo:

{
  "name": "Dana",
  "voice": "Kaci",
  "image": "user:[email protected]:AYGXpjhQ2Lw8…",
  "refine": "a dark green hoodie, a plain light grey studio background",
  "logo": "user:[email protected]:AYGXpjgN7cRt…"
}

From an existing avatar, with a new voice and glasses:

{
  "name": "Marco with glasses",
  "voice": "Zeno",
  "avatar": "user:[email protected]:eyJnIjoiaDMy…",
  "refine": "round tortoiseshell glasses"
}
  • name is required, the new 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.
  • appearance, image and avatar are the start of the picture. Send exactly one of them.
  • appearance is the person to draw, for example their age, hair and features.
    Length: 1 to 500 characters.
  • outfit, shot, expression and details describe the drawn picture further. They apply only with appearance and are ignored otherwise: to change a photo or an avatar, use refine.
    • outfit is what the person wears. Maximum length: 300 characters.
    • shot is the framing. Supported values: close-up (head and shoulders), upper-body (from the waist up), full-body (head to feet). Default: close-up.
    • expression is the facial expression. When omitted, Google is asked for a smile with teeth. Maximum length: 200 characters.
    • details is anything else about the picture. Maximum length: 1000 characters.
  • image is the assetId of a person’s photo uploaded with POST /assets (JPEG, PNG or WebP), or the mediaId of an image made with POST /images. The previewMediaId returned by POST /avatars is an image mediaId and works here too. The previewMediaId listed by GET /avatars does not: pass that avatar’s avatarId as avatar instead.
  • avatar is an avatarId from GET /avatars or POST /avatars, to start from its picture.
  • refine is optional, a change to the picture in words, for example clothes, background, hairstyle or glasses.
    Length: 1 to 1000 characters.
  • logo is optional, an image to place on the clothes: an assetId from POST /assets or an image mediaId from POST /images. Say where it goes in refine, for example "the logo on the cap".
  • email is optional, the account to save the avatar on. With image, avatar or logo it defaults to the account they live on and must match it. With appearance alone, a healthy account with an image allowance is picked when it is omitted, preferring one whose images are not used up this month. Name any other account, a free one included, with email.
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 a photo, with refine and logo. previewMediaId is the new picture:

    {
      "avatarId": "user:[email protected]:eyJnIjoiaDU4…",
      "name": "Dana",
      "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": "photo",
      "previewMediaId": "user:[email protected]:eyJ1IjoiaHR0…",
      "refine": "a dark green hoodie, a plain light grey studio background",
      "logo": "user:[email protected]:AYGXpjgN7cRt…"
    }
    

    From an existing avatar with no change (a copy with another name or voice), there is no new picture, so no previewMediaId:

    {
      "avatarId": "user:[email protected]:eyJnIjoiaDMw…",
      "name": "Marco, firm voice",
      "voice": "Zeno",
      "voiceId": "Alnilam",
      "voiceStyle": "Firm",
      "voicePreview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Alnilam.wav",
      "email": "[email protected]",
      "source": "avatar"
    }
    
  • 400 Bad Request — an unknown voice, none or more than one of appearance, image and avatar, inputs from different accounts, an image Google no longer serves, or an invalid parameter.

    {
      "error": "Unknown voice Bob. GET /voices lists them (name or voice id)",
      "code": 400
    }
    
    {
      "error": "Give one of appearance (a description of the person to draw), image (a photo uploaded with POST /assets, or an image mediaId from POST /images) or avatar (an avatarId to start from)",
      "code": 400
    }
    
    {
      "error": "Give only one of appearance, image and avatar",
      "code": 400
    }
    
    {
      "error": "user:[email protected]:AYGXpjgN7cRt… lives on [email protected], not [email protected]: every input of one avatar must come from the same account",
      "code": 400
    }
    
    {
      "error": "logo: Google answered HTTP 404 for this image (it may have expired). Generate it again or upload it with POST /assets",
      "code": 400
    }
    
    {
      "error": "Parameter name is required",
      "code": 400
    }
    
  • 401 Unauthorized

    Invalid API token.

    {
      "error": "useapi.net ⁝ Unauthorized",
      "code": 401
    }
    
  • 403 Forbidden — an image, avatar or logo 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 an input id is not connected.

    {
      "error": "Account [email protected] is not configured",
      "code": 404
    }
    
  • 422 Unprocessable Content — Google refused the picture: a prominent person, a minor, or content against its terms. Nothing is saved. Try another photo or other words.

    {
      "error": "Google refused the image: \"The image you provided contains a prominent person, which isn't allowed by our content policies. Try another image.\"",
      "code": 422
    }
    
    {
      "error": "Google refused the image: \"The image you provided contains a minor, which isn't allowed by our content policies. Try another image.\"",
      "code": 422
    }
    
    {
      "error": "Google refused this request (\"That request looks like it goes against our terms. Try asking something else.\")",
      "code": 422
    }
    
  • 429 Too Many Requests — Google’s own short-term limit on avatar pictures for this account. Retry later, or use another account.

    {
      "error": "Google says this account has hit its limit for generating avatar pictures in Vids. Retry later or use another account",
      "code": 429
    }
    
  • 502 Bad Gateway — Google did not save the avatar, or answered without a picture. Retry.

    {
      "error": "Google did not keep the avatar in the Vids document, please retry",
      "code": 502
    }
    
  • 503 Service Unavailable — Google’s avatar picture service is failing for now (Google’s own editor shows “Something went wrong. Try again.”). Nothing was charged. Retry in a few minutes.

    {
      "error": "Google's avatar picture service failed (\"Something went wrong. Try again.\", INTERNAL_SERVER_ERROR). Nothing was charged. Retry in a few minutes",
      "code": 503
    }
    
  • 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

The new avatar’s avatarId, name, voice and account, the previewMediaId of its new picture, and what it was made from.

The new avatar, field by field
{ // TypeScript, all fields are optional
  avatarId: string            // user:<id>-<email>-avatar:…, for POST /videos/avatar, avatar_1..avatar_3 of POST /videos, or avatar here
  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' | 'photo' | 'image' | 'avatar'   // appearance, an uploaded photo, an image mediaId, an avatarId
  previewMediaId?: string     // the new picture (1280x720), download it with GET /media/{mediaId}. Absent when the picture was reused unchanged
  look?: {                    // with appearance: the description you sent
    appearance: string
    outfit?: string
    shot: 'close-up' | 'upper-body' | 'full-body'
    expression?: string
    details?: string
  }
  refine?: string             // the change you sent
  logo?: string               // the logo id you sent
  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"
       }'
    
    # From a photo: upload it to the account first, then pass its assetId as image
    curl -X POST "https://api.useapi.net/v1/google-vids/assets?email=user%40example.com" \
       -H "Content-Type: image/jpeg" \
       -H "Authorization: Bearer …" \
       --data-binary @dana.jpg
    
    curl -X POST "https://api.useapi.net/v1/google-vids/avatars" \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer …" \
       -d '{
         "name": "Dana",
         "voice": "Kaci",
         "image": "user:[email protected]:AYGXpjhQ2Lw8…",
         "refine": "a dark green hoodie"
       }'
    
  • 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/avatar`, {
      method: "POST",
      headers,
      body: JSON.stringify({
        avatar: avatar.avatarId,
        script: "Hi, I'm Marco. Welcome to our channel."
      })
    })).json();
    console.log("talking 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)
    
Try It