List Characters
June 5, 2026 (November 16, 2026)
Table of contents
List all characters on an account. This endpoint is intentionally fast — it does NOT resolve image preview URLs or voice audio URLs. If you need previews, call GET /characters/ref for the single character you want to display.
The voice block on each character distinguishes three states:
- Live voice — full voice metadata block (
workflowId,mediaId,displayName,baseVoice,dialog,voicePerformance) but noaudioUrl(use the singleton endpoint). - Orphan voice —
{ "mediaId": "...", "deleted": true }. The character was created with a voice that’s since been deleted via DELETE /voices/ref. A character whose voice was attached by its workflow instead reports{ "workflowId": "...", "deleted": true }. - No voice — the
voicefield is omitted entirely.
https://api.useapi.net/v1/google-flow/characters
Request Headers
Authorization: Bearer {API token}
Query Parameters
email— required. Account whose characters to list.
Responses
-
{ "characters": [ { "character": "user:12345-email:6a6f...-character:f470f1b5-...-imgs:2-voice:d990a2f9-...", "entityId": "f470f1b5-...", "displayName": "Carol", "personalityNotes": "A curious traveler with a sharp wit", "imageReferences": [ { "workflowId": "wf-a..." }, { "workflowId": "wf-b..." } ], "voice": { "source": "user", "voice": "user:12345-email:6a6f...-voice:d990a2f9-...-mid:d55b6d59-...", "workflowId": "d990a2f9-...", "mediaId": "d55b6d59-...", "displayName": "Cheerful Narrator", "baseVoice": "Achernar", "dialog": "Hello, this is a test voice.", "voicePerformance": "Cheerful, energetic delivery" }, "thumbnailMediaId": "thumb-a...", "createTime": "2026-06-05T18:14:07.706641Z", "updateTime": "2026-06-05T18:14:16.004078Z" }, { "character": "user:12345-email:6a6f...-character:60831b31-...-imgs:1-voice:umbriel", "entityId": "60831b31-...", "displayName": "Frank", "imageReferences": [{ "workflowId": "wf-d..." }], "voice": { "source": "system", "voice": "Umbriel", "displayName": "Umbriel" }, "thumbnailMediaId": "thumb-d...", "createTime": "2026-06-05T22:42:18.901333Z", "updateTime": "2026-06-05T22:42:24.882179Z" }, { "character": "user:12345-email:6a6f...-character:8a4b0541-...-imgs:1", "entityId": "8a4b0541-...", "displayName": "Eve", "imageReferences": [{ "workflowId": "wf-c..." }], "voice": { "mediaId": "5b1c0e7a-...", "deleted": true }, "thumbnailMediaId": "thumb-c...", "createTime": "2026-06-05T18:15:37.734955Z", "updateTime": "2026-06-05T18:15:41.167097Z" } ] }If no characters have been created yet,
charactersis just an empty array — no error. -
{ "error": "Parameter email is required", "code": 400 } -
{ "error": "Google Flow account [email protected] not found", "code": 404 }
Model
Every character of the account, each with its reference-id, name, images and voice.
The list of characters, field by field
{
characters: Array<{ // every character of the account
character: string // reference-id used in character_1..10 on POST /videos, character_1..7 on POST /images
entityId: string // Google's id of the character
displayName: string // the character's name ('Untitled Character' when it has none)
personalityNotes?: string // notes about the character, when set
imageReferences: Array<{ // the character's image slots
workflowId?: string // the image's Google Flow workflow; absent on an empty slot
}>
thumbnailMediaId?: string // media id of the character's thumbnail image
createTime: string // ISO 8601 timestamp (empty when Google gives none)
updateTime: string // ISO 8601 timestamp of the last change (empty when Google gives none)
voice?: // omitted if no voice was ever attached. One of three shapes: a custom voice (source user),
// a system voice preset (source system), or a custom voice that was attached and then
// deleted (deleted: true, no source)
| {
source: 'user' // a custom voice (POST /voices)
voice: string // dual-id reference-id
workflowId: string // Google Flow workflow of the voice
mediaId: string // media id of the voice's audio
displayName?: string // the voice's name
baseVoice?: string // the system preset the voice is built on
dialog?: string // the text the voice speaks in its sample
voicePerformance?: string // the delivery style
}
| {
source: 'system' // a system voice preset
voice: string // Title-case preset name (e.g. 'Umbriel')
displayName: string // same as `voice`
}
| {
mediaId?: string // the deleted voice's media id, when the voice was attached by media id
workflowId?: string // the deleted voice's workflow id, when the voice was attached by workflow
deleted: true // always true: the voice was attached, then deleted
}
}>
}
Examples
-
curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/[email protected]" -
const r = await fetch( `https://api.useapi.net/v1/google-flow/characters?email=${email}`, { headers: { 'Authorization': `Bearer ${token}` } } ) const { characters } = await r.json() console.log(characters.map(c => c.displayName)) -
import requests r = requests.get( 'https://api.useapi.net/v1/google-flow/characters', headers={'Authorization': f'Bearer {token}'}, params={'email': '[email protected]'}, ) for c in r.json()['characters']: print(c['displayName'], '→', c['character'])