List Characters

June 5, 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 — { "workflowId": "...", "deleted": true }. The character was created with a voice that’s since been deleted via DELETE /voices/ref.
  • 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": { "workflowId": "ccd7615f-...", "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" }

  • 404 Not Found

    { "error": "Google Flow account [email protected] not found" }

Model 

{
  characters: Array<{
    character: string            // reference-id used in character_1..7 on POST /videos & POST /images
    entityId: string
    displayName: string
    personalityNotes?: string
    imageReferences: Array<{ workflowId?: string }>
    thumbnailMediaId?: string
    createTime?: string          // ISO 8601 timestamp
    updateTime?: string
    voice?:                      // omitted if no voice was ever attached
      | {                        // live user voice
          source: 'user'
          voice: string          // dual-id reference-id
          workflowId: string
          mediaId: string
          displayName?: string
          baseVoice?: string
          dialog?: string
          voicePerformance?: string
        }
      | {                        // system voice preset
          source: 'system'
          voice: string          // Title-case preset name (e.g. 'Umbriel')
          displayName: string    // same as `voice`
        }
      | {                        // orphan user voice — attached then deleted
          workflowId: string
          deleted: true
        }
  }>
}

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