Create an avatar
October 7, 2026 (November 16, 2026)
Table of contents
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
avatarIdasavatar_1..avatar_3to 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:
refineis a change in words: other clothes, a new background, a hairstyle, glasses.logois an image placed on the clothes like a small pin or patch, on the left chest unless you say where inrefine.
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
refineand/orlogo(both together are one change). So a start plus a change uses 2 images. An avatar copied unchanged fromavatar, or an imagemediaIdused 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
API tokenis 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 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"
}
nameis required, the new avatar’s name. It is a label only and plays no part in a video prompt.
Length:1to40characters.voiceis required, a voicenameorvoiceid from GET /voices, case-insensitive.appearance,imageandavatarare the start of the picture. Send exactly one of them.appearanceis the person to draw, for example their age, hair and features.
Length:1to500characters.outfit,shot,expressionanddetailsdescribe the drawn picture further. They apply only withappearanceand are ignored otherwise: to change a photo or an avatar, userefine.outfitis what the person wears. Maximum length:300characters.shotis the framing. Supported values:close-up(head and shoulders),upper-body(from the waist up),full-body(head to feet). Default:close-up.expressionis the facial expression. When omitted, Google is asked for a smile with teeth. Maximum length:200characters.detailsis anything else about the picture. Maximum length:1000characters.
imageis theassetIdof a person’s photo uploaded with POST /assets (JPEG, PNG or WebP), or themediaIdof an image made with POST /images. ThepreviewMediaIdreturned by POST /avatars is an imagemediaIdand works here too. ThepreviewMediaIdlisted by GET /avatars does not: pass that avatar’savatarIdasavatarinstead.avataris anavatarIdfrom GET /avatars or POST /avatars, to start from its picture.refineis optional, a change to the picture in words, for example clothes, background, hairstyle or glasses.
Length:1to1000characters.logois optional, an image to place on the clothes: anassetIdfrom POST /assets or an imagemediaIdfrom POST /images. Say where it goes inrefine, for example"the logo on the cap".emailis optional, the account to save the avatar on. Withimage,avatarorlogoit defaults to the account they live on and must match it. Withappearancealone, 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, withemail.
Responses
-
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
refineandlogo.previewMediaIdis 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,imageandavatar, 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 } -
Invalid API token.
{ "error": "useapi.net ⁝ Unauthorized", "code": 401 } -
403 Forbidden — an
image,avatarorlogoid 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
emailor 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)