@sogni-ai/sogni-creative-agent-skill/llm.txt

Sogni Creative Agent Skill: agent skill and CLI for Sogni AI image, 3D, speech, video, and music generation.

# 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 <model> --mode <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 <id>`,
  `--task-profile general|coding|reasoning`, `--max-tokens <n>`,
  `--thinking` / `--no-thinking`, `--list-replays [n]`, `--get-replay <id>`,
  `--ingest-replay <json|@path>`.
- Live Supernet media models: `--list-models [query]` or
  `--search-models <query>`, optionally with
  `--model-media image|video|audio|all`, `--model-network fast|relaxed`, and
  repeatable `--model-tag <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 <image> -m krea2_identity_edit_v1_2` or
  `-c <image> -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 <image>` 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 <image>` 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.