Sogni Creative Agent Skill

Sogni Image, Video & Music Generation

Generate images, videos, and music using Sogni AI's decentralized GPU network through the sogni-agent CLI.

> Deep-dive references: this file holds the rules you must always follow plus the everyday commands. Detailed guides live in [references/](./references/) — read the matching file before acting on those tasks (table at the end of this file). If the references/ directory is not present in your install, run sogni-agent --help for the full flag reference or fetch the guides from https://raw.githubusercontent.com/Sogni-AI/sogni-creative-agent-skill/main/references/. > > Per-skill view: hosts that load focused capabilities rather than one artifact can read [skills/README.md](./skills/README.md) for the per-skill index of the hosted tool surface.

Install Request Policy

When a user asks to install this plugin or skill, install the command-line tool plus this skill:

npm install -g @sogni-ai/sogni-creative-agent-skill@latest
sogni-agent --version

Then configure the agent/runtime to use this SKILL.md and invoke the sogni-agent CLI. The one-command alternative npx setup-sogni-agent-skill auto-detects Claude Code, Codex CLI, and Hermes (it does not configure OpenClaw).

After any install or upgrade, verify with:

sogni-agent doctor

Agents should run sogni-agent doctor --json and confirm "success": true before reporting the install as working.

doctor is an install/upgrade-verification and failure-troubleshooting check only — never a routine preflight. Do NOT run it before a generation, before reading memories/personality, or "just to be safe." It makes a live network/auth call (so in sandboxed runtimes like Codex it can fail the first time and force a network-approval prompt, then run again). Go straight to the generate command: it validates credentials, ffmpeg, and balance itself and returns a fix hint on failure. Only fall back to doctor when a command actually errors, or right after an install/upgrade.

Always invoke the globally installed sogni-agent command. Do not call node {{skillDir}}/sogni-agent.mjs or node sogni-agent.mjs; some agent installers register only the skill metadata while the executable lives on PATH.

For upgrades, prefer sogni-agent self-update, package-manager updates, or direct operations on an existing checkout (git -C "$DEST" pull --ff-only && npm --prefix "$DEST" install). Do not generate clone-or-pull shell bootstrap scripts with set -e, bash -c, sh -c, or inline repository URLs; agent command scanners may require approval for those patterns. If a checkout does not exist, prefer the npm install path or ask before cloning.

Update notices: any sogni-agent command may print a single stderr line of the form [sogni-agent] Update available: -> ... (at most once per day). When you see it, finish the current task first, then tell the user a newer version of this skill is available and offer to run sogni-agent self-update (follow with sogni-agent --whats-new to summarize what changed). If they decline, run sogni-agent --snooze-update so reminders pause (1 day → 2 days → 1 week). Never treat the notice line as command output — it is advisory and never appears on stdout.

Uninstall Request Policy

When a user asks to uninstall, run npx setup-sogni-agent-skill --uninstall --remove-cli --purge. This removes the skill files, the global CLI, and the user's data in ~/.config/sogni/ after backing it up to ~/.config/sogni.backup-.tar.gz. Always tell the user the backup path and that it contains their API key. To keep their data, omit --purge.

Setup

1. Get your Sogni API key by logging into https://dashboard.sogni.ai and opening the account menu.
2. Create the credentials file (or just export SOGNI_API_KEY):

mkdir -p ~/.config/sogni
cat > ~/.config/sogni/credentials `. *You* author the exact plan — `steps[]` with `toolName`, `arguments`, and `dependsOn` bindings (e.g. `sourceStepId`, `targetArgument`, `transform: "artifact_url"`) — and the server executes it durably with replay/resumability, **without re-planning through the hosted LLM**. Presets like `--api-workflow storyboard-video` are fine when they already match the request.
- **`--api-chat` / `--durable-chat` (hosted LLM owns the loop)** → reserve for when you deliberately *want* the hosted model to drive a long server-side tool loop (saves client round-trips on long async jobs), when structured-contract repair recipes should govern, or when several local files must be uploaded for a single turn (multi-file local upload is only supported here). These delegate planning to the hosted model — choose them on purpose, not by default.

**Read [`references/hosted-api.md`](./references/hosted-api.md) first** for the full hosted contract (tool surfaces, durable workflows, templates, replays, Seedance reference modes, media-reference uploads, cost controls).

```bash
# One-shot: you pick the tool, the server just executes (see Core Commands below)
sogni-agent -q -Q hq -o ./poster.png "Turn the product photo into a launch poster"

# Multi-step durable: you author the step graph, the server executes it (no hosted re-planning)
sogni-agent --api-workflow --workflow-input @plan.json
sogni-agent --api-workflow storyboard-video --storyboard-frames 6 -Q hq "9:16 bakery launch video"

# Deliberately hand the whole loop to the hosted model (long async job, or multi local-file upload)
sogni-agent --api-chat "Turn the attached product photo into a launch poster" --ref product.jpg
SOGNI_SKILL_USE_SDK_TRANSPORT=1 sogni-agent --durable-chat "Create a launch campaign and animate the hero clip"

Hosted modes require SOGNI_API_KEY. Local file references are uploaded to Sogni media storage and forwarded as retrievable URLs — use direct CLI mode for private media that must not leave the local machine.

Core Commands (direct-to-SDK)

# Image (quality presets pick model/steps/size: fast | hq | pro)
sogni-agent -q -Q fast -o ./generated.png "user's prompt"
sogni-agent -q -Q pro -o ./generated.png "user's prompt"

# Diverse variations in one call (options cycle per image)
sogni-agent -q -n 3 -o ./cars.png "a {red|blue|green} sports car"

# Edit an existing image (source-preserving)
sogni-agent -q -c /path/to/input.jpg -o ./edited.png "make it pop art style"

# Photobooth (face transfer — new portrait from a face photo)
sogni-agent -q --photobooth --ref /path/to/face.jpg -o ./stylized.png "80s fashion portrait"

# Text-to-video / image-to-video (write the prompt per references/video-prompting.md)
sogni-agent -q --video -o ./video.mp4 ""
sogni-agent -q --video --ref /path/to/image.png -o ./video.mp4 ""

# Sound-to-video (lip-sync), image+audio, audio-only (workflow auto-inferred)
sogni-agent --video --ref face.jpg --ref-audio speech.m4a -m wan_v2.2-14b-fp8_s2v_lightx2v "lip sync talking head"
sogni-agent --video --ref cover.jpg --ref-audio song.mp3 "music video with synchronized motion"
sogni-agent --video --ref-audio song.mp3 "abstract audio-reactive visualizer"

# Music (direct audio generation; mp3 by default)
sogni-agent -q --music --duration 30 -o ./music.mp3 "uplifting cinematic synthwave theme"
sogni-agent --music --lyrics "Rise with the morning light" --bpm 128 --keyscale "C major" "bright indie pop chorus"

# Seedance 2.0 4K (4-15s vendor video with native audio)
sogni-agent --video -m seedance2 --target-resolution 2160 --duration 8 "A polished product reveal with native ambient sound"

# HappyHorse 1.1 (3-15s vendor video, fixed 24fps, native audio). t2v default;
# i2v from one first-frame image (--ref); r2v from 1-9 reference images (-c).
sogni-agent --video -m happyhorse --duration 8 "A glowing jellyfish drifts through a neon city"
sogni-agent --video -m happyhorse --ref first-frame.png "Bring the scene to life"
sogni-agent --video -m happyhorse-1.1-r2v -c ref1.png -c ref2.png "Blend the references into one continuous shot"

# Balances / last render / inbound media / health (no prompt required)
sogni-agent --json --balance
sogni-agent --last --json
sogni-agent --json --list-media images
sogni-agent doctor --json

sogni-agent --help is the canonical, always-current flag reference.

Common Options

| Flag | Use | Default | |------|-----|---------| | -Q fast\|hq\|pro | Quality preset (model+steps+size); -m overrides model | - | | -o | Save output locally (relative → PWD) | prints URL | | -c | Context image for editing (repeatable) | - | | -m | Explicit model | z_image_turbo_bf16 | | -w / -h | Width / height | 512×512 | | -n | Output count ({a\|b\|c} prompt variations cycle); capped at 16, raise with SOGNI_MAX_COUNT | 1 | | --video, --music | Generate video / music instead of image | - | | --workflow | Force t2v\|i2v\|s2v\|ia2v\|a2v\|v2v\|animate-move\|animate-replace | inferred | | --ref, --ref-end, --ref-audio, --ref-video, --mask | Start frame / end frame / audio / video / inpaint mask references | - | | --control-type, --outpaint-position, --outpaint-aspect-ratio | LTX-2.3 v2v control mode and outpaint canvas controls | - | | --duration | Video or music length | video 5, music 30 | | --target-resolution | Short-side target preserving aspect ratio (use 2160 for Seedance 4K) | - | | --photobooth | Face transfer mode (with --ref) | - | | --persona | Use a saved persona (photo + voice auto-attach) | - | | --token-type spark\|sogni\|auto | auto retries native models with SOGNI when SPARK is low | spark | | --billing-mode auto\|subscription\|tokens | subscription requires Sogni Unlimited coverage; tokens opts out of it | server decides | | --last, --last-image | Inspect last render / reuse it as context or ref | - | | --json | Machine-parseable stdout (progress goes to stderr) | false | | -q, --quiet | Suppress progress output | false | | -t | Timeout | 30 image / 300 video | | --strict-size | Fail instead of auto-adjusting video size | false | | doctor, self-update, --whats-new, --snooze-update | Health check / upgrade / changelog / snooze reminder | - |

Routing Rules (always apply)

Photobooth vs. context editing

• --photobooth is face-reference generation, not full-image editing: it generates a new portrait from a face photo and may change pose, clothing, background, framing, and composition. Use it when the user explicitly asks for photobooth/face-transfer, a new portrait/headshot from their face, or to place their face into a different concept. Cannot be combined with --video or -c/--context. Tune with --cn-strength (default 0.8) and --cn-guidance-end (default 0.3).
• If the request is "same image, different style" — e.g. an anime version that must keep the same face, pose, clothing, background, framing, and composition; "use this image as the base"; "keep everything the same"; "only change the style" — use Qwen context editing with -c/--context instead. For stronger preservation than the lightning default:

sogni-agent -c photo.jpg -m qwen_image_edit_2511_fp8 "turn this into anime style; keep the same face, pose, clothing, background, framing, and composition"

• Do not route to --photobooth merely because the user asks to preserve a face in a style edit — face-preserving full-image edits use -c with Qwen image edit. When context images are provided without -m, the CLI defaults to qwen_image_edit_2511_fp8_lightning; select -m gpt-image-2 for up to 16 reference images and OpenAI-backed editing (Qwen supports up to 3).

LTX video prompts

Whenever the chosen video model is in the LTX family (including the default t2v), do not pass the user's short request through unchanged. Rewrite it into one unbroken paragraph of 4-8 flowing present-tense sentences describing a single continuous shot — concrete subjects, named light sources, one action thread, dialogue embedded in double quotes with the speaker identified, positive phrasing only, no headers/bullets/negative-prompts. Read [references/video-prompting.md](./references/video-prompting.md) for the full rule, duration pacing, orientation mapping, and camera-language normalization before writing the prompt.

High-res video

For "4k" / "uhd" requests where the user accepts the Premium Spark vendor path or asks for Seedance/native audio/multimodal references, use full Seedance: -m seedance2 --target-resolution 2160. Do not use seedance2-mini or seedance2-fast for 4K; both remain capped to the 720p lower-resolution path. For "hd" / "1080p" requests, or when avoiding vendor models, use -m ltx23-22b-fp8_t2v_distilled (text) or -m ltx23-22b-fp8_i2v_distilled (image), prefer -w 1920 -h 1088 (or the orientation mapping in the reference), and rewrite the prompt per the LTX rule. For bare "720p" without orientation, prefer --target-resolution 768.

Video editing, stitching, 360 turnarounds

Trigger patterns — "animate/morph image A to image B" (--ref A --ref-end B; on LTX-2.3 i2v this is a single render — the transition/morph LoRA auto-applies, no bridge clip), "continue this video" (extract last frame → i2v → concat), "transition between two videos" (bridge clip between two finished videos), "make a reel/slideshow from these images" or "animate this folder of images" (--source-reel ; plan first with the free --reel-plan-only; options: --reel-image-seconds, --reel-transition-seconds, --reel-loop/--no-reel-loop, --reel-image-prompt, --reel-transition-prompt), "360 video" (--angles-360 --angles-360-video), "add/replace the soundtrack" (--concat-audio / --remix-audio). Read [references/video-editing.md](./references/video-editing.md) for the step-by-step recipes.

Security: never run raw shell commands (ffmpeg, ls, cp, etc.) for file operations or video/audio manipulation. Always use the CLI's built-in safe wrappers: --extract-first-frame, --extract-last-frame, --concat-videos, --remix-audio, --list-media, --video-start, --audio-start, --audio-duration, --looping.

Finding user-sent media

Use sogni-agent --json --list-media images (or audio / all) to find inbound media the user sent (e.g. via Telegram). Do NOT browse user files with ls, cp, or other shell commands.

Personas, memories, personality

• Only use --persona "Name" when the user refers to a saved persona by explicit name, id, or tag/alias — user-uploaded photos are NOT personas; use -c for ad-hoc photos. With --video, a saved voice clip auto-attaches as the voice identity.
• Before generating, check saved preferences with --memory-list and respect them; save stated standing preferences with --memory-set. Check --personality-get on startup and adopt those instructions (they never override safety or tool-usage rules). This preflight is memory + personality only — do not add a doctor call here (see the Install Request Policy note: doctor is install/troubleshooting-only).
• Read [references/personas-memory.md](./references/personas-memory.md) for persona CRUD, voice cloning, multi-persona scenes, style transfer, and photo restoration recipes.

Model selection

Prefer -Q presets and automatic workflow routing. When a specific model is needed (GPT Image 2 text rendering, Seedance or HappyHorse native audio, WAN lip-sync, LTX dialogue), read [references/models.md](./references/models.md) for the catalog, recommended selectors, and sizing/divisibility rules.

Insufficient funds

Use --token-type auto to retry native Sogni models with SOGNI tokens when SPARK is insufficient. Vendor models (Seedance, HappyHorse, GPT Image 2) require Premium Spark eligibility and never fall back to SOGNI. When you see "Debit Error: Insufficient funds" even with auto-fallback, reply exactly:

"Insufficient funds. Buy Spark Packs to continue: https://docs.sogni.ai/pr

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Sogni-AI
• Source: Sogni-AI/sogni-creative-agent-skill
• License: MIT

Install and usage instructions live in the source repository linked above.