Get Single Character (with previewUrls + audioUrl)

June 5, 2026 (November 16, 2026)

Table of contents

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

Resolve a single character by reference-id with all media URLs included:

  • imageReferences[].previewUrl — signed image preview for each attached image
  • thumbnailUrl — signed thumbnail of the auto-composited character avatar
  • voice.audioUrl — signed playback URL when a live voice is attached

All URLs are valid for ~6 hours.

https://api.useapi.net/v1/google-flow/characters/ref

Path Parameters

Request Headers

Authorization: Bearer {API token}

Responses

  • 200 OK

    {
      "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...",
          "mediaId": "media-a...",
          "previewUrl": "https://flow-content.google/image/media-a...?Expires=...&Signature=..."
        },
        {
          "workflowId": "wf-b...",
          "mediaId": "media-b...",
          "previewUrl": "https://flow-content.google/image/media-b...?Expires=...&Signature=..."
        }
      ],
      "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",
        "audioUrl": "https://flow-content.google/audio/d55b6d59-...?Expires=...&Signature=..."
      },
      "thumbnailMediaId": "thumb-a...",
      "thumbnailUrl": "https://flow-content.google/image/thumb-a...?Expires=...&Signature=...",
      "createTime": "2026-06-05T18:14:07.706641Z",
      "updateTime": "2026-06-05T18:14:16.004078Z"
    }
    

    For a system voice attached at create time (e.g. voice: "Umbriel" on POST /characters), the voice block reports { "source": "system", "voice": "Umbriel", "displayName": "Umbriel" } — no workflowId, no audioUrl. Preview the audio sample from https://www.gstatic.com/aitestkitchen/voices/samples/{Name}.wav.

    For an orphan voice (the attached user voice has been deleted), the voice block degrades to { "workflowId": "...", "mediaId": "...", "deleted": true } — no audioUrl. workflowId comes from the -voice: part of the reference you sent, so a reference without it leaves workflowId out. A voice attached by its workflow (not its media) reports { "workflowId": "...", "deleted": true }. The image URLs are unaffected.

  • 400 Bad Request

    {
      "error": "Parameter character has incorrect format",
      "code": 400
    }
    
  • 403 Forbidden

    {
      "error": "Unauthorized access to user:12345 detected in character reference",
      "code": 403
    }
    
  • 404 Not Found

    {
      "error": "Character not found: f470f1b5-...",
      "code": 404
    }
    

Model

The character with its reference-id, its images with signed preview links, its thumbnail and its voice.

The character, field by field
{
  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
    mediaId?: string             // populated when the image media is resolvable
    previewUrl?: string          // signed image preview URL (~6h TTL)
  }>
  thumbnailMediaId?: string      // media id of the character's thumbnail image
  thumbnailUrl?: string          // signed thumbnail URL (~6h TTL)
  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, no workflow or media), 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
        audioUrl?: string        // signed playback URL (~6h TTL)
      }
    | {
        source: 'system'         // a system voice preset
        voice: string            // canonical Title-case preset name (e.g. 'Umbriel')
        displayName: string      // same as `voice`
      }
    | {
        workflowId?: string      // the deleted voice's workflow id, when known
        mediaId?: string         // the deleted voice's media id, when the voice was attached by media id
        deleted: true            // always true: the voice was attached, then deleted
      }
}

Examples

  • REF="user:12345-email:6a6f...-character:f470f1b5-...-imgs:2"
    REF_ENC=$(printf '%s' "$REF" | jq -sRr @uri)
    curl -H "Authorization: Bearer YOUR_API_TOKEN" \
         "https://api.useapi.net/v1/google-flow/characters/$REF_ENC"
    
  • const ref = 'user:12345-email:6a6f...-character:f470f1b5-...-imgs:2'
    const r = await fetch(
      `https://api.useapi.net/v1/google-flow/characters/${encodeURIComponent(ref)}`,
      { headers: { 'Authorization': `Bearer ${token}` } }
    )
    const c = await r.json()
    c.imageReferences.forEach((img, i) => console.log(`img ${i}:`, img.previewUrl))
    console.log('voice audio:', c.voice?.audioUrl)
    
  • import requests, urllib.parse
    ref = 'user:12345-email:6a6f...-character:f470f1b5-...-imgs:2'
    r = requests.get(
        f'https://api.useapi.net/v1/google-flow/characters/{urllib.parse.quote(ref, safe="")}',
        headers={'Authorization': f'Bearer {token}'},
    )
    c = r.json()
    for i, img in enumerate(c['imageReferences']):
        print(f"img {i}:", img.get('previewUrl'))
    print('voice audio:', (c.get('voice') or {}).get('audioUrl'))
    

Try It