image_generate
Generate still-image assets, with distinct workflows for per-shot storyboard/frame images, reusable shot-element references, and scene-level moodboards; fal-backed requests return an async job to poll with `job_get`.
When to use
- Use `workflow=generate_shot` when the caller asks for a storyboard frame, shot panel, first frame, last frame, or any image for one numbered shot.
- For a normal storyboard package, omit `composition_mode` or set `composition_mode=overall_storyboard` so BeatBandit creates the preserved Overall storyboard image. Use `moments_grid_4` / `moments_grid_9` only when the caller explicitly asks for key moments.
- For a first-frame candidate, set `workflow=generate_shot`, `payload.asset_type=first_frame`, and `payload.composition_mode=firstframe_grid_4` or `firstframe_grid_9`; do not use `overall_storyboard`.
- For a last-frame candidate, set `workflow=generate_shot`, `payload.asset_type=last_frame`, and `payload.composition_mode=lastframe_grid_4` or `lastframe_grid_9`; do not use `overall_storyboard`.
- Use `workflow=generate_scene_moodboard` only when the caller asks for a scene moodboard, visual development board, or reusable master art-direction reference for a scene/scope.
- Use `workflow=generate_element` when the caller asks for a character, location, object, or prop reference image.
- If `workflow=generate_element` is requested for a named character/location/object and no recurring element exists yet, first create it with `shot_mutate(entity_type=element, operation=upsert_element, token=..., element_type=...)`, then call `image_generate` with the returned element id.
- Use when the caller wants BeatBandit's actual still-image generation pipeline, not manual uploads.
- When `payload.provider=fal` or a fal-backed model is selected, treat `image_generate` as a parent async workflow: start it once, then call `job_get` with the returned `job_id` until completion.
When not to use
- Do not use for video or audio workflows.
- Do not use `generate_scene_moodboard` when the user asks for individual storyboard panels or clean single-shot frames; use `generate_shot` with a `shot_card_id` instead.
- Do not expect `prompt_override` to change the selected artifact type. It only changes prompt content inside the chosen workflow.
- Do not retry `image_generate` with the same fal-backed inputs while a returned `job_id` is still running; poll `job_get` instead.
- Do not call `image_generate(workflow=generate_element)` with an invented or missing `element_id`; discover existing elements through `project_assets_query` / `shot_element_library`, or create the recurring element first with `shot_mutate`.
Examples
- “Generate a storyboard panel for shot 12 with `workflow=generate_shot`, `asset_type=storyboard`, and the shot's `shot_card_id`.”
- “Generate the default Overall storyboard image for shot 12 by omitting `composition_mode` or passing `composition_mode=overall_storyboard`.”
- “Generate key moments for shot 12 with `composition_mode=moments_grid_4` only if the user asks for multiple key moments.”
- “Generate first-frame candidates for shot 12 with `asset_type=first_frame` and `composition_mode=firstframe_grid_4`.”
- “Generate a new reference image for the”
- “Generate a full-body photoreal reference for Anna after creating/finding her recurring element id.”
- “Generate a scene moodboard for scene 50.10.20.”
- “Generate a shot image using a selected scene moodboard as a reference source.”
- “Generate a fal-backed shot image with `payload.provider=fal`, then poll `job_get(job_id=...)` and inspect `result_data` or `asset_display` after completion.”
Anti-examples
- Generate a video timeline export.
- Ask for "single storyboard panel" but call `workflow=generate_scene_moodboard`; use `workflow=generate_shot` instead.
- Call `image_generate` again because a fal-backed start response is still processing; use `job_get` with the original `job_id`.
- Generate an image for "Anna" without resolving or creating Anna's recurring element first; use `project_assets_query` / `shot_element_library` and `shot_mutate` first when needed.
Workflows
Switch behavior by setting the workflow input field.
| Workflow | Phases | Calls |
|---|---|---|
generate_shot | start | image.generate |
generate_element | start | image.generate |
generate_scene_moodboard | start | image.generate |
Linked resources
Tool calls may return resource_links pointing at these resource families.
Input schema
image_generate input
{
"$ref": "./image.generate.input.json"
}Output schema
image_generate output
{
"$ref": "./image.generate.output.json"
}← All toolsv1 · workflow_runner