Skip to main content
Glama

generate_video_with_reference

Generate a video using up to 7 reference images (r2v — e.g. a consistent character/subject across the video). reference_images_base64: raw base64-encoded image bytes (no data: URI prefix), up to 7 with Omni Flash keys (abra_r2v_*, the default), up to 3 with Veo r2v keys (veo_3_1_r2v_*). Mutually exclusive with start-image (i2v) generation.

THIS IS THE RECOMMENDED WAY to get content that actually looks like a real person
from a real photo — confirmed live 2026-07-11: r2v conditions generation on the
reference photo's actual pixels and reliably preserves the real face, unlike the
character system's `generate_character_image`/`generate_character_turnaround`
(those condition on a TEXT description + a loosely-attached reference and were
confirmed to drift to an unrelated-looking person). For a still IMAGE rather than
video, use this and read `first_frame_path` (or `last_frame_path`) off the result once done (via
check_job) — same-day testing found no reliable image-only equivalent: a plain
generate_image call with image_inputs pointed at an external photo was confirmed
to silently ignore the reference entirely.

project_id: put the clip into a project made with create_project instead of the
account's default one.

entity_id: optional — the entityId of a character you created and voiced with
set_character_voice. Only meaningful together with video_model_key="veo_3_1_r2v_lite"
(the one r2v model that generates speech natively); for abra_r2v_* models passing
entity_id has no effect (and was known to 500 historically). When set with the right
model, Flow attaches the character's audioReferences and lip-syncs the generated
speech in the assigned TTS voice. The job runs on the character's own Google account
(that's where the entity and its audioReferences live) — so an account different
from your other calls is normal here, no action needed.

voice / voice_style / voice_text: optional one-shot narration without creating a
character. Pass a voice name from list_voices() (e.g. "Algieba") and either a
voice_text or embed the spoken line in the prompt between quotes. Mutually
exclusive with entity_id — a character already carries its own voice. Only works
with speech-capable r2v models (veo_3_1_r2v_lite).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "prompt": "<prompt>",
      "reference_images_base64": "<reference_images_base64>"
    },
    "name": "generate_video_with_reference"
  }
}

Input Schema

NameRequiredDescriptionDefault
seedNo
voiceNo
aspectNoVIDEO_ASPECT_RATIO_LANDSCAPE
promptYes
entity_idNo
project_idNo
voice_textNo
voice_styleNo
include_previewNo
video_model_keyNoabra_r2v_4s
reference_images_base64Yes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / video_model_key / enum
      Previous value: -[
      -  "abra_r2v_4s",
      -  "abra_r2v_6s",
      -  "abra_r2v_8s",
      -  "abra_r2v_10s",
      -  "abra_r2v_4s_360p",
      -  "abra_r2v_6s_360p",
      -  "abra_r2v_8s_360p",
      -  "abra_r2v_10s_360p",
      -  "macaron_cookie_r2v_3s",
      -  "macaron_cookie_r2v_4s",
      -  "macaron_cookie_r2v_5s",
      -  "macaron_cookie_r2v_6s",
      -  "macaron_cookie_r2v_7s",
      -  "macaron_cookie_r2v_8s",
      -  "macaron_cookie_r2v_9s",
      -  "macaron_cookie_r2v_10s",
      -  "macaron_cookie_r2v_15s",
      -  "macaron_cookie_r2v_3s_360p",
      -  "macaron_cookie_r2v_4s_360p",
      -  "macaron_cookie_r2v_5s_360p",
      -  "macaron_cookie_r2v_6s_360p",
      -  "macaron_cookie_r2v_7s_360p",
      -  "macaron_cookie_r2v_8s_360p",
      -  "macaron_cookie_r2v_9s_360p",
      -  "macaron_cookie_r2v_10s_360p",
      -  "macaron_cookie_r2v_15s_360p",
      -  "veo_3_1_r2v_lite"
      -]New value: +[
      +  "abra_r2v_4s",
      +  "abra_r2v_6s",
      +  "abra_r2v_8s",
      +  "abra_r2v_10s",
      +  "abra_r2v_4s_360p",
      +  "abra_r2v_6s_360p",
      +  "abra_r2v_8s_360p",
      +  "abra_r2v_10s_360p",
      +  "macaron_cookie_r2v_3s",
      +  "macaron_cookie_r2v_4s",
      +  "macaron_cookie_r2v_5s",
      +  "macaron_cookie_r2v_6s",
      +  "macaron_cookie_r2v_7s",
      +  "macaron_cookie_r2v_8s",
      +  "macaron_cookie_r2v_9s",
      +  "macaron_cookie_r2v_10s",
      +  "macaron_cookie_r2v_11s",
      +  "macaron_cookie_r2v_12s",
      +  "macaron_cookie_r2v_13s",
      +  "macaron_cookie_r2v_14s",
      +  "macaron_cookie_r2v_15s",
      +  "macaron_cookie_r2v_3s_360p",
      +  "macaron_cookie_r2v_4s_360p",
      +  "macaron_cookie_r2v_5s_360p",
      +  "macaron_cookie_r2v_6s_360p",
      +  "macaron_cookie_r2v_7s_360p",
      +  "macaron_cookie_r2v_8s_360p",
      +  "macaron_cookie_r2v_9s_360p",
      +  "macaron_cookie_r2v_10s_360p",
      +  "macaron_cookie_r2v_11s_360p",
      +  "macaron_cookie_r2v_12s_360p",
      +  "macaron_cookie_r2v_13s_360p",
      +  "macaron_cookie_r2v_14s_360p",
      +  "macaron_cookie_r2v_15s_360p",
      +  "veo_3_1_r2v_lite"
      +]
  2. Changed1 schema field changed
    • changedInput schema / properties / video_model_key / enum
      Previous value: -[
      -  "abra_r2v_4s",
      -  "abra_r2v_6s",
      -  "abra_r2v_8s",
      -  "abra_r2v_10s",
      -  "abra_r2v_4s_360p",
      -  "abra_r2v_6s_360p",
      -  "abra_r2v_8s_360p",
      -  "abra_r2v_10s_360p",
      -  "veo_3_1_r2v_lite"
      -]New value: +[
      +  "abra_r2v_4s",
      +  "abra_r2v_6s",
      +  "abra_r2v_8s",
      +  "abra_r2v_10s",
      +  "abra_r2v_4s_360p",
      +  "abra_r2v_6s_360p",
      +  "abra_r2v_8s_360p",
      +  "abra_r2v_10s_360p",
      +  "macaron_cookie_r2v_3s",
      +  "macaron_cookie_r2v_4s",
      +  "macaron_cookie_r2v_5s",
      +  "macaron_cookie_r2v_6s",
      +  "macaron_cookie_r2v_7s",
      +  "macaron_cookie_r2v_8s",
      +  "macaron_cookie_r2v_9s",
      +  "macaron_cookie_r2v_10s",
      +  "macaron_cookie_r2v_15s",
      +  "macaron_cookie_r2v_3s_360p",
      +  "macaron_cookie_r2v_4s_360p",
      +  "macaron_cookie_r2v_5s_360p",
      +  "macaron_cookie_r2v_6s_360p",
      +  "macaron_cookie_r2v_7s_360p",
      +  "macaron_cookie_r2v_8s_360p",
      +  "macaron_cookie_r2v_9s_360p",
      +  "macaron_cookie_r2v_10s_360p",
      +  "macaron_cookie_r2v_15s_360p",
      +  "veo_3_1_r2v_lite"
      +]
  3. Changed1 schema field changed
    • addedInput schema / properties / seed
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Seed"
      +}
  4. Changed3 schema fields changed
    • addedInput schema / properties / voice
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Voice"
      +}
    • addedInput schema / properties / voice_style
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Voice Style"
      +}
    • addedInput schema / properties / voice_text
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Voice Text"
      +}
  5. Changed1 schema field changed
    • addedInput schema / properties / entity_id
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Entity Id"
      +}
  6. First observed

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations (readOnly=false, openWorld=true, destructive=false) by disclosing model-dependent limits (7 refs on abra_r2v_*, 3 on veo_3_1_r2v_*), that entity_id only functions with veo_3_1_r2v_lite and historically 500s on abra_r2v_*, and that the job runs on the character's own account. The only weakness is that safety/rate/return behavior is not summarized, and some claims are framed as dated test anecdotes rather than stable behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The opening sentence is front-loaded and effective, and the per-parameter paragraphs are organized. But it drifts into verbose provenance asides ('confirmed live 2026-07-11', 'no action needed', claims about unrelated tools' failures) that add length without adding call-time guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter, non-idempotent, open-world generation tool with no output schema, the description supplies the model-selection rules, mutual exclusions, and a workaround for retrieving still frames via check_job. It is nearly complete for correct invocation, with the main remaining hole being the undocumented seed/aspect/include_preview parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage the description must carry the load, and it does for the important parameters: reference_images_base64 format (raw base64, no data: prefix, count limits), project_id, entity_id, voice/voice_style/voice_text, and model family constraints via video_model_key. However seed, aspect, and include_preview receive no explanation at all, leaving a meaningful gap against an 11-parameter schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Generate a video using up to 7 reference images') and immediately scopes it with the r2v concept and the 'consistent character/subject' use case. It explicitly distinguishes itself from start-image (i2v) generation and from the generate_character_image/generate_character_turnaround siblings, so an agent can differentiate without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit routing: use this for content that must look like a real person, avoid generate_character_image/turnaround (drift, text-conditioned), use generate_image-free path for stills by reading first_frame_path. It also states mutual exclusivity with i2v start-image and between entity_id and voice/voice_style/voice_text, giving both when-to-use and when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.