/sn-image-imitate

name: sn-image-imitate
description: |
  Generates a new image that imitates the style of a reference image while updating content based on user intent.
  Uses a three-stage pipeline: image annotation (long caption), caption rewriting, and image generation.
  Use when user asks to "imitate style", "保持这个风格重画", "按这张图风格生成", or "style transfer with new content".
metadata:
  project: SenseNova-Skills
  tier: 1
  category: scene
  priority: 8
  user_visible: true
triggers:
  - "style imitation"
  - "style transfer"
  - "imitate this image style"
  - "use this style with new content"
  - "reference style image"
  - "风格模仿"
  - "风格迁移"
  - "模仿这张图风格"
  - "按参考图风格生成"

sn-image-imitate

Image style imitation scene skill (tier 1), relying on the `sn-image-recognize`, `sn-text-optimize`, and `sn-image-generate` tools provided by `sn-image-base` (tier 0).

Features:

• Extracts high-fidelity long caption from a reference image
• Rewrites caption according to user requested content change while preserving style and layout
• Enforces layout-lock constraints during caption rewrite
• Performs post-generation layout consistency review and bounded retries
• Returns structured process artifacts for debugging and reproducibility

Non-goals

• Pure neural style transfer without content change (use dedicated style-transfer tools instead)
• Local editing / inpainting of specific regions within the reference image
• Processing video or animation input (only single static images are supported)
• Batch generation from multiple reference images in one invocation
• Guaranteeing pixel-level fidelity to the reference; the skill targets layout and style consistency, not exact reproduction

Input Specification

• `reference_image` (string, required): local path or URL of the style reference image
• `target_content` (string, required): new content user wants in the generated image
• `output_mode` (string, default `friendly`): output mode, `friendly` or `verbose`
• `aspect_ratio` (string, default `16:9`): output aspect ratio for generation
• `image_size` (string, default `2k`): output image size preset
• `max_attempts` (int, default `3`): maximum generation attempts for meeting layout consistency
• `layout_threshold` (float, default `0.75`): minimum layout similarity score to accept result

Environment Variable

Dependency installation and API key configuration are for [sn-image-base](../sn-image-base/SKILL.md) skill.

The minimum environment variables to configure `sn-image-base` skill running with [SenseNova Token Plan](https://platform.sensenova.cn/token-plan):

SN_BASE_URL="https://token.sensenova.cn/v1"
SN_API_KEY="your-api-key"

Fallback priority is dedicated variable > domain shared variable > global variable. Text calls use `SN_TEXT_API_KEY` -> `SN_CHAT_API_KEY` -> `SN_API_KEY`; vision calls use `SN_VISION_API_KEY` -> `SN_CHAT_API_KEY` -> `SN_API_KEY`; image generation uses `SN_IMAGE_GEN_API_KEY` -> `SN_API_KEY`.

Please refer to the **Python dependencies and API keys** section in [`sn-image-generate_en.md`](../../docs/sn-image-generate_en.md) for more configurations.

API Configuration

All API calls in this skill are executed through the `sn_agent_runner.py` of the `sn-image-base` skill, please refer to the `sn-image-base` skill ([README.md](../sn-image-base/README.md)) for more details.

• **VLM call**: `sn-image-recognize` (Step 1 & 3)
• **LLM call**: `sn-text-optimize` (Step 2)
• **Image generation call**: `sn-image-generate` (Step 3)

**When encountering `MissingApiKeyError` or needing explicit model control**: pass model and auth params explicitly via CLI arguments. See `$SN_IMAGE_BASE/references/api_spec.md`.

**`$SN_IMAGE_BASE` path explanation**: `$SN_IMAGE_BASE` is the installation directory of the `sn-image-base` skill (`SKILL.md` exists). The agent can locate this path by skill name `sn-image-base`.

Architecture: Main Agent + Worker Agent

This skill uses a two-tier agent architecture:

• **Main Agent**: receives user request, normalizes parameters, sends preflight, invokes Worker Agent, and sends final text/image to user
• **Worker Agent**: executes fixed 3-step pipeline and returns structured JSON

**Responsibility Boundaries**:

• Worker Agent does not send any user-visible message directly
• Main Agent sends all user-facing responses
• Worker Agent last message must be and only be the JSON string defined in Return Contract
• Worker Agent executes VLM/LLM/image calls directly; no nested subagent for these low-level calls

Workflow

Main Agent Workflow

1. Extract `reference_image`, `target_content`, `output_mode` (default `friendly`), `aspect_ratio` (default `16:9`), `image_size` (default `2k`), `max_attempts` (default `3`), and `layout_threshold` (default `0.75`) 2. Validate required inputs:

• `reference_image` is provided and resolvable
• `target_content` is non-empty

3. Send preflight message: `"Using sn-image-imitate skill to generate a style-consistent image, please wait..."` 4. Start Worker Agent with full normalized parameters and working directory 5. On Worker result:

• `status=ok`: send final summary and generated image
• `status=error`: report the actual error

Worker Agent Workflow

Worker Agent receives `reference_image`, `target_content`, `output_mode`, `aspect_ratio`, `image_size`, `max_attempts`, `layout_threshold`, and the working directory of this skill (`$SKILL_DIR`).

**Error Handling Strategy**:

All `sn_agent_runner.py` calls share the same error handling rules:

• If the subprocess exits with non-zero code, crashes, or times out: do not fallback, return `status=error` with the actual error message from stderr or the system error string
• If the subprocess returns invalid JSON or the JSON lacks an expected `result` field: return `status=error`, do not silently continue with empty or default values
• If the VLM review call fails during Step 3, treat the attempt as incomplete: do not record a score, and either retry the revie