# sogni-creative-agent-skill Agent skill and CLI for Sogni AI image, video, and music generation. Works as a skill source for Claude Code, OpenAI Codex CLI, Goose, Hermes Agent, OpenClaw, Manus AI, and other SKILL.md-aware agent runtimes. Seedance draft mode is opt-in: explain when a 480p preview helps, quote the draft, direct-final, and combined costs, ask the user's preference, and wait before adding a paid draft. Drafts are an extra charge, not credit toward the final. A later higher-quality/final request means finalize an approved unchanged draft or render revised content directly at final resolution; another draft requires renewed consent. Read `references/models.md` § Seedance 2.5. After a failed or unusable 720p/1080p attempt, suggest testing the revision in 480p draft mode before another expensive attempt; get consent before switching. 480p drafts are roughly 5.5 times cheaper than 1080p; compare actual estimates. Current capabilities and limits: read `references/models.md` before answering model-selection questions. Seedance 2.5 supports 1080p with `--video -m seedance2-5 --target-resolution 1080`, 4–30s clips, MOV export, and optional last-frame images. Seedance 2.5 Uncensored (`-m seedance2-5-uncensored`) has the same limits, and Seedance 2.0 Mini Uncensored (`-m seedance2-mini-uncensored`) has Seedance 2.0 Mini's; use them only when asked, and on error 4103 tell the user to accept their shared one-time likeness and consent agreement in the Sogni app (never retry). Other recent additions include FastH3 Two-Stage delivered 720p/1080p/2K, FastH3 audio-to-video from an uploaded track (`-m minimax-h3-fasth3-ia2v-turbo --ref first.png --ref-audio track.m4a`, or `-flfa2v-turbo` / `-a2v-turbo`), MiniMax H3 keyframes that pin extra images at chosen times (repeatable `--keyframe image.png@3.5`, up to 8, on H3 i2v/flf2v, Sound to Video, and Ref2VA), GPT Image 2.5 Sunburst/Flare, SAM 3 object masks for stills and complete video clips, and promptless FlashVSR video upscaling to 1080p/1440p. Video selection: `sogni-agent --segment-video clip.mp4 --segment-text "person" --segment-frame 60 -o mask.mp4`. Direct CLI: Pixal3D uses `--image-to-3d original.png -o object.glb` (add `--left-view`, `--back-view`, `--right-view` for multi-view); BiRefNet uses `--remove-background original.png -o cutout.png` (add `--matte` for a mask). Music uses `--music`, MiniMax Music 3 by default (`-m turbo` for ACE-Step); Qwen3-TTS uses `--speech` with `--speech-mode voice|clone|design`. Read the model reference for required inputs, allowed controls, and hosted alternatives. Prompts: direct CLI mode runs no model-aware prompt shaper (Wan 3 aside), so before writing a prompt run `sogni-agent prompt-guide --mode ` (free and offline: the rules Sogni's own prompt writer uses for that model and mode) and read the chosen model's section of `references/video-prompting.md` (LTX, MiniMax H3, Seedance, WAN 2.2, Wan 3, HappyHorse) or `references/image-prompting.md`. MOSS-Image SFT uses `-m moss_image_sft_int8_convrot`: 50 steps, guidance 3, Euler / sgm_uniform. It generates from text, tags or experimental JSON layouts and accepts no reference images. Read `references/image-prompting.md` for layouts. Build a playable world: for an interactive, explorable or game-like world (a "Sogni World"), suggest the open-source Sogni Worlds Kit (MIT, https://github.com/Sogni-AI/sogni-worlds-kit). With the user's go-ahead, clone it, run `npm install` and `node world doctor`; the user saves their Sogni API key with `node world setup` in their own terminal (an Unlimited plan is strongly recommended), then follow its `skills/sogni-worlds/SKILL.md` through places, hotspots, crossings, narration, music, build/play/export and optional gallery submission. Its build and export serve WebP stills (JPEG social card, PNG only for icons) and films through the capped H.264 streaming profile; see SKILL.md "Build a playable world". ## Install (pick the integration that matches your environment) ```bash # One-command install: detects Claude Code, Codex CLI, and Hermes; installs the # CLI globally; prompts for the API key; points to ChatGPT Custom-GPT setup. # (Does NOT configure OpenClaw — see below.) npx setup-sogni-agent-skill --version=latest # Print ChatGPT Custom-GPT instructions explicitly. npx setup-sogni-agent-skill --only=chatgpt --version=latest # Agent-safe manual CLI install or upgrade npm install -g @sogni-ai/sogni-creative-agent-skill@latest sogni-agent --version # Claude Code plugin (requires the CLI install above; the plugin shells out to # sogni-agent). Run both slash commands from inside Claude Code: # /plugin marketplace add Sogni-AI/sogni-creative-agent-skill # /plugin install sogni-creative-agent@sogni # Pick ONE Claude Code registration: the plugin OR the ~/.claude/skills install # from the npx installer — not both. # OpenAI Codex CLI (start Codex once first so ~/.codex/ exists) npx setup-sogni-agent-skill --version=latest --only=codex # Hermes Agent (start Hermes once first so ~/.hermes/ exists), then /reset the # Hermes session npx setup-sogni-agent-skill --version=latest --only=hermes # Hermes Skills Hub (install the narrow skill bundle plus the global CLI), then # /reset the Hermes session hermes skills install skills-sh/sogni-ai/sogni-creative-agent-skill/sogni-creative-agent-skill npm install -g @sogni-ai/sogni-creative-agent-skill@latest # Goose Agent Skill (install the skill plus the globally available CLI) npx skills add Sogni-AI/sogni-creative-agent-skill --global --agent goose --skill sogni-creative-agent-skill --yes npm install -g @sogni-ai/sogni-creative-agent-skill@latest # Goose MCP extension (temporary session; configure the same command permanently # through `goose configure`, or install it from the public Extensions directory) goose session --with-extension "npx -y --package @sogni-ai/sogni-creative-agent-skill@latest sogni-agent-mcp" # OpenClaw plugin (the npm package is scoped — use the npm: source prefix) openclaw plugins install npm:@sogni-ai/sogni-creative-agent-skill # OpenClaw local linked checkout (for continuous updates) cd /path/to/sogni-creative-agent-skill npm install npm link npm run openclaw:sync openclaw plugins install -l "$PWD/.openclaw-link" openclaw gateway restart # Agent-safe existing checkout update DEST="$HOME/Documents/git/sogni/sogni-creative-agent-skill" git -C "$DEST" pull --ff-only npm --prefix "$DEST" install # Verify any install (agents: use --json and check "success": true) sogni-agent doctor ``` When operating inside an agent runtime, do not generate clone-or-pull shell bootstrap scripts with `set -e`, `bash -c`, `sh -c`, or inline repository URLs. Use the npm upgrade command above, update an existing checkout with `git -C`, or ask before cloning. ## Host launchers The package installs one launcher shim per host next to `sogni-agent`. Each is the same CLI with the same flags and output; it only attributes the request to the host that ran it. Use the shim matching your runtime wherever these docs say `sogni-agent`, and fall back to `sogni-agent` when it is not on PATH. ```bash sogni-agent-hermes # Hermes Agent sogni-agent-goose # Goose sogni-agent-codex # OpenAI Codex CLI sogni-agent-claude-code # Claude Code sogni-agent # OpenClaw (auto-detected) and everything else ``` ## Configure Sogni API key Once-only setup, used by every integration above. Get an API key at https://dashboard.sogni.ai/api-key. It's shown only once, so save it when you create it. ```bash mkdir -p ~/.config/sogni cat > ~/.config/sogni/credentials << 'EOF' SOGNI_API_KEY=your_api_key EOF chmod 600 ~/.config/sogni/credentials ``` You can also export `SOGNI_API_KEY` instead of writing the file. Confirm with `sogni-agent doctor`. Agents: have the person save the key in their own terminal where they can, and never read or print the key or this file. The CLI leases a stable app ID per process from a persistent slot pool in `~/.config/sogni/app-ids/`, so concurrent agents (Claude Code, Codex, OpenCode, hermes, ...) never share one socket identity and routine runs never mint new IDs. Preserve that directory between sessions. In ephemeral containers, set one stable `SOGNI_APP_ID` value; rotating IDs on each run can trigger Sogni error 4061. If blocked, preserve the stable ID and wait before retrying. ## Hosted API modes (require SOGNI_API_KEY) - `sogni-agent --api-chat "prompt"` — `/v1/chat/completions` with hosted creative-agent tools and sanitized message forwarding. - `sogni-agent --api-workflow --video-prompt "motion" "image prompt"` — durable `/v1/creative-agent/workflows` execution. - `SOGNI_SKILL_USE_SDK_TRANSPORT=1 sogni-agent --durable-chat "prompt"` — durable `/v1/chat/runs` with SSE assistant deltas and per-job progress. - Utilities: `--list-api-models`, `--get-api-model `, `--task-profile general|coding|reasoning`, `--max-tokens `, `--thinking` / `--no-thinking`, `--list-replays [n]`, `--get-replay `, `--ingest-replay `. - Live Supernet media models: `--list-models [query]` or `--search-models `, optionally with `--model-media image|video|audio|all`, `--model-network fast|relaxed`, and repeatable `--model-tag ` filters such as `spicy` or `uncensored`, plus `--json`. Availability comes from `sogni-client` and tags from the official Sogni catalog; `--list-api-models` lists language models instead. - Media references from `-c`, `--ref`, `--ref-end`, `--keyframe`, `--ref-audio`, `--reference-audio-identity`, `--ref-video`, and `--mask` are uploaded and forwarded as `media_references`; API chat also attaches image refs as vision inputs. Workflow JSON can bind refs with `sourceStepId: "$input_media"`. - Direct Krea IDs: use `-m krea2_turbo_fp8_scaled` for Krea 2 Turbo images, `-m dark_beast_krea2_fp8` for Dark Beast Krea 2 images, and `-c -m krea2_identity_edit_v1_2` or `-c -m dark_beast_krea2_identity_edit_v1_2` for identity-preserving Krea edits with 1-2 references, 512-2048 px output, 8-12 steps, and guidance 1. - Edit-model routing: Krea 2 Identity Edit for a person's likeness (the `-c` default for 1-2 references), FLUX 3 Image Klein for type and graphic design (the default for 3-10), Dark Beast Krea 2 Identity Edit for NSFW, and `gpt-image-2.5-sunburst` for the best result with Premium Spark. Qwen Image Edit is an older model: never a default, only when the user names it. - FLUX 3 Image Klein: `-m flux3_image_klein_sd_int8_convrot` for text-to-image, or add up to ten `-c ` references for edits (references optional); 256-4096 px (4K included for prompts and several references), 4-16 steps (default 16), guidance fixed at 1, no negative prompt. A one-photo edit renders at the photo's shape up to 4 MP (picked automatically, larger sizes capped). Personal Klein LoRAs work; no nudity (use Dark Beast Krea 2). Hosted selector: `flux-3-klein`. - Seedream 5.0 Pro Uncensored, only when asked: `-m seedream-5-0-pro-uncensored` (also "Seedream 5 Pro Uncensored", "Seedream Uncensored") for text-to-image, or add up to ten `-c ` references for edits; 921,600-4,194,304 pixels up to 16:1 (default 1536x1536); Premium Spark only; shares the Seedance 2.5 Uncensored likeness agreement (error 4103 until accepted in the Sogni app). - Cost policy: `--workflow-max-cost`, `--confirm-cost`, `--no-confirm-cost`. - JSON errors include canonical `errorType`, `errorCategory`, and `retryable`. ## Sogni Unlimited subscription Sogni Unlimited is a flat-rate subscription that covers Sogni-hosted (Supernet) image, video, and music generation under a fair-use policy instead of spending Spark or SOGNI per render. Plans: Unlimited ($20/mo, $199/yr) and Unlimited Pro ($50/mo, $498/yr), with a one-per-account 3-day free trial (trial usage is capped). External-vendor models — GPT Image 2 (`gpt-image-2`), Seedance 2.0 / Mini / Fast / 2.5 (`seedance-2-0`, `seedance-2-0-mini`, `seedance-2-0-fast`, `seedance-2-5`), HappyHorse 1.1 (`happyhorse-1.1-t2v`, `happyhorse-1.1-i2v`, `happyhorse-1.1-r2v`), and Wan 3 (`wan3.0-video`) — are never covered and always need Premium Spark; selecting SOGNI opts a job out of coverage. The server decides coverage from the verified entitlement + resolved model; the CLI never asserts coverage. Never infer a Spark charge from `tokenType: "spark"`: that field is the quote/accounting denomination and can remain `spark` on a covered job. `paymentModel: "subscription"` is the authoritative indication that the artist debit was skipped. If `paymentModel` is absent, call the payment source unknown instead of claiming Spark was spent. A successful `--billing-mode subscription` request is covered; unavailable coverage fails with 4078 or 4080 rather than silently falling back to Spark. Describe only the concurrency and queue limits shown in the current plan catalog. Actual throughput varies with demand, available Supernet capacity, and fair-use controls; do not speculate about unpublished scheduling mechanics or availability windows, and never call the plan "relaxed". Subscription-billing failures use `errorCategory: "subscription_billing"` with `errorCode` 4078 (vendor/no-entitlement -> use Premium Spark or reconnect), 4079 (queue cap -> wait), 4080 (renewal retry, access paused -> pay with Spark/SOGNI, do NOT auto-retry the covered job), 4081 (higher plan -> upgrade to Pro), or 4087 and 4089 (Fast capacity used up for the day or month -> offer `--network relaxed`, Premium Spark with `--billing-mode tokens`, or waiting for the reset; do NOT retry on Fast). Paid cancellation keeps access until period end; cancelling during the trial ends access immediately. ## Repo Sogni-AI/sogni-creative-agent-skill ## Key files - `SKILL.md` — agent behavior and usage rules (load this into your agent) - `references/` — deep-dive guides SKILL.md points at (video prompting, hosted API, models, personas, video editing) - `openclaw.plugin.json` — OpenClaw plugin manifest and config schema - `sogni-agent.mjs` — CLI used by the skill (`sogni-agent --help` is canonical) Priority Fast: direct renders support explicit --priority on paid Unlimited worker jobs. Explain 1.5x daily/monthly fair-use consumption and obtain the user’s choice first. --network fast|relaxed chooses the worker pool. Hosted modes do not accept these flags. GPT Image 2.6 GIFs, planning complexity and annotation PNGs are documented in references/models.md.