Skip to main content
Glama

openFlow

by io.github.molkex
OverviewDiscussionsAdmin

generate_character_image

Generate a portrait or body image for an existing Flow character.

entity_id: the character's entityId — from create_character or
create_character_from_photo, or create_character_from_description's own result
(which already calls this for slot 0 — no need to call it again for that slot).
character_slot_index: 0 for portrait, 1 for body. Flow keeps the two slots
visually consistent server-side once they share an entityId — no reference
image needed for the body shot.

ONE-SHOT PER SLOT, confirmed live 2026-07-25: each slot can be written exactly
once — a second generate_character_image call into an ALREADY-FILLED slot fails
(HTTP 500), it does not overwrite. Also confirmed: the FIRST write into a slot
500s on a card with no personality_notes saved yet — call update_character with
personality_notes before the first generate_character_image on a fresh entity_id.
If you're using create_character_from_description, both of these are already
handled for slot 0; this caveat mainly matters if you're driving slot 1 (body) or
entity_id yourself.

THIS TOOL DOES NOT PLACE A CHARACTER INTO A NEW SCENE — it only ever (re)writes
the character's own portrait/body slot, once. For "generate a picture of this
character doing X", use generate_with_face(character=..., prompt=...) instead,
which conditions on the reference image, not entity_id.

CAVEAT confirmed live 2026-07-11: for a character seeded from a REAL PHOTO
(create_character_from_photo), this text-prompt generation is NOT reliable for
identity — it conditions on a text description, not the real photo's pixels, and
was confirmed to drift to an unrelated-looking person even with a detailed
physical description saved on the entity. Fine for invented/stylized characters.
If the goal is "content that looks like a real person," use
generate_video_with_reference (r2v) instead — see its docstring.

Only works for the account whose project actually owns this entity_id —
characters are per-account, same as projects. Pass that account as `account`
(optional for a character saved in list_characters(): it is looked up).

Input Schema

NameRequiredDescriptionDefault
modelNoBELUGA
aspectNoIMAGE_ASPECT_RATIO_LANDSCAPE
promptYes
accountNo
entity_idYes
character_slot_indexYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / aspect / enum
      Previous value: -[
-  "IMAGE_ASPECT_RATIO_LANDSCAPE",
-  "IMAGE_ASPECT_RATIO_PORTRAIT",
-  "IMAGE_ASPECT_RATIO_SQUARE"
-]New value: +[
+  "IMAGE_ASPECT_RATIO_LANDSCAPE",
+  "IMAGE_ASPECT_RATIO_PORTRAIT",
+  "IMAGE_ASPECT_RATIO_SQUARE",
+  "IMAGE_ASPECT_RATIO_LANDSCAPE_FOUR_THREE",
+  "IMAGE_ASPECT_RATIO_PORTRAIT_THREE_FOUR"
+]
  2. Changed2 schema fields changed
    • changedInput schema / properties / model / default
      Previous value: -"GEM_PIX_2"New value: +"BELUGA"
    • changedInput schema / properties / model / enum
      Previous value: -[
-  "NARWHAL",
-  "GEM_PIX_2",
-  "HARBOR_SEAL"
-]New value: +[
+  "BELUGA",
+  "GEM_PIX_2",
+  "HARBOR_SEAL"
+]
  3. Changed1 schema field changed
    • changedInput schema / properties / model / default
      Previous value: -"NARWHAL"New value: +"GEM_PIX_2"
  4. Changed1 schema field changed
    • addedInput schema / properties / account
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Account"
+}
  5. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only give readOnly=false/idempotent=false/destructive=false; the description adds substantial behavioral detail beyond that: one-shot-per-slot semantics, HTTP 500 on a second write with no overwrite, a 500 on first write without personality_notes, server-side slot consistency, and per-account ownership/scoping. It is consistent with idempotentHint=false.

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

Conciseness4/5

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

Front-loaded with the core purpose, then parameter notes, then caveats — a sensible structure. It is long and the live-confirmation dates and repeated 'this caveat mainly matters if...' framing add some bulk, but each block carries actionable information rather than filler.

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, non-idempotent, 6-parameter generation tool with no output schema and zero schema descriptions, the description covers preconditions, failure modes, alternatives, and account scoping thoroughly. The main omission is any indication of the return shape (job id, media handle) or latency, which an agent might want.

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?

Schema coverage is 0%, so the description must carry the load. It documents the non-obvious parameters well: entity_id's provenance (create_character / create_character_from_photo / create_character_from_description slot 0), character_slot_index (0=portrait, 1=body), and account (optional, auto-looked-up). prompt, model, and aspect are left undocumented, though their names and enums are largely self-describing.

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?

The first sentence gives a precise verb+resource+scope ('Generate a portrait or body image for an existing Flow character') and immediately bounds it against siblings by stating it 'DOES NOT PLACE A CHARACTER INTO A NEW SCENE' and naming generate_with_face instead. An agent can distinguish it from generate_image, generate_with_face, and generate_video_with_reference without opening a schema.

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?

Explicit routing: use generate_with_face for 'character doing X' scenes, use generate_video_with_reference for real-person identity. It states prerequisites (call update_character with personality_notes before the first write on a fresh entity_id) and the when-not (second write into a filled slot fails). Very few gaps left to inference.

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

All openFlow toolsInspect
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.

Resources