Expert Usage Guide

• nano_banana: default choice for general text-to-image generation.
• seedream: use when the user explicitly asks for Seedream or the task clearly needs that provider.
• gpt_image: use when the user explicitly asks for GPT Image / OpenAI image generation, or when the task should follow OpenAI-native image parameters.

Recommended parameters:

{"prompt":"a cinematic cat poster","provider":"nano_banana"}

{"prompt":"a cinematic cat poster","provider":"seedream"}

{"prompt":"a cinematic cat poster","provider":"gpt_image","size":"1536x1024","quality":"medium"}

Do not use when:

• The user wants to edit an existing image.
• The user first needs image understanding, grounding, segmentation, or prompt extraction.

ImageEditingAgent

Use when:

• The user wants to modify one or more existing images.
• The task is "change this image", "replace background", "make it blue", "edit the uploaded image", and similar.

Recommended parameters:

{"input_path":"inbox/cli/source.png","prompt":["replace the background with a clean white studio"],"provider":"nano_banana"}

Use input_paths when several images or references are required.

Do not use when:

• The user wants a mask first.
• The user wants pure text-to-image generation.

ImageSegmentationAgent

Use when:

• The user wants a mask, cutout, localized edit, region-only processing, or inpaint-style preparation.
• The task says "segment", "extract the subject", "generate a mask", "keep only the person", or similar.

Recommended parameters:

{"input_path":"inbox/cli/source.png","prompt":"person","threshold":0.2}

Key follow-up rule:

• After success, read current_output.results[0].mask_path.
• That mask_path is a reusable workspace file path for later tools or experts.

Typical chaining:

1. Call ImageSegmentationAgent.
2. Read mask_path.
3. Pass that workspace path to later editing or file-processing steps.

ImageGroundingAgent

Use when:

• The user needs locations or bounding boxes, not a pixel mask.
• The task is to find where an object is in the image.

Recommended parameters:

{"input_path":"inbox/cli/source.png","prompt":"red handbag"}

Prefer this over segmentation when:

• Bbox information is enough.
• The next step only needs rough localization.

ImageUnderstandingAgent

Use when:

• The user wants description, style analysis, OCR, prompt reverse engineering, or a combined understanding pass.
• The task says "describe this image", "read the text in this image", "analyze the style", "reverse prompt this image", or similar.

Recommended parameters:

{"input_path":"inbox/cli/source.png","mode":"description"}

{"input_path":"inbox/cli/source.png","mode":"all"}

{"input_path":"inbox/cli/reference.png","mode":"prompt"}

Prefer this before generation or editing when:

• The image contents are unclear.
• You need to understand a reference before deciding the next step.

TextTransformExpert

Use when:

• The task is one atomic text transform only.
• The user wants rewrite, expand, compress, translate, structure, title, or script.

Recommended parameters:

{"input_text":"Launch a summer tea campaign.","mode":"rewrite"}

{"input_text":"Launch a summer tea campaign.","mode":"translate","target_language":"zh-CN"}

VideoGenerationAgent

Use when:

• The user wants a video generated from text or image-guided inputs.

Recommended parameters:

{"prompt":"make a cinematic cat video","provider":"seedance","mode":"prompt"}

{"input_path":"inbox/cli/first_frame.png","prompt":"animate this image","provider":"veo","mode":"first_frame"}

Do not use when:

• The task is only to generate still images.

VideoUnderstandingExpert

Use when:

• The task is about understanding an existing video, not generating one.
• The user wants description, shot breakdown, OCR, or prompt reverse engineering from a reference video.

Recommended parameters:

{"input_path":"inbox/cli/reference.mp4","mode":"description"}

{"input_path":"inbox/cli/reference.mp4","mode":"prompt"}

SpeechTranscriptionExpert

Use when:

• The user wants audio or video converted into text.
• The task is transcript-first, not audio editing or synthesis.

Recommended parameters:

{"input_path":"inbox/cli/interview.wav"}

{"input_path":"inbox/cli/interview.mp4","timestamps":true,"language":"en"}

SpeechSynthesisExpert

Use when:

• The user wants text or SSML converted into spoken audio.
• The task is voiceover, narration, or TTS.

Recommended parameters:

{"text":"Hello from Creative Claw."}

{"ssml":"<speak>Hello<break time=\"500ms\"/>world</speak>","speaker":"zh_female_yingyujiaoyu_mars_bigtts"}

MusicGenerationExpert

Use when:

• The user wants a generated song draft or BGM clip from text instructions.
• The task is music creation rather than speech synthesis.

Recommended parameters:

{"prompt":"cinematic orchestral background music","instrumental":true}

{"prompt":"warm folk pop song","lyrics":"custom lyric lines"}

SearchAgent

Use when:

• The user needs external references, inspirations, or web facts.

Mode strategy:

• image: use for visual references.
• text: use for factual or conceptual information.
• all: use when both are helpful.

Recommended parameters:

{"query":"editorial fashion poster references","mode":"image"}

{"query":"brand campaign visual strategy examples","mode":"text"}

KnowledgeAgent

Use when:

• The task needs design thinking, art direction, prompt planning, or creative decomposition before execution.
• The user wants several visual directions, campaign ideas, or prompt sets.

Recommended parameters:

{"prompt":"Design three visual directions for a premium matcha brand campaign"}

Prefer this before generation when:

• The task is underspecified.
• The user wants higher-level creative planning, not just direct rendering.

Common Chaining Patterns

Reference Image -> Better Prompt -> New Image

1. ImageUnderstandingAgent with mode="prompt"
2. ImageGenerationAgent

Video Reference -> Understand -> Decide Next Step

1. VideoUnderstandingExpert
2. Then choose VideoGenerationAgent, KnowledgeAgent, or file tools based on the result

Speech Media -> Transcript -> Script Rewrite

1. SpeechTranscriptionExpert
2. TextTransformExpert

Uploaded Image -> Understand -> Decide Edit Direction

1. ImageUnderstandingAgent
2. ImageEditingAgent

Uploaded Image -> Segment Subject -> Local Edit

1. ImageSegmentationAgent
2. Read mask_path
3. Use ImageEditingAgent or built-in file/image tools

Design Brief -> Creative Directions -> Final Rendering

1. KnowledgeAgent
2. ImageGenerationAgent

Need Web References Before Rendering

1. SearchAgent
2. KnowledgeAgent or ImageGenerationAgent

Routing Heuristics

• If the user says "generate", start from ImageGenerationAgent.
• If the user says "edit this image", start from ImageEditingAgent.
• If the user says "describe / OCR / analyze style / reverse prompt image", start from ImageUnderstandingAgent.
• If the user says "rewrite / translate / compress / title / script", start from TextTransformExpert.
• If the user says "find where", start from ImageGroundingAgent.
• If the user says "mask / cutout / segment", start from ImageSegmentationAgent.
• If the user says "analyze this video / break down shots / OCR video / reverse prompt video", start from VideoUnderstandingExpert.
• If the user says "video generation", start from VideoGenerationAgent.
• If the user says "transcribe audio / transcribe video / speech to text", start from SpeechTranscriptionExpert.
• If the user says "text to speech / narration / voiceover", start from SpeechSynthesisExpert.
• If the user says "BGM / generate music / song draft", start from MusicGenerationExpert.
• If the user says "search references / web info", start from SearchAgent.
• If the user says "give me design directions / creative plan", start from KnowledgeAgent.

Important Guardrails

• Do not call an expert just because one exists; choose it because it is the best fit.
• Do not use ImageGenerationAgent when the user clearly needs an image edit.
• Do not use ImageGroundingAgent when the next step truly needs a pixel mask; use ImageSegmentationAgent.
• Do not pass artifact names or vague labels when a workspace path is available.
• Do not invent unsupported provider names. Use only declared provider values.