Create Character

June 5, 2026

Table of contents

  1. What can use a character?
  2. Request Headers
  3. Request Body
  4. Responses
  5. Model
  6. Examples
  7. Try It

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 Quality
veo-3.1-quality		 ✗ n/a n/a
Veo 3.1 Fast
veo-3.1-fast		 ✓ (Ingredients mode, 8 s duration only) 3 total (character images + raw image refs) 1 voice
Veo 3.1 Lite
veo-3.1-lite		 ✓ (Ingredients mode, 8 s duration only) 3 total (character images + raw image refs) 1 voice
Veo 3.1 Lite Lower Priority
veo-3.1-lite-low-priority		 ✓ (Ingredients mode, 8 s duration only) 3 total (character images + raw image refs) 1 voice
Gemini Omni Flash
omni-flash		 ✓ (Ingredients mode, all durations) 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-..."
}
  • displayName is required, user-facing name. Range: 1-200 chars.
  • imageReference_1 is required, an image mediaGenerationId — either uploaded via POST /assets/email or generated via POST /images. At least one image is required.
  • imageReference_2 is optional, second image reference (max two per character).
  • personalityNotes is optional, short description shown alongside the character. Range: 0-2000 chars.
  • voice is 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 the voice field from its response).

Responses

  • 200 OK

    {
  "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 character field as the value for character_1..character_7 on POST /videos and POST /images.

  • 400 Bad Request

    Validation error.

    { "error": "Parameter displayName is required" }

  • 401 Unauthorized

    { "error": "Unauthorized" }

  • 404 Not Found

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

Model 

{
  entityId: string
  character: string              // reference-id used in character_1..7 on POST /videos & POST /images
  displayName: string
  personalityNotes?: string
  imageReferences: Array<{ mediaId: string }>
  voice?: string                 // echoed when a voice was attached:
                                 //   user voice → the encoded reference-id (`user:N-email:...-voice:...-mid:...`)
                                 //   system voice → the Title-case preset name (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'])

Try It