List Characters

June 5, 2026 (November 16, 2026)

Table of contents

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

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 no audioUrl (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 voice field 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

  • 200 OK

    {
      "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, characters is just an empty array — no error.

  • 400 Bad Request

    {
      "error": "Parameter email is required",
      "code": 400
    }
    
  • 404 Not Found

    {
      "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'])
    

Try It