openFlow

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).

Input Schema

Name	Required	Default
`seed`	No
`voice`	No
`aspect`	No	VIDEO_ASPECT_RATIO_LANDSCAPE
`prompt`	Yes
`entity_id`	No
`project_id`	No
`voice_text`	No
`voice_style`	No
`include_preview`	No
`video_model_key`	No	abra_r2v_4s
`reference_images_base64`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 15, 2026

addedInput schema / properties / seed

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Seed"
+}

Changed3 schema fields changedOct 9, 2026

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"
+}

Changed1 schema field changedOct 9, 2026

addedInput schema / properties / entity_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Entity Id"
+}

First observedSep 1, 2026

TDQS

A4.4/5.0

Behavior5/5

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

With annotations only covering the classic hints, the description adds rich behavioral context beyond them: the entity_id/veo_3_1_r2v_lite binding, the historical 500 error, the fact that the job runs on the character's own Google account, mutual exclusivity rules, and model-capability constraints. This is well above what annotations provide.

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?

Purpose is front-loaded, but the description is bloated with internal testing anecdotes ('confirmed live 2026-07-11', 'same-day testing found') and tangential parentheticals that dilute the signal. Several sentences do not directly aid tool selection or invocation.

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 a complex 11-parameter generation tool with no output schema, it covers behavior, edge cases, and how to retrieve results (via check_job / first_frame_path). Only the un-explained parameters (seed, aspect, include_preview) leave minor gaps.

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

Parameters3/5

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

Schema coverage is 0%, so the description must compensate. It documents the trickiest parameters well (reference_images_base64 format/limits, entity_id, voice/voice_style/voice_text, project_id), but leaves seed, aspect, prompt, and include_preview undescribed. Solid but incomplete for an 11-parameter tool.

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?

States a specific verb+resource ('Generate a video using up to 7 reference images') and immediately names the technique (r2v) and its purpose (consistent character/subject). It actively distinguishes itself from siblings like generate_image, generate_character_image, and generate_character_turnaround.

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?

Explicitly declares itself 'THE RECOMMENDED WAY' for a specific goal (real person from a real photo) and contrasts it against named alternatives that were 'confirmed to drift'. It also states mutual exclusivity with start-image (i2v) generation and notes the image-only fallback via first_frame_path.

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

All openFlow tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

generate_video_with_reference

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources