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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
modelNoNARWHAL
aspectNoIMAGE_ASPECT_RATIO_LANDSCAPE
promptYes
entity_idYes
character_slot_indexYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.5/5.0
Behavior5/5

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

The description adds substantial runtime behavior beyond the annotations: one-shot-per-slot semantics, HTTP 500 on already-filled slots, the personality_notes prerequisite, identity drift for real-photo seeds, and per-account ownership. These are high-value disclosures not visible in the structured metadata.

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?

The description is long but dense with non-redundant caveats and routing rules, and the most important distinctions are front-loaded. Minor redundancy exists around the one-shot/'once' theme, but each paragraph earns its place.

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 mutating tool with no output schema, the description covers preconditions, failure modes, ownership constraints, and sibling alternatives exceptionally well. It does not state what the tool returns on success, but that omission does not significantly hinder correct selection and invocation.

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?

Adds crucial meaning for entity_id (provenance from create_character/create_character_from_photo/create_character_from_description) and character_slot_index (0=portrait, 1=body, plus server-side consistency). However, with 0% schema coverage, prompt, model, and aspect are not described in prose beyond what the schema enums/defaults already provide, so the compensation is partial.

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 concrete verb and resource: 'Generate a portrait or body image for an existing Flow character.' It also explicitly contrasts itself with generate_with_face and generate_video_with_reference, and states what it does NOT do, making sibling differentiation strong.

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 when-to-use and when-not-to-use guidance: don't re-call for slot 0 after create_character_from_description, call update_character with personality_notes first on fresh entities, use generate_with_face for 'character doing X', and use generate_video_with_reference for real-person identity. This is exemplary routing.

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