Create Character
June 5, 2026 (November 16, 2026)
Table of contents
Create a character — a reusable Google Flow entity that bundles 1–2 reference images plus an optional attached voice. Characters can be referenced from POST /videos and POST /images via character_1..7 to keep the same identity across generations.
What can use a character?
Per Google Flow’s model rules:
| Model | Character support | Image budget | Voice budget |
|---|---|---|---|
Veo 3.1 Qualityveo-3.1-quality | n/a | n/a | |
Veo 3.1 Fastveo-3.1-fast | 3 total (character images + raw image refs) | 1 voice | |
Veo 3.1 Liteveo-3.1-lite | 3 total (character images + raw image refs) | 1 voice | |
Veo 3.1 Lite Lower Priorityveo-3.1-lite-low-priority | 3 total (character images + raw image refs) | 1 voice | |
Omni 1.2 Flashomni-flash-1.2 | 10 total (character images + raw image refs), 3 on extend | 5 voices, 3 on extend | |
Omni 1.1 Flashomni-flash | 7 total (character images + raw image refs) | 5 voices |
Example: character_1 with 2 images + character_2 with 2 images + 3 referenceImage_* = 7 effective image refs — accepted on omni-flash, rejected on veo-3.1-fast (cap 3).
https://api.useapi.net/v1/google-flow/characters
Request Headers
Authorization: Bearer {API token}
Content-Type: application/json
Request Body
{
"displayName": "Carol",
"personalityNotes": "A curious traveler with a sharp wit",
"imageReference_1": "user:12345-email:6a6f...-image:abc123...",
"imageReference_2": "user:12345-email:6a6f...-image:def456...",
"voice": "user:12345-email:6a6f...-voice:d990a2f9-...-mid:d55b6d59-..."
}
displayNameis required, user-facing name. Range: 1-200 chars.imageReference_1is required, an imagemediaGenerationId— either uploaded via POST /assets/emailor generated via POST /images. At least one image is required.imageReference_2is optional, second image reference (max two per character).personalityNotesis optional, short description shown alongside the character. Range: 0-2000 chars.voiceis optional. Either a system voice preset name (e.g.Umbriel, case-insensitive — one of the 30 presets) or a user voice from POST /voices (use thevoicefield from its response).
Responses
-
{ "entityId": "f470f1b5-...", "character": "user:12345-email:6a6f...-character:f470f1b5-...-imgs:2-voice:d990a2f9-...", "displayName": "Carol", "personalityNotes": "A curious traveler with a sharp wit", "imageReferences": [ { "mediaId": "abc123..." }, { "mediaId": "def456..." } ], "voice": "user:12345-email:6a6f...-voice:d990a2f9-...-mid:d55b6d59-..." }Use the
characterfield as the value forcharacter_1..character_10on POST /videos (slots_8.._10onomni-flash-1.2only) andcharacter_1..character_7on POST /images. -
Validation error.
{ "error": "Parameter displayName is required", "code": 400 } -
401 Unauthorized
{ "error": "useapi.net ⁝ Unauthorized", "code": 401 } -
An image or voice reference belongs to another useapi.net user, so no character was created. Use images and voices made or uploaded with your own API token.
{ "error": "Unauthorized access to user:99999 detected in image reference user:99999-email:6a6f...-image:abc123...", "code": 403 }When the voice belongs to another user:
{ "error": "Unauthorized access to user:99999 detected in voice reference", "code": 403 } -
404 Not Found
{ "error": "Google Flow account [email protected] not found", "code": 404 }
Model
The new character, with the reference-id to send as character_1 and up, and the images and voice you attached.
The new character, field by field
{
entityId: string // Google's id of the character
character: string // reference-id used in character_1..10 on POST /videos, character_1..7 on POST /images
displayName: string // the name you sent
personalityNotes?: string // the notes you sent; omitted when none
imageReferences: Array<{ // the images you attached (imageReference_1, imageReference_2)
mediaId: string // the image reference-id you sent
}>
voice?: string // echoed when a voice was attached: the voice's reference-id for a custom voice
// (user:N-email:...-voice:...-mid:...), or the Title-case preset name for a system
// voice (e.g. Umbriel)
}
Examples
-
curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "displayName": "Carol", "imageReference_1": "user:12345-email:6a6f...-image:abc123...", "imageReference_2": "user:12345-email:6a6f...-image:def456..." }' \ "https://api.useapi.net/v1/google-flow/characters" -
const r = await fetch('https://api.useapi.net/v1/google-flow/characters', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ displayName: 'Carol', imageReference_1: imgA, imageReference_2: imgB, }) }) const result = await r.json() console.log('character ref:', result.character) -
import requests r = requests.post( 'https://api.useapi.net/v1/google-flow/characters', headers={'Authorization': f'Bearer {token}'}, json={ 'displayName': 'Carol', 'imageReference_1': img_a, 'imageReference_2': img_b, }, ) print('character ref:', r.json()['character'])