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

Sogni Creative Agent Skill: agent skill and CLI for Sogni AI image, 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, Hermes Agent, OpenClaw,
Manus AI, and other SKILL.md-aware agent runtimes.

## 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

# Print ChatGPT Custom-GPT instructions explicitly.
npx setup-sogni-agent-skill --only=chatgpt

# 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 --only=codex

# Hermes Agent (start Hermes once first so ~/.hermes/ exists), then /reset the
# Hermes session
npx setup-sogni-agent-skill --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

# 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-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. The API key can always be
found by logging into https://dashboard.sogni.ai and opening the account menu.

```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`.

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`, `--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.
- 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`), and HappyHorse 1.1 (`happyhorse-1.1-t2v`, `happyhorse-1.1-i2v`,
`happyhorse-1.1-r2v`) — 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), or 4081 (higher plan -> upgrade to Pro). 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)