image-posting — Displaying images in chat responses

Overview

There are two mechanisms for including images in chat responses:

1. Automatic extraction from tool results — When tool results contain image URLs or paths, the framework automatically detects and displays them in the chat bubble
2. Markdown image syntax — Writing ![alt](url) in the response text causes the frontend to render it

Method 1: Automatic display from tool results

If the result of calling a tool (web_search, image_gen, etc.) contains image information, the framework automatically displays the image in the chat bubble. No special operation is needed on the Anima side.

Conditions for automatic detection

The following are treated as images when detected in the tool result JSON:

• Path detection: Values of the path, file, filepath, asset_path keys, or paths in the result string starting with assets/ / attachments/ (.png .jpg .jpeg .gif .webp) → source: generated (trusted)
• URL detection: When image URLs exist in the url, image_url, thumbnail, src keys → source: searched (via proxy, allowed domains only)
• image_gen specific: The entire tool result is scanned with a regular expression, and paths containing assets/ or attachments/ are automatically extracted

Up to 5 images per response.

image_gen tool implementation and pipeline

• Entry: The dispatch() of core/integrations/image_gen.py processes generate_character_assets and other tool names. It is also a facade that proxies test-related mutable attributes around GLB (_FBX2GLTF_PATH, etc.) to _image_glb.
• Batch generation body: The ImageGenPipeline.generate_all() of core/integrations/_image_pipeline.py orchestrates 7 steps.
• API client, constants, and prompts: core/integrations/image/ (e.g., novelai.py, fal.py, meshy.py, constants.py's NOVELAI_MODEL / _DEFAULT_ANIMATIONS, prompts.py's expression prompts).

Content of the 7 steps (for the full pipeline when steps is unspecified in anime style):

1. fullbody — Anime (when image_style is not realistic): If NOVELAI_TOKEN exists, use NovelAI (NOVELAI_MODEL = nai-diffusion-4-5-full). If not, and FAL_KEY exists, use Fal Flux Pro. If neither exists, error. Realistic: Always Fal Flux Pro only (FAL_KEY required. No fallback to NovelAI). config.image_gen's style_prefix / style_suffix / negative_prompt_extra, style_reference (image bytes), and vibe_strength / vibe_info_extracted for Vibe Transfer are reflected here.
2. bustup — Bust-up with Flux Kontext (fal). Expression names are only valid from core.schemas.VALID_EMOTIONS (neutral, smile, laugh, troubled, surprised, thinking, embarrassed). By default, all of the above are generated. neutral references the full body; others reference a neutral bust when possible (falling back to full body if unavailable). Separate prompts and guidance for realistic/anime (prompts.py).
3. icon — Square icon with Flux Kontext referencing the neutral bust. On success, attempts to update the icon paste template with persist_anima_icon_path_template() (processing continues even on failure).
4. chibi — Chibi character image with Flux Kontext referencing the full body.
5. 3d — Meshy Image-to-3D (default ai_model: meshy-6) from chibi to avatar_chibi.glb.
6. rigging — In the pipeline, rigging is performed via input_task_id from the task_id of the immediately preceding Image-to-3D using create_rigging_task. After saving the rigged GLB, optimize_glb; attached walking animations are converted to anim_*.glb via download_rigging_animations (using strip_mesh_from_glb when possible). Standalone tool generate_rigged_model / generate_animations's dispatch side converts an existing GLB to a data URI and POSTs it to MESHY_RIGGING_URL (note that the input path differs from pipeline step 6).
7. animations — If the animations argument is not provided, uses _DEFAULT_ANIMATIONS (idle, sitting, waving, talking and Meshy action IDs). If rigging was not performed in the same execution, re-fetches rig_task_id from the existing avatar_chibi.glb via create_rigging_task_from_glb before generating additional animations.

Realistic style (config.image_gen.image_style == "realistic"): When steps is unspecified, the default enabled steps are fullbody / bustup / icon only (chibi, 3D, rigging, and additional animations do not run by default). In generate_character_assets of dispatch, if the prompt looks like Danbooru-style tags, _looks_like_anime_prompt may automatically convert it via _convert_anime_to_realistic for realistic output.

Style reference (Vibe Transfer): ImageGenPipeline passes the path of config.style_reference (when it exists) to full-body generation. Additionally, when supervisor_name is specified in generate_character_assets and the supervisor's assets/ contains avatar_fullbody.png or avatar_fullbody_realistic.png (depending on style), it is loaded as an override for style_reference. generate_all() also contains vibe_image / vibe_strength / vibe_info_extracted / seed / expressions / steps / progress_callback, but what the current dispatch passes from tool arguments is limited to prompt, negative_prompt, skip_existing, steps, animations, supervisor_name (and handler-injected anima_dir).

generate_fullbody (standalone): The dispatch implementation is always NovelAIClient only (no fallback even if Fal is available in the environment). It also does not reference image_style. Output is always avatar_fullbody.png. If realistic full-body or pipeline consistency is needed, use generate_character_assets.

Return value of generate_character_assets (JSON)

Keys equivalent to PipelineResult.to_dict() (paths are strings, or null if absent):

PNG paths are subject to automatic chat display. GLB files are handled separately for asset storage, workspace, etc.

Output filename mapping table

Pipeline (anime image_style)

Pipeline (realistic) — Full body, bust, expressions, and icons have _realistic appended to the filename:

• Full body: avatar_fullbody_realistic.png
• Neutral bust: avatar_bustup_realistic.png
• Expressions: avatar_bustup_smile_realistic.png, etc. (consolidated in bustup_expressions)
• Icon: icon_realistic.png

Standalone dispatch (individual tools within dispatch)

Default additional animation names and Meshy action IDs (pipeline animations step): idle: 0, sitting: 32, waving: 28, talking: 307 (overridable via the animations argument).

Proxy restrictions for searched images

External URL images are served via a proxy for security. At the time of artifact extraction, only the following allowed domains are detected:

• cdn.search.brave.com
• images.unsplash.com
• images.pexels.com
• upload.wikimedia.org

URLs from domains other than the above are not automatically displayed even if included in tool results. The proxy itself performs safety checks such as HTTPS enforcement, private/local rejection, magic byte validation, SVG rejection, size and rate limits (the open_with_scan / allowlist modes can be switched via config.server.media_proxy).

Method 2: Markdown image syntax

Write Markdown image syntax directly in the response text to display images.

Shortened path (recommended)

The frontend automatically completes the API path with your own Anima name. Just write the filename:

![説明](attachments/ファイル名)
![説明](assets/ファイル名)

Example:

スクショ撮りました！
![ANAトップページ](attachments/ana_top.png)

Full path

You can also write the API path explicitly:

![説明](/api/animas/{自分の名前}/assets/{ファイル名})
![説明](/api/animas/{自分の名前}/attachments/{ファイル名})

Screenshot save location

When taking screenshots with agent-browser or similar, saving directly to your own attachments directory is the most reliable:

agent-browser screenshot ~/.animaworks/animas/{自分の名前}/attachments/screenshot.png

Example (for aoi):

agent-browser screenshot ~/.animaworks/animas/aoi/attachments/page_screenshot.png

After saving, write the following in the response to display it:

![ページのスクショ](attachments/page_screenshot.png)

Files saved to ~/.animaworks/tmp/attachments/ are also displayed as a fallback, but since it is a temporary directory, persistence is not guaranteed.

Notes

• Asset paths of other Anima instances cannot be referenced directly (outside permission scope)
• Direct links to external URLs are not recommended. URLs from domains outside the allowed list are not automatically displayed and may be blocked by the proxy's safety checks
• Results from generate_character_assets contain paths such as fullbody / bustup / bustup_expressions / icon / chibi in the JSON, so PNGs are automatically displayed and Markdown syntax is often unnecessary
• Standalone generate_bustup / generate_chibi have a fixed reference of avatar_fullbody.png (they do not read avatar_fullbody_realistic.png for realistic). Standalone generate_fullbody is NovelAI-only as shown in the table above, and its filename and generation path do not match the realistic full body in the pipeline. When mixing pipeline and standalone tools, check the actual file at assets/
• Image generation takes a long time. The framework targets it for dedicated thread pool execution and background tool configuration. From the CLI, asynchronous execution such as animaworks-tool submit image_gen … may be recommended (see common_knowledge/operations/background-tasks.md, etc.)
• Maximum of 5 images automatically displayed per response