@sogni-ai/sogni-creative-agent-skill
Version:
Sogni Creative Agent Skill: agent skill and CLI for Sogni AI image, 3D, speech, video, and music generation.
1,174 lines • 90.9 kB
Markdown
<p align="center">
<img src="https://raw.githubusercontent.com/Sogni-AI/sogni-creative-agent-skill/main/docs/banner.jpg" alt="Sogni Creative Agent: image, video, and music generation for AI agents. A small robot on a rooftop at dusk paints the sky with a brushstroke of paintings, film, and music above a town of glowing windows." width="100%" />
</p>
<h1 align="center">Sogni Creative Agent Skill</h1>
<p align="center">Image, video, and music generation for AI agents — powered by <a href="https://sogni.ai">Sogni AI</a>'s decentralized GPU network.</p>
<p align="center">
<a href="https://www.npmjs.com/package/@sogni-ai/sogni-creative-agent-skill"><img alt="npm" src="https://img.shields.io/npm/v/@sogni-ai/sogni-creative-agent-skill.svg" /></a>
<a href="https://www.npmjs.com/package/@sogni-ai/sogni-creative-agent-skill"><img alt="downloads" src="https://img.shields.io/npm/dm/@sogni-ai/sogni-creative-agent-skill.svg" /></a>
<img alt="node" src="https://img.shields.io/node/v/@sogni-ai/sogni-creative-agent-skill.svg" />
<a href="./LICENSE"><img alt="license" src="https://img.shields.io/npm/l/@sogni-ai/sogni-creative-agent-skill.svg" /></a>
</p>
---
**Sogni Creative Agent Skill** plugs into the agent runtime you already use — Claude Code, [goose](https://goose-docs.ai/), [OpenClaw](https://github.com/OpenClaw/OpenClaw), [Hermes Agent](https://hermes-agent.nousresearch.com/), [Manus AI](https://manus.im), and others — and gives it production-quality image, video, and music generation through a single CLI: `sogni-agent`.
It ships four ways:
- a standalone Node.js CLI (`sogni-agent`)
- a skill source that any [`SKILL.md`](./SKILL.md)-aware agent can load
- a local MCP stdio server (`sogni-agent-mcp`) for goose, Claude Desktop, Codex, and other MCP clients
- a published [OpenClaw](https://github.com/OpenClaw/OpenClaw) plugin
With this skill, an agent can:
- generate with MOSS-Image SFT from captions, tags, or JSON layouts (`-m moss_image_sft_int8_convrot`), or the 8-step preset (`-m moss_image_sft_dmd8_int8_convrot`); both accept compatible Personal LoRAs. Optional `--moss-rope-scale-x` and `--moss-rope-scale-y` adjust spatial composition (0–100; neutral 1) while preserving output dimensions. See the [model recipes](./references/models.md).
- generate images from prompts and edit/restyle existing images
- select an object in an original image and return its SAM 3 mask (`--segment`; see the [object selection guide](references/object-selection.md))
- track an object across a video and return a frame-aligned mask (`--segment-video`; see the [object selection guide](references/object-selection.md))
- create videos from text, images, first/last frames, audio, or source video (LTX-2.5), with LTX-2.3 retained for voice ID, transition, and 10Eros workflows
- turn an image folder into a visually deduplicated, music-backed seamless loop with one plugin skill invocation
- generate instrumental music or full songs with lyrics
- run hosted creative workflows including storyboard-driven video
- build a playable, click-through world (places, crossing films, narration, music, 3D collectibles) with the open-source [Sogni Worlds Kit](https://github.com/Sogni-AI/sogni-worlds-kit), which uses the same Sogni API key
- save personas, preferences, and last-render state across sessions
- check balances, list models, and refine previous results
<p align="center">
<img src="https://raw.githubusercontent.com/Sogni-AI/sogni-creative-agent-skill/main/docs/screenshot.jpg" alt="Sogni Creative Agent Skill rendering an image from a Telegram-style chat" width="320" />
</p>
> **Fastest install:** paste this repo's GitHub URL into your agent and ask it to "install this skill".
---
## Table of Contents
- [Connecting with MCP](#connecting-with-mcp)
- [Quick Start](#quick-start)
- [Requirements](#requirements)
- [Installation](#installation)
- [Node CLI (default)](#node-cli-default)
- [Claude Code plugin](#claude-code-plugin)
- [OpenAI Codex CLI](#openai-codex-cli)
- [Hermes Agent](#hermes-agent)
- [goose](#goose)
- [OpenClaw plugin](#openclaw-plugin)
- [ChatGPT (Custom GPT)](#chatgpt-custom-gpt)
- [Manus / other SKILL.md frameworks](#manus--other-skillmd-frameworks)
- [Manual install from source](#manual-install-from-source)
- [Host launchers](#host-launchers)
- [Verify your install](#verify-your-install)
- [Upgrading safely from inside an agent](#upgrading-safely-from-inside-an-agent)
- [Claude Desktop](#claude-desktop)
- [Also works in OpenAI Codex](#also-works-in-openai-codex)
- [Setup (Sogni API key)](#setup-sogni-api-key)
- [Usage](#usage)
- [CLI Reference](#cli-reference)
- [Common options](#common-options)
- [Quality presets](#quality-presets)
- [Recommended models](#recommended-models)
- [Video Sizing & Aspect Ratios](#video-sizing--aspect-ratios)
- [LTX-2.x Prompting Guide](#ltx-2x-prompting-guide)
- [Photobooth (Face Transfer)](#photobooth-face-transfer)
- [Personas, Memory, and Personality](#personas-memory-and-personality)
- [Hosted API Modes](#hosted-api-modes)
- [Dynamic Prompt Variations](#dynamic-prompt-variations)
- [Token Auto-Fallback](#token-auto-fallback)
- [Sogni Unlimited Subscription](#sogni-unlimited-subscription)
- [Error Reporting & Output](#error-reporting--output)
- [For AI Agents](#for-ai-agents)
- [Development](#development)
- [License](#license)
---
## Connecting with MCP
The skill includes a **local MCP server**, `sogni-agent-mcp`, which runs the
installed CLI on your computer. Use it when your MCP client needs local media,
saved personas and memories, or video editing with ffmpeg. See the
[Claude Desktop](#claude-desktop), [Codex](#also-works-in-openai-codex) and [Goose](#goose)
instructions for local setup.
Sogni also documents a separate **hosted MCP** integration for remote clients
that support Streamable HTTP and Bearer-token authentication. Check the
[MCP connection guide](https://docs.sogni.ai/agents/mcp/) for its current
availability and configuration. Hosted tools do not require this skill or CLI,
but they cannot read your local files or use your saved local personas and
memories. References must be uploaded; a local path is not a hosted asset.
MCP exposes callable tools. This skill supplies creative instructions and local
workflows; the [Worlds Kit](https://github.com/Sogni-AI/sogni-worlds-kit) supplies
the world-building pipeline and player. Connecting a hosted server does not
install either. Existing CLI and local MCP users can keep their setup and their
account's normal billing, including eligible Unlimited coverage.
## Quick Start
1. Get a Sogni API key from [the API Keys page](https://dashboard.sogni.ai/api-key) and save it — see [Setup](#setup-sogni-api-key).
2. Install (one command):
```bash
npx setup-sogni-agent-skill --version=latest
```
This auto-detects Claude Code, OpenAI Codex CLI, and Hermes Agent; installs the
CLI globally; registers the skill into each detected runtime; prompts for your
API key; and tells you how to request ChatGPT Custom-GPT setup instructions.
(It does **not** configure OpenClaw — see the [OpenClaw plugin](#openclaw-plugin)
section.)
Prefer to do it manually? Install the CLI directly:
```bash
npm install -g @sogni-ai/sogni-creative-agent-skill@latest
sogni-agent --version
```
Then point your agent runtime at this repository's [`SKILL.md`](./SKILL.md).
3. Verify the install:
```bash
sogni-agent doctor
```
Then ask your agent to do something:
- "Generate an image of a sunset over mountains"
- "Edit this image to add a rainbow"
- "Use Sogni Loop Maker on my image folder"
- "Make a video of a cat playing piano"
- "Generate a 30 second synthwave product-launch theme"
- "Turn my selfie into James Bond using photobooth"
- "Refine the last image at higher quality"
---
## Requirements
- **Node.js ≥ 22.11.0**
- **Sogni API key** ([API Keys page](https://dashboard.sogni.ai/api-key))
- **`ffmpeg` + `ffprobe`** *(optional)* — required for local utilities such as `--angles-360-video`, `--concat-videos`, timestamped frame extraction, and `--verify-video`; `--upscale-video` needs `ffprobe`. Set `FFMPEG_PATH` / `FFPROBE_PATH` to override discovery (a leading `~` is expanded).
- macOS, Linux, or Windows
---
## Installation
### Node CLI (default)
For most agents and human users:
```bash
npm install -g @sogni-ai/sogni-creative-agent-skill@latest
sogni-agent --version
```
Then point your agent/runtime at this repository's [`SKILL.md`](./SKILL.md). When an install request is ambiguous, install the CLI and skill source together — that's the supported default.
### Claude Code plugin
The Claude Code plugin shells out to the `sogni-agent` CLI installed above, so both steps are required. From inside Claude Code, register the marketplace and install the plugin:
```text
/plugin marketplace add Sogni-AI/sogni-creative-agent-skill
/plugin install sogni-creative-agent@sogni
```
The first command registers a `sogni` marketplace with one plugin entry (`sogni-creative-agent`) backed by a lean Claude-Code-focused [`plugin-skills/sogni-creative-agent/SKILL.md`](./plugin-skills/sogni-creative-agent/SKILL.md); the second installs the plugin into Claude Code. The full skill spec still lives at the repository root [`SKILL.md`](./SKILL.md).
The plugin invokes the local CLI with your Sogni credentials. Network generation
sends your prompt, settings and selected reference media to Sogni for processing;
results can be downloaded to your computer. Personas and memories use local
files, and selected persona references may be sent with a generation request.
See Sogni's [privacy policy](https://www.sogni.ai/privacy-policy) and
[support page](https://www.sogni.ai/contact).
> **Pick one registration per machine.** Install either this plugin **or** the personal skill that `npx setup-sogni-agent-skill --version=latest` writes to `~/.claude/skills/` — not both. With both installed, Claude Code lists two near-identical skills, which wastes context and makes skill selection ambiguous.
### OpenAI Codex CLI
For the namespaced Sogni skills, register the marketplace and install the plugin:
```bash
codex plugin marketplace add Sogni-AI/sogni-creative-agent-skill
codex plugin add sogni-creative-agent@sogni
```
Start a new Codex session, then invoke Loop Maker directly:
```text
$sogni-creative-agent:loop-maker ./images
```
In the Codex app, type `@`, choose **Sogni Loop Maker**, and select its starter prompt.
For local development, replace the GitHub shorthand in `codex plugin marketplace add` with the absolute path to this repository.
Alternatively, the `npx` installer writes the full monolithic skill to `~/.codex/skills/sogni-creative-agent-skill/`, which Codex discovers automatically:
```bash
npx setup-sogni-agent-skill --version=latest --only=codex
```
Start Codex once before running the installer so `~/.codex/` exists. If the selected local runtime is not detected, setup exits before installing anything.
Restart Codex (or start a new session) and ask it to "generate an image of a sunset" — the skill shells out to the globally installed `sogni-agent`. To remove this personal-skill install later: `npx setup-sogni-agent-skill --uninstall --only=codex`.
### Hermes Agent
[Hermes Agent](https://hermes-agent.nousresearch.com/) can install the dedicated,
security-scannable bundle directly from its Skills Hub (via skills.sh):
```bash
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
sogni-agent-hermes doctor
```
Then `/reset` the Hermes session so it picks up the new skill. The Hub bundle
lives at
[`.agents/skills/sogni-creative-agent-skill/`](./.agents/skills/sogni-creative-agent-skill/)
and contains only the agent instructions and the references they load, keeping
the CLI runtime and development files outside Hermes' skill security scan.
For a combined CLI + personal-skill setup, the `npx` installer still places the
skill at `~/.hermes/skills/media/sogni-creative-agent-skill/`:
```bash
npx setup-sogni-agent-skill --version=latest --only=hermes
```
Start Hermes once before running the installer so `~/.hermes/` exists. If the
selected local runtime is not detected, setup exits before installing anything.
### goose
[goose](https://goose-docs.ai/) supports both Agent Skills and MCP extensions. Pick one integration per installation so goose does not receive duplicate Sogni instructions and tools.
To install the skill globally:
```bash
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
sogni-agent-goose doctor
```
The skill is discovered from goose's global skill directories and uses the `sogni-agent-goose` launcher for host attribution.
To run the MCP extension directly instead:
```bash
goose session --with-extension "npx -y --package @sogni-ai/sogni-creative-agent-skill@latest sogni-agent-mcp"
```
The same command can be added permanently from `goose configure` as a Command-line Extension. Once the public listing is accepted, it can also be installed from the [goose Extensions directory](https://goose-docs.ai/extensions/). The MCP package is self-contained; it reads `SOGNI_API_KEY` from the extension environment or the existing `~/.config/sogni/credentials` file.
### OpenClaw plugin
The skill is published on ClawHub by the `sogni-ai` publisher. Specify the publisher because more than one listing uses this skill name:
```bash
npx -y clawhub@latest install @sogni-ai/sogni-creative-agent-skill
```
Through 3.54.2 the listing was `@fishmongr/sogni-creative-agent-skill`. ClawHub no longer finds that name, so an install made from it does not update; install again with the command above.
To install as a code plugin instead, use OpenClaw's `npm:` source prefix (the npm package is scoped, so a bare `openclaw plugins install sogni-creative-agent-skill` will not resolve it):
```bash
openclaw plugins install npm:@sogni-ai/sogni-creative-agent-skill
```
The installed plugin loads its behavior from [`SKILL.md`](./SKILL.md) via [`openclaw.plugin.json`](./openclaw.plugin.json). The `npx setup-sogni-agent-skill --version=latest` installer does **not** configure OpenClaw — use the command above (or the local-link flow below) instead.
> **API key under OpenClaw:** the plugin config holds non-secret defaults only (models, timeouts, paths) — it does **not** carry your API key. Provide `SOGNI_API_KEY` via the environment the OpenClaw gateway passes to the CLI, or save it to `~/.config/sogni/credentials` (`SOGNI_API_KEY=<your-key>`). This keeps your key out of plugin config files.
For a local checkout that you want to update continuously, link the minimal OpenClaw surface (`.openclaw-link/`) — not the repository root, which contains development tests that OpenClaw correctly blocks during plugin safety scanning:
```bash
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
```
To update the linked install later:
```bash
cd /path/to/sogni-creative-agent-skill
git pull --ff-only
npm install
npm link
npm run openclaw:sync
openclaw gateway restart
```
The generated `.openclaw-link/` directory is only for OpenClaw; Hermes, Manus, and other skill-based agents should continue using the root [`SKILL.md`](./SKILL.md).
#### OpenClaw configuration
When loaded through OpenClaw, this skill reads plugin defaults from OpenClaw config; CLI flags always override them. The supported config schema is defined in [`openclaw.plugin.json`](./openclaw.plugin.json) and includes default models, video workflow models, hosted API defaults (`apiBaseUrl`, `defaultLlmModel`, `defaultTaskProfile`, `defaultApiMaxTokens`, `defaultApiThinking`, `defaultApiToolMode`, workflow cost defaults), token type, seed strategy, timeouts, and media paths. If your OpenClaw config lives elsewhere, set `OPENCLAW_CONFIG_PATH`.
### ChatGPT (Custom GPT)
Run `npx setup-sogni-agent-skill --only=chatgpt --version=latest` to print step-by-step instructions for creating a ChatGPT Custom GPT whose Instructions embed this skill. Note that ChatGPT cannot run the local CLI; the Custom GPT path covers prompt-side behavior only.
### Manus / other SKILL.md frameworks
Point the agent at this repository's [`SKILL.md`](./SKILL.md) for behavior guidance and [`llm.txt`](https://raw.githubusercontent.com/Sogni-AI/sogni-creative-agent-skill/main/llm.txt) for install/setup help. The agent should invoke the globally installed `sogni-agent` CLI by default.
### Manual install from source
```bash
gh repo clone Sogni-AI/sogni-creative-agent-skill
cd sogni-creative-agent-skill
npm install
```
### Host launchers
The package installs one launcher shim per host alongside `sogni-agent`. Each shim is the same CLI with the same flags and output — it only tags the request with the agent framework that ran it, so Sogni can tell a Codex render from a Claude Code render:
| Host | Command | Reported framework |
| --- | --- | --- |
| Hermes | `sogni-agent-hermes` | `hermes-agent` |
| goose | `sogni-agent-goose` | `goose` |
| OpenAI Codex CLI | `sogni-agent-codex` | `codex` |
| Claude Code | `sogni-agent-claude-code` | `claude-code` |
| OpenClaw | `sogni-agent` | `openclaw` (detected from `OPENCLAW_PLUGIN_CONFIG`) |
| Anything else | `sogni-agent` | `unknown` |
The Claude Code and Codex plugin surfaces already pin their launcher, and OpenClaw is detected automatically. Goose and Hermes skill installs should use their matching launchers wherever the docs say `sogni-agent`. Everything works normally through bare `sogni-agent` — the render is just attributed to `unknown`. Falling back to `sogni-agent` is always safe if a shim is not on `PATH`.
### Verify your install
Every install path above ends the same way — run the built-in health check:
```bash
sogni-agent doctor
```
It verifies the Node version, API credentials (and their file permissions), config-dir writability, `ffmpeg` availability, live authentication, and whether a newer version is available. `sogni-agent doctor --json` emits the same checks for agents. If anything is marked `✗`, the detail line says exactly how to fix it.
### Upgrading safely from inside an agent
When upgrading from inside an agent runtime, prefer direct package-manager or existing-checkout commands. Avoid asking the agent to build a clone-or-pull shell bootstrap script with `set -e`, `bash -c`, `sh -c`, or an inline repository URL — some sandboxes correctly route those through approval and the install will stall.
For a global CLI:
```bash
npm install -g @sogni-ai/sogni-creative-agent-skill@latest
sogni-agent --version
```
For an existing local checkout:
```bash
DEST="$HOME/Documents/git/sogni/sogni-creative-agent-skill"
git -C "$DEST" pull --ff-only
npm --prefix "$DEST" install
```
If the checkout is missing, use the npm install path above or explicitly approve a clone.
---
## Claude Desktop
Claude Desktop can't run skills against your local files, so Sogni ships as a local MCP server instead. Two ways to install:
**Recommended — one command (also installs the CLI, saves your API key, and offers to install ffmpeg):**
npx setup-sogni-agent-skill --version=latest
This registers the Sogni tools in `claude_desktop_config.json`. Fully quit and reopen Claude Desktop afterwards. Generated images display inline in the chat automatically.
**Manual — drag-and-drop bundle:** download `sogni-creative-agent.mcpb` from the GitHub Releases page and drop it onto Claude Desktop's Settings → Extensions page. You'll be prompted for your Sogni API key (stored in the OS keychain) unless you've already run the installer.
Don't use both — you'd get duplicate Sogni tools. The extension wraps the same globally installed `sogni-agent` CLI used by Claude Code, so personas, memories, and credentials are shared.
Video/audio editing features need ffmpeg on your machine; the `npx` installer offers to install it for you.
### Also works in OpenAI Codex
The same local MCP server runs in OpenAI Codex — the Codex CLI and IDE extension read MCP servers from `~/.codex/config.toml`. With the CLI installed globally (`npm i -g @sogni-ai/sogni-creative-agent-skill`), register it and start a new Codex session:
```bash
codex mcp add sogni-creative-agent -- node "$(npm root -g)/@sogni-ai/sogni-creative-agent-skill/desktop-extension/server/index.mjs"
```
Or write the `~/.codex/config.toml` entry yourself (use the absolute path from `npm root -g`):
```toml
[mcp_servers.sogni-creative-agent]
command = "node"
args = ["/opt/homebrew/lib/node_modules/@sogni-ai/sogni-creative-agent-skill/desktop-extension/server/index.mjs"]
```
Codex also runs the Skill natively (see [OpenAI Codex CLI](#openai-codex-cli)) — pick one integration per machine; running both gives Codex duplicate Sogni tools. The server finds your globally installed `sogni-agent`, ffmpeg, and saved credentials on its own, so no `env` block is needed.
---
## Setup (Sogni API key)
1. Get your API key from [the API Keys page](https://dashboard.sogni.ai/api-key).
2. Save it to a credentials file:
```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 skip the file and export `SOGNI_API_KEY` in your environment.
### Filesystem path overrides
Defaults live under `~/.config/sogni/` for credentials, last-render metadata, personas, memories, and personality.
**Running several agents at once** (Claude Code, Codex, OpenCode, hermes, ...) works out of the box: each process leases its own stable app ID from a persistent slot pool in `~/.config/sogni/app-ids/`, so concurrent runs never fight over one socket identity (SWITCH_CONNECTION 4015) and routine runs do not create unnecessary IDs (error 4061). Leases are released on exit and reclaimed automatically if a process dies. Long-lived daemons should pin their own `SOGNI_APP_ID` to stay out of the shared pool, and each harness can set its own `SOGNI_LAST_RENDER_PATH` so `--last` stays per-tool. Override individual paths with:
| Variable | Purpose |
|----------|---------|
| `SOGNI_CREDENTIALS_PATH` | Custom credentials file |
| `SOGNI_APP_ID` | Pinned app ID (ephemeral/container homes and long-lived daemons; skips the pool) |
| `SOGNI_APP_ID_PATH` | Legacy single app-ID file mode for callers that manage their own concurrency |
| `SOGNI_APP_ID_POOL_DIR` | Persistent app-ID slot pool for concurrent agents (default: `~/.config/sogni/app-ids/`) |
| `SOGNI_APP_ID_POOL_MAX` | Maximum concurrent app-ID slots (default: 32) |
| `SOGNI_LAST_RENDER_PATH` | Where last-render state is persisted; give each agent harness its own file so `--last` never reads another tool's render |
| `SOGNI_MODEL_CATALOG_URL` | Model catalog API base URL (default: `https://api.sogni.ai/v1/model-catalog`) |
| `SOGNI_MODEL_CATALOG_CACHE_PATH` | Base path for the five-minute model catalog caches and ETags |
| `SOGNI_MEDIA_INBOUND_DIR` | Directory used by `--list-media` |
| `OPENCLAW_CONFIG_PATH` | OpenClaw config file location |
| `FFMPEG_PATH` | Custom `ffmpeg` binary |
---
## Usage
Claude Code plugin users can launch the complete folder-to-loop workflow with one skill invocation:
```text
/sogni-creative-agent:loop-maker ./images
/sogni-creative-agent:loop-maker ./images start=cover.jpg music="subtle tropical cyberpunk electronica" output=launch-loop.mp4
```
Codex CLI and IDE users can invoke the same bundled skill with `$`:
```text
$sogni-creative-agent:loop-maker ./images
$sogni-creative-agent:loop-maker ./images start=cover.jpg music="subtle tropical cyberpunk electronica" output=launch-loop.mp4
```
The skill visually removes repeated concepts from the active sequence, renders one direct LTX first-frame/last-frame clip per image pair, closes the loop, generates a soundtrack longer than the picture, and verifies anchors, interior motion, streams, and full-file decoding before delivery. Original source images are preserved. The default stack is Sogni plus the bundled FFmpeg wrappers; HyperFrames and Remotion are optional only for explicitly requested text, overlays, or compositor effects. True 360 novel-view synthesis is deliberately excluded from this workflow because a direct single-image LTX prompt does not reliably create camera orbit geometry.
Image output supports `--output-format png`, `jpg`, or `webp`. For worker images,
`--no-prompt-metadata` omits embedded prompt and generation settings. JSON output
includes per-image `results` with `nsfwDetected` and `nsfwSources`; a label alone
does not mean the optional content filter withheld the image.
```bash
# Image generation
sogni-agent -Q hq -o dragon.png "a dragon eating tacos"
# Edit an image (a person: Krea 2 Identity Edit, the default; type or design: FLUX 3 Image Klein)
sogni-agent -c subject.jpg "add a neon cyberpunk glow"
sogni-agent -c poster.png -m flux3_image_klein_sd_int8_convrot "the headline now reads GRAND OPENING"
# Photobooth face transfer
sogni-agent --photobooth --ref face.jpg "80s fashion portrait"
# Text-to-video (t2v) with native dialogue
sogni-agent --video 'A narrator says "welcome to the story" as ocean waves crash'
# Short-side resolution targeting (preserves the inherited aspect ratio)
sogni-agent --video --target-resolution 768 \
"A calm cinematic shot of lanterns drifting across a night lake"
# Seedance 2.0 4K (4-15s vendor video path with native audio)
sogni-agent --video -m seedance2 --target-resolution 2160 --duration 8 \
"A polished product reveal with native ambient sound"
# Seedance multimodal context with public HTTPS references (-c for the image: loose
# references cannot be combined with --ref/--ref-end frame anchors)
sogni-agent --video -m seedance2 --workflow t2v \
-c https://cdn.example.com/product.png \
--ref-video https://cdn.example.com/motion.mp4 \
--ref-audio https://cdn.example.com/music.m4a \
"Use @Image1 for product identity, @Video1 for camera movement, and @Audio1 for music rhythm"
# Alibaba Wan 3 unified video (2-30s, fixed 30fps, native audio, 480P/720P/1080P; 720P by default)
sogni-agent --video -m wan3 --target-resolution 1080 --duration 8 \
'A presenter walks through a detailed studio and says "Welcome."'
sogni-agent --video -m wan3 --ref first.png --ref-end last.png \
"Move smoothly between the supplied endpoint frames"
sogni-agent --video -m wan3 --workflow ia2v --ref presenter.png --ref-audio dialogue.mp3 \
"Use Image 1 for the presenter and Audio 1 for the performance"
sogni-agent --video -m wan3 --workflow r2v --ref-video motion.mp4 \
"Use Video 1 as loose motion and pacing guidance for a new rainy-night scene"
sogni-agent --video -m wan3 --smart-duration --wan3-ratio 9:16 --no-expand-prompt \
--reference-file-url https://cdn.example.com/brief.pdf \
"Use the supplied brief exactly"
# Seedance 2.5 Uncensored: every Seedance 2.5 mode and limit under its own model.
# Accept its one-time likeness and consent agreement in the Sogni app first
# (until then jobs fail with error 4103, which is not retryable).
sogni-agent --video -m seedance2-5-uncensored --target-resolution 1080 --duration 8 \
"A low camera circles two dancers spinning through a packed neon club, the crowd and strobe lights streaking past the lens. 0-3s: they lock hands and whip into a tight turn, her sequined dress and his loose shirt flaring out as the dancers around them throw their arms up. 3-6s: the taller dancer dips her partner low to the floor while the camera swings around them, magenta and blue light washing across their faces and sweat glinting on their shoulders. 6-8s: they snap upright together on the bass drop, chests heaving and grinning, as the crowd surges in behind them. Pounding bass, the crowd cheering, heels striking the floor. Both dancers keep the same faces, outfits and hair from the first frame to the last."
# Seedance 2.0 Mini Uncensored: every Seedance 2.0 Mini mode and limit (480p/720p,
# 4-15s) under its own model. It shares the Seedance 2.5 Uncensored agreement.
sogni-agent --video -m seedance2-mini-uncensored --target-resolution 720 --duration 8 \
"A slow dolly glides down a rain-soaked neon street at night at chest height, the wet asphalt mirroring pink and blue signs. 0-3s: a lone cyclist in a yellow raincoat rolls through the frame from left to right, tires hissing through a wide puddle and scattering the reflections. 3-6s: steam curls up from a street grate as a shop shutter on the right rattles down to the pavement. 6-8s: the dolly comes to rest on a glowing noodle-bar window where a cook tosses noodles in a smoking wok. Steady rain patter on awnings, distant traffic, the shutter's metal clatter. The street stays empty apart from the cyclist and the cook."
# Wan 3.0 Enhanced through MuleRouter (smart/fixed 2-30s, 30fps, native audio)
sogni-agent --video -m wan3-enhanced --target-resolution 1080 --duration 8 \
--wan3-ratio 16:9 'A presenter says "Welcome." in a detailed studio'
sogni-agent --video -m wan3-enhanced --workflow i2v --ref first.png --ref-end last.png \
-c wardrobe.png "Keep the endpoint frames and use Image 1 for wardrobe detail"
# MiniMax R2V default: Balanced (minimax-h3-r2v-balanced); other tiers only when requested.
# MiniMax H3 Standard, 8-step Balanced, 4-step LightX2V Turbo, FastH3 Turbo, FastH3 Reference, and FastH3 and Ref2VA Two-Stage (1080p/2K) video
sogni-agent --video -m minimax-h3 --duration 10 "<three-field H3 prompt>"
sogni-agent --video -m minimax-h3-i2v --ref first.png --duration 8 "<I2V preamble plus three-field H3 prompt>"
sogni-agent --video -m minimax-h3-r2v-balanced --ref identity.png -c wardrobe.png \
--ref-video motion.mp4 --ref-audio voice.m4a \
"<six-field Ref2VA prompt>"
sogni-agent --video -m minimax-h3-balanced --duration 8 "<three-field H3 prompt>"
sogni-agent --video -m minimax-h3-flf2v-balanced --ref first.png --ref-end last.png --duration 8 "<FLF2V preamble plus three-field H3 prompt>"
sogni-agent --video -m minimax-h3-turbo --duration 8 "<three-field H3 prompt>"
sogni-agent --video -m minimax-h3-turbo --sampler sa_solver --duration 8 "<A/B variant of the same H3 prompt>"
sogni-agent --video -m minimax-h3-flf2v-turbo --ref first.png --ref-end last.png --duration 8 "<FLF2V preamble plus three-field H3 prompt>"
sogni-agent --video -m minimax-h3-fasth3-turbo --duration 8 "<three-field H3 prompt>"
sogni-agent --video -m minimax-h3-fasth3-i2v-turbo --ref first.png --duration 8 "<I2V preamble plus three-field H3 prompt>"
sogni-agent --video -m minimax-h3-fasth3-flf2v-turbo --ref first.png --ref-end last.png --duration 8 "<FLF2V preamble plus three-field H3 prompt>"
sogni-agent --video -m minimax-h3-fasth3-turbo-2stage --duration 8 "<three-field H3 prompt>" # 2K: FastH3 Two-Stage, delivered at 2x the canvas
sogni-agent --video -m minimax-h3-fasth3-turbo-2stage --target-resolution 1080 --duration 8 "<three-field H3 prompt>" # 1080p: 960x544 delivered at 1920x1088
sogni-agent --video -m minimax-h3-r2v-2stage --ref identity.png -c wardrobe.png "<six-field Ref2VA prompt>" # 2K Ref2VA Two-Stage (20 steps)
sogni-agent --video -m minimax-h3-r2v-balanced-2stage --target-resolution 1080 --ref identity.png "<six-field Ref2VA prompt>" # 1080p Balanced Ref2VA Two-Stage (8 steps)
sogni-agent --video -m minimax-h3-fasth3-r2v-turbo --ref identity.png -c wardrobe.png "<six-field Ref2VA prompt>" # FastH3 Reference
sogni-agent --video -m minimax-h3-fasth3-r2v-turbo-2stage --target-resolution 1080 --ref identity.png "<six-field Ref2VA prompt>" # 1080p FastH3 Reference Two-Stage
# MiniMax H3 FastH3 audio-to-video: your voice or song drives the clip and is its soundtrack
sogni-agent --video -m minimax-h3-fasth3-ia2v-turbo --ref portrait.png --ref-audio voice.m4a --duration 8 "<I2V preamble plus three-field H3 prompt>"
sogni-agent --video -m minimax-h3-fasth3-flfa2v-turbo --ref first.png --ref-end last.png --ref-audio song.mp3 --duration 12 "<FLF2V preamble plus three-field H3 prompt>"
sogni-agent --video -m minimax-h3-fasth3-a2v-turbo --ref-audio song.mp3 --audio-start 30 --duration 15 "<three-field H3 prompt>"
# MiniMax H3 keyframes: the clip passes through extra images at chosen times (repeat --keyframe, up to 8)
sogni-agent --video -m minimax-h3-fasth3-flf2v-turbo --ref first.png --ref-end last.png \
--keyframe turn.png@3.5 --keyframe wave.png@6 --duration 8 \
"<keyframe alignment line plus three-field H3 prompt that names each keyframe <Picture N> and describes it at its time>"
# Image-to-video (i2v; defaults to wan_v2.2-14b-fp8_i2v_lightx2v)
sogni-agent --video --ref cat.jpg "the cat leaps off the sofa and bolts toward the camera as it tracks back"
# Animate two images together (first frame → last frame; defaults to
# ltx25-22b-int8_i2v_distilled using the standard first/last-frame template)
sogni-agent --video --ref first.png --ref-end last.png \
"the opening frame flows smoothly into the final frame"
# Image+audio-to-video (auto-routes to LTX-2.5 ia2v)
sogni-agent --video --ref cover.jpg --ref-audio song.mp3 \
"music video with synchronized motion"
# Pixal3D textured GLB from one original image (no prompt)
sogni-agent --image-to-3d object.png --mesh-faces 30000 -o object.glb
# Pixal3D multi-view: the front plus any of the subject's own left side, back and
# right side (left view = its own left side faces the camera, so it faces screen-left)
sogni-agent --image-to-3d front.png --left-view left.png --back-view back.png --right-view right.png -o object.glb
# BiRefNet transparent PNG (add --matte for the soft mask)
sogni-agent --remove-background original.png -o cutout.png
# MiniMax Music 3 (the default music model) and Qwen3-TTS studio speech
sogni-agent --music --duration 30 -o score.mp3 "instrumental orchestral theme, 90 BPM, D minor"
sogni-agent --speech --speech-voice ryan -o speech.wav "Welcome to the story."
# Voice cloning from a 3–30s recording, or voice design from a description
sogni-agent --speech --speech-mode clone --voice-reference voice.wav -o clone.wav "A new line in this voice."
sogni-agent --speech --speech-mode design --voice-description "Warm, low-pitched storyteller" -o designed.wav "The journey begins."
# Direct music generation (MiniMax Music 3; tempo and key go in the prompt)
sogni-agent --music --duration 60 \
"uplifting cinematic synthwave theme for a product launch, 110 BPM, A minor"
# Song with lyrics (plain section tags, one per line)
sogni-agent --music --lyrics $'[Verse]\nRise with the morning light\n[Chorus]\nWe run' \
--output-format mp3 "bright indie pop chorus, 128 BPM, C major"
# ACE-Step 1.5 XL Turbo by name: a cheap draft with exact BPM/key, up to 600s
sogni-agent --music -m turbo --bpm 128 --keyscale "C major" "bright indie pop chorus"
# LTX-2.3 voice identity / persona
sogni-agent --video --reference-audio-identity voice.webm \
'A medium close-up frames the narrator as he looks into the lens and says in a calm, low voice, "This is my voice."'
# Hosted chat with Sogni creative-agent tools (/v1/chat/completions)
sogni-agent --api-chat \
"Create a 4-shot product video concept for a red sneaker"
# Hosted chat with image vision plus media-reference metadata
sogni-agent --api-chat --ref product.jpg \
"Turn this into a launch poster and describe the edit plan"
# Hosted chat controls and model discovery
sogni-agent --api-chat --task-profile reasoning --no-thinking \
"Plan a concise multi-step product launch workflow"
sogni-agent --list-api-models
# Live Supernet media model discovery
sogni-agent --list-models
sogni-agent --search-models spicy
sogni-agent --list-models --model-media image --model-tag uncensored
# Live LoRA catalog discovery (IDs, strength ranges, bipolar directions)
sogni-agent --list-loras --lora-catalog-model krea2_turbo_fp8_scaled
sogni-agent --search-loras lighting
sogni-agent --json --list-loras --lora-category character
# Durable hosted chat run with SSE progress events
SOGNI_SKILL_USE_SDK_TRANSPORT=1 sogni-agent --durable-chat \
"Create a product launch storyboard and render the first hero image"
# Durable hosted workflow (/v1/creative-agent/workflows)
sogni-agent --api-workflow \
--video-prompt "The camera slowly pushes in as the sketch comes alive" \
"A graphite robot sketch on a drafting table"
# Durable workflow with a media reference and a cost ceiling
sogni-agent --api-workflow --ref https://cdn.example.com/sketch.png \
--workflow-max-cost 25 --confirm-cost \
--video-prompt "The camera slowly pushes in as the sketch comes alive" \
"Animate the referenced sketch"
# Exact durable workflow input
sogni-agent --api-workflow --workflow-input @workflow.json
# Storyline -> GPT Image 2.5 Sunburst storyboard sheet -> Seedance 2.5 1080p video
sogni-agent --api-workflow storyboard-video --storyboard-frames 6 --duration 12 -Q hq \
"Create a 9:16 bakery launch video with a neon street-window reveal"
# Sogni Intelligence replay records
sogni-agent --list-replays 20
sogni-agent --get-replay run_abc123 --json
# Opt in to SDK transport for hosted operations (durable workflows + chat).
# Validates restEndpoint/socketEndpoint via the skill's SSRF guard, then
# calls the SDK workflow/chat methods directly.
# Falls back to the legacy SSRF-validated fetch path when the env is unset.
export SOGNI_SKILL_USE_SDK_TRANSPORT=1
sogni-agent --api-workflow storyboard-video "10s neon city flyover"
# Local segment + concat with external soundtrack
sogni-agent --video --workflow v2v --ref-video dance.mp4 \
--video-start 10 --duration 8 --controlnet-name pose -o ./clip-2.mp4 \
"robot dancing"
sogni-agent --concat-videos ./final.mp4 ./clip-1.mp4 ./clip-2.mp4 \
--concat-audio song.mp3 --concat-audio-start 0
# Balances and help
sogni-agent --balance
sogni-agent --help
```
> Prefer `.webm`, `.m4a`, or `.mp3` voice clips. Local `.wav` clips are normalized to `.m4a` before upload when `ffmpeg` is available.
>
> For local multi-clip workflows, use the built-in FFmpeg wrappers (`--video-start`, `--audio-start`, `--audio-duration`, `--concat-videos`, `--concat-audio`) over raw shell commands — they produce safer, more reproducible results.
---
## CLI Reference
Run `sogni-agent --help` for the full CLI. Below are the options and tables most agents and users reach for first.
### Common options
| Option | Use |
|--------|-----|
| `-Q fast\|hq\|pro` | Pick image quality without memorizing model IDs |
| `-o <path>` | Save output locally |
| `-c <path>` | Provide image context for edits (without `-m`: Krea 2 Identity Edit for 1-2 images, FLUX 3 Image Klein for 3-10) |
| `--video` | Generate video instead of image |
| `--music` | Generate music instead of an image: MiniMax Music 3 by default, 10–300s (60s default, a ceiling); `-m turbo` or `-m sft` for ACE-Step (10–600s) |
| `--lyrics`, `--bpm`, `--keyscale`, `--timesig` | `--lyrics` for any model (Music 3: plain `[Verse]`/`[Chorus]` tags); `--bpm`/`--keyscale`/`--timesig` are exact ACE-Step controls and are written into the prompt on the default Music 3 |
| `--speech`, `--speech-mode` | Qwen3-TTS voice, clone, or design |
| `--image-to-3d <image>` | Pixal3D binary GLB from one original image (the front view in multi-view) |
| `--left-view`, `--back-view`, `--right-view <image>` | Pixal3D multi-view orbit views, any subset, named by the subject's own sides: left = its own left side toward the camera (it faces screen-left), right = its own right side (it faces screen-right). Templates that label the subject's right side "left" build a model turned 180 degrees |
| `--remove-background <image>`, `--matte` | BiRefNet transparent PNG or soft mask |
| `--ref`, `-c`, `--ref-audio`, `--ref-video` | Frame/loose image/audio/video references; audio/video repeat for H3 r2v and Seedance loose refs |
| `--keyframe <image>@<sec>` | MiniMax H3 keyframe: pin an image at that time strictly inside the clip, in addition to `--ref`/`--ref-end`; repeat for up to 8 (H3 i2v/flf2v, FastH3 Sound to Video, Ref2VA) |
| `--audio-start <sec>` | Where the `--ref-audio` window begins; on FastH3 audio-to-video the window is the clip length (no `--audio-duration`) |
| `--target-resolution <px>` | Target the short side, preserving aspect ratio; on MiniMax H3 FastH3 and Ref2VA Two-Stage, the delivered size `720`, `1080`, or `2K` (default 2K) |
| `--workflow <type>` | Force `t2v`, `i2v`, `r2v`, `s2v`, `ia2v`, `a2v`, `v2v`, or animate workflows |
| `--wan3-ratio`, `--smart-duration`, `--reference-file-url`, `--reference-link-url`, `--watermark` | Wan 3 adaptive/fixed ratio, smart timing, document/web context, and watermark controls |
| `--expand-prompt`, `--no-expand-prompt` | Enable provider prompt expansion for direct Wan 3 video, or preserve the exact submitted prompt |
| `--generate-audio`, `--no-generate-audio` | Keep/strip MiniMax H3's track, enable/disable Wan 3 native audio, or control generated-keyframe workflows |
| `--sampler <name>` | Image/music sampler; LightX2V FL2VA H3 Turbo accepts `euler`, `er_sde`, or `sa_solver` and defaults to `er_sde` on Socket. Ref2VA Turbo and FastH3 Turbo accept Euler only. The CLI omits this field unless explicitly set. |
| `--api-chat` | Use `/v1/chat/completions` with Sogni creative-agent tools |
| `--api-workflow` | Start a `/v1/creative-agent/workflows` durable workflow with explicit `input.steps`; optional `storyboard-video` preset |
| `--workflow-input <json\|@path>` | Explicit durable workflow input JSON. Use `@path` to load JSON from a file. |
| `--workflow-max-cost <n>`, `--confirm-cost`, `--no-confirm-cost` | Set durable workflow capacity ceiling and explicit cost confirmation |
| `--storyboard-frames <n>` | Beat count for `--api-workflow storyboard-video` |
| `--video-prompt`, `--negative-prompt`, `--generate-audio`, `--expand-prompt` | Generated-keyframe durable workflow step controls |
| `--watch-workflow`, `--list-workflows`, `--get-workflow <id>`, `--workflow-events <id>`, `--stream-workflow <id>`, `--cancel-workflow <id>`, `--resume-workflow <id>` | Manage durable workflows |
| `--api-tools <mode>`, `--no-api-tool-execution`, `--llm-model <id>`, `--task-profile <profile>`, `--max-tokens <n>`, `--thinking` / `--no-thinking`, `--api-base-url <url>` | Tune hosted API requests |
| `--list-api-models`, `--get-api-model <id>` | Inspect Sogni Intelligence LLM models |
| `--list-models [query]`, `--search-models <query>` | List or search currently available Supernet image, video, and audio models |
| `--model-media <type>`, `--model-network <network>` | Filter live model discovery by media or Fast/Relaxed network |
| `--network <fast\|relaxed>` | Render on this Supernet for one run; overrides the configured `defaultNetwork` (default: Fast) |
| `--model-tag <tag>` | Filter by an official catalog tag such as `spicy` or `uncensored`; repeat for AND matching |
| `--list-loras [query]`, `--search-loras <query>` | List or search the live LoRA catalog with each LoRA's hard range, recommended range, default, and slider direction |
| `--lora-catalog-model <id>`, `--lora-category <category>` | Filter LoRA discovery to one model's compatible LoRAs or one catalog category |
| `--list-replays [n]`, `--get-replay <id>`, `--ingest-replay <json\|@path>` | Manage Sogni Intelligence replay records (use `@path` to load JSON from a file) |
| `--persona <name>` | Use a saved persona |
| `--concat-videos <out> <clips...>` | Stitch clips locally with FFmpeg |
| `--extract-first-frame`, `--extract-frame-at`, `--extract-last-frame` | Extract visual-QA frames through safe FFmpeg wrappers |
| `--verify-video <path>` | Probe streams and fully decode a final video before delivery |
| `--last`, `--last-image` | Inspect last render / reuse last image as context or video reference |
| `-t <sec>`, `--cancel-on-timeout` | How long a run waits, from submission (default 30 image, 1800 video, 600 music). Time the account's own plan limit holds a project is not counted. A timeout leaves the project running and prints the `--result` command that fetches it; `--cancel-on-timeout` cancels instead |
| `--detach` (`--no-wait`), `--status <id>`, `--result <id>`, `--wait`, `--recent [hours]` | Submit and return with the project id; check a project's state and why it is queued (plan limit or workers); fetch its finished media (`-o` saves it); with `--wait`, wait for the project over the live connection first instead of polling; list this account's completed projects (default 24 h, max 168) |
| `--strict-size` | Fail instead of auto-adjusting video size |
| `--json` | Emit structured output for agents |
| `-n <count>` | Multiple outputs per call (safety-capped at 16; raise deliberately with `SOGNI_MAX_COUNT`) |
| `doctor` / `--doctor` | Install health check: Node, credentials, ffmpeg, auth, version (`--json` for agents) |
| `self-update` | Upgrade the CLI via the detected package manager |
| `--whats-new [version]` | Show bundled CHANGELOG entries (everything after `<version>` if given) |
| `--snooze-update` | Snooze the pending-update reminder (1 day → 2 days → 1 week) |
| `--no-update-check` | Disable the background update check for this run (`SOGNI_NO_UPDATE_CHECK=1` to disable always) |
| `--video-model <id>` | Override the i2v model used by `--angles-360-video` |
| `--memory-category <c>` | Category for `--memory-set`: `preference` (default), `fact`, or `context` |
### Quality presets
Skip remembering model IDs — `--quality` / `-Q` selects the right model, steps, and dimensions for image generation:
| Preset | Model | Steps | Size | Speed |
|--------|-------|-------|------|-------|
| `fast` | `z_image_turbo_bf16` | 8 | 512×512 | ~5–10s |
| `hq` | `z_image_turbo_bf16` | default | 768×768 | ~10–15s |
| `pro` | `qwen_image_2512_fp8` | 20 | 1024×1024 | ~30 sec |
Explicit `--model` overrides the preset's model. Explicit `-w`/`-h` overrides dimensions.
### Recommended models
Prefer `-Q fast|hq|pro` for images and automatic workflow routing for video. Pass `-m` only when you need a specific model family.
| Need | Recommended selector |
|------|----------------------|
| Default images | `z_image_turbo_bf16` |
| OpenAI GPT Image generation, editing, or strong text rendering | `gpt-image-2` |
| Highest-quality images | `qwen_image_2512_fp8` (or `-Q pro`) |
| Image editing, chosen by what the request means (never Qwen Image Edit unless the user names it) | a person's likeness: `krea2_identity_edit_v1_2` (the `-c` default for 1-2 references); type, logos and graphic design: `flux3_image_klein_sd_int8_convrot` (the default for 3-10); NSFW: `dark_beast_krea2_identity_edit_v1_2`; the best result with Premium Spark: `gpt-image-2.5-sunburst` |
| Deterministic image upscaling through 16K | `rtx_vsr_pro` via `--upscale` |
| Promptless video upscaling to 1080p/1440p | `flashvsr_v1.1_tiny_long_bf16` via `--upscale-video` |
| Object masks from points, boxes, or a description | `sam3_image_segment_bf16` via `--segment` |
| Dark Beast Krea 2 images | `dark_beast_krea2_fp8` |
| Identity-preserving Krea image edits | `krea2_identity_edit_v1_2` |
| Text-to-image, image-to-image, or edits from up to ten references in one model (FLUX 3 Image Klein) | `flux3_image_klein_sd_int8_convrot` |
| Uncensored identity-preserving Krea edits | `dark_beast_krea2_identity_edit_v1_2` |
| Seedream 5.0 Pro Uncensored images or edits from up to ten references, only when the user asks for it ("Seedream Uncensored") | `seedream-5-0-pro-uncensored` |
| Photobooth face transfer | `coreml-sogniXLturbo_alpha1_ad` |
| Songs and instrumentals (default) | `minimax_music3` (`--music`) |
| Quick, cheap music draft, exact BPM/key, or over 300s | `ace_step_1.5_xl_turbo` (`--music-model turbo`) |
| ACE-Step with stronger lyric handling | `ace_step_1.5_xl_sft` (`--music-model sft`) |
| MiniMax H3 text-to-video with native stereo audio | `minimax-h3` or `minimax-h3-t2v` |
| MiniMax H3 image-to-video | `minimax-h3-i2v` |
| MiniMax H3 first-frame → last-frame video | `minimax-h3-flf2v` with `--ref A --ref-end B` |
| MiniMax H3 video that passes through extra images at chosen times | Any H3 i2v/flf2v, FastH3 Sound to Video, or Ref2VA selector with repeatable `--keyframe image@seconds` (up to 8); two are included in the price |
| MiniMax H3 Standard reference-to-video (explicit choice) | `minimax-h3-r2v` with up to 9 images, 3 videos, 3 audios / 12 files total |
| MiniMax H3 Balanced text-to-video | `minimax-h3-balanced` or `minimax-h3-t2v-balanced` |
| MiniMax H3 Balanced image-to-video | `minimax-h3-i2v-balanced` with `--ref` |
| MiniMax H3 Balanced first-frame → last-frame video | `minimax-h3-flf2v-balanced` with `--ref A --ref-end B` |
| MiniMax H3 Balanced reference-to-video | `minimax-h3-r2v-balanced` with up to 9 images, 3 videos, 3 audios / 12 files total |
| MiniMax H3 LightX2V Turbo text-to-video | `minimax-h3-turbo` or `minimax-h3-t2v-turbo` |
| MiniMax H3 LightX2V Turbo image-to-video | `minimax-h3-i2v-turbo` with `--ref` |
| MiniMax H3 LightX2V Turbo first-frame → last-frame video | `minimax-h3-flf2v-turbo` with `--ref A --ref-end B` |
| MiniMax H3 Ref2VA Turbo reference-to-video | `minimax-h3-r2v-turbo` with up to 9 images, 3 videos, 3 audios / 12 files total |
| MiniMax H3 FastH3 Turbo text-to-video | `minimax-h3-fasth3-turbo` or `minimax-h3-fasth3-t2v-turbo` |
| MiniMax H3 FastH3 Turbo image-to-video | `minimax-h3-fasth3-i2v-turbo` with `--ref` |
| MiniMax H3 FastH3 Turbo first-frame → last-frame video | `minimax-h3-fasth3-flf2v-turbo` with `--ref A --ref-end B` |
| MiniMax H3 reference-to-video (default: Balanced R2V) | `minimax-h3-r2v-balanced` with up to 9 images, 3 videos, 3 audios / 12 files total; catalog and Personal LoRAs |
| MiniMax H3 1080p or 2K video (FastH3 Two-Stage, delivered at twice the canvas) | `minimax-h3-fasth3-turbo-2stage` (infers the frame mode; 2K default, `--target-resolution 1080` or `720`), or `minimax-h3-fasth3-t2v-turbo-2stage` / `-i2v-turbo-2stage` / `-flf2v-turbo-2stage` |
| MiniMax H3 1080p or 2K reference-to-video (Ref2VA Two-Stage, delivered at twice the canvas) | `minimax-h3-r2v-balanced-2stage` (preferred Balanced R2V; Standard and FastH3 Reference only when explicitly requested): the same references, durations and LoRAs as `minimax-h3-r2v` / `minimax-h3-r2v-balanced` / `minimax-h3-fasth3-r2v-turbo`; 2K default, `--target-resolution 1080` or `720` |
| MiniMax H3 video driven by your own voice or song (FastH3 audio-to-video) | `minimax-h3-fasth3-ia2v-turbo` (`--ref` + `--ref-audio`), `minimax-h3-fasth3-flfa2v-turbo` (`--ref` + `--ref-end` + `--ref-audio`), or `minimax-h3-fasth3-a2v-turbo` (`--ref-audio`); `minimax-h3-fasth3-turbo` with `--ref-audio` picks the mode; add `-2stage` for Two-Stage; `--lora` works as on the frame modes |
| Text-to-video with native dialogue/audio | `ltx25` (Distilled) or `ltx25-22b-int8_t2v_dev` (Dev/HQ) |
| Explicit uncensored image-to-video on 30GB+ GPUs | `ltx23-eros` with `--no-filter` |
| Image or first/last frames to video | `ltx25-i2v` (FLF shares the I2V model ID) |
| Image+audio-to-video | `ltx25-ia2v` |
| Audio-to-video | `ltx25-a2v` |
| Video-to-video with ControlNet/edit templates | `ltx25-v2v` |
| Seedance text-to-video | `seedance2` for up to native 4K; `seedance2-mini` for the lower-cost 720p path; `seedance2-fast` for the legacy 720p fast path |
| Seedance video-to-video without ControlNet | `seedance2-v2v` |
| Seedance 2.5 single clip up to 30s (480p/720p/1080p, MP4/MOV and last-frame export) | `seedance2-5` (`seedance2-5-ia2v` / `seedance2-5-v2v` for image+audio and v2v/editing) |
| Seedance 2.5 Uncensored, only when the user asks for it ("Seedance Uncensored", "Seedance Spicy") | `seedance2-5-uncensored` |
| Seedance 2.0 Mini Uncensored, only when the user asks for it ("Seedance Mini Uncensored", "Uncensored Seedance Mini") | `seedance2-mini-uncensored` |
| Wan 3 unified text, frame, reference, audio, or video generation | `wan3` / `wan3.0-video` |
| Wan 3.0 Enhanced text, frame, reference, audio, or video generation | `wan3-enhanced` / `wan3.0-spicy-video` |
| Face lip-sync with uploaded audio | `wan_v2.2-14b-fp8_s2v_lightx2v` |
`gpt-image-2` supports flexible OpenAI image sizes up to 3840 px on either edge, max 3:1 aspect ratio, and total pixels from 655,360 to 8,294,400; the API snaps dimensions to valid multiples of 16. For image editing with `gpt-image-2`, you can pass up to 16 context images. For likeness-preserving edits of a referenced person or character, agents default to Krea 2 Identity Edit (`krea2_identity_edit_v1_2`) unless you explicitly choose another model. It and Dark Beast Krea 2 Identity Edit (`dark_beast_krea2_identity_edit_v1_2`) use `-c/--context`, accept 1-2 references at 512-2048 px, and leave execution defaults to the current model tier.
For Pixal3D mesh budgets, BiRefNet cutouts/mattes, Music 3 section tags, and all Qwen3-TTS modes, read [the model guide](references/models.md). Speech uses exact scripts without music duration or sampler controls; clone mode checks 3–30s recordings with `ffprobe`. Audio batches save every output with numbered filenames.
Music generation uses `--music` and outputs `mp3` by default. `--audio` remains the video-reference alias for `--ref-audio`; use `--music` or `--generate-music` for direct audio-only generation.
Seedance 2.5 loose-reference operations use an explicit task contract. `reference` accepts any loose image/video/audio set (including audio-only); `edit` and `extend` require `@Video1` through `--ref-video` and reject first/last-frame anchors. Edit inherits the source aspect ratio and requires its source duration, while extend inherits the ratio and uses the requested continuation duration:
```bash
sogni-agent --video -m seedance2-5 --seedance-task-type reference --ref-audio voice.m4a "Use @Audio1 as the singer's voice. <the new performance, in time-coded beats>"
sogni-agent --video -m seedance2-5-v2v --seedance-task-type edit --ref-video source.mp4 --duration 8 --target-resolution 720 "Edit @Video1. Replace <what changes>. Keep the subject, camera path, and timing."
sogni-agent --video -m seedance2-5-v2v --seedance-task-type extend --ref-video source.mp4 --duration 8 --target-resolution 720 "Extend @Video1. <the new footage after its ending, in time-coded beats>"
```
Seedance 2.5 draft mode is opt-in. A 480p preview can help check uncertain motion, composition, or lighting before committing to 1080p. Before adding a paid draft, the agent must explain that benefit, quote the actual draft, direct-final, and combined draft-plus-final estimates, ask which workflow the user prefers, and wait for their choice. If a 720p/1080p attempt fails or produces an unusable take, the agent should suggest testing the revision in 480p draft mode before another expensive attempt, then get consent before switching. A 480p draft is roughly 5.5 times cheaper than 1080p; compare actual estimates for the same inputs. A draft is an extra charge, not credit toward the final; video-input drafts can be costly. An explicit draft request or agreed draft plan already supplies consent within its scope.
`--seedance-draft` renders a 480p draft at the 480p price. `--seedance-finalize <job-id>` renders that same video at 1080p for a separate 1080p charge, with the draft's prompt, media, length, ratio, seed and audio, before the draft's `seedanceDraftExpiresAt` (about three hours). It cannot change lighting or other content. A later higher-quality/final request supersedes draft-first iteration: finalize an approved unchanged draft, or render the revision directly at the requested final resolution. Another paid draft requires renewed consent. See [the full draft guide](references/models.md#seedance-25).
```bash
# Only after the user chooses the quoted draft workflow:
sogni-agent --video -m seedance2-5 --seedance-draft --json "<Seedance prompt>" # results[0].jobId
# After approval of the unchanged take and its separately quoted 1080p cost:
sogni-agent --video -m seedance2-5 --seedance-finalize <job-id> -o final.mp4
```
---
## Video Sizing & Aspect Ratios
- **WAN 2.2 models** use dimensions divisible by 16, each side 480–1536 px, and at most 1,048,576 pixels per frame (1024×1024), so 1280×720, 720×1280, and 1024×1024 fit but 1536×864 and 1080p do not (as of 2026-09). The CLI refuses an explicit `-w`/`-h` or `--target-resolution` above that instead of sending it; sizes it chooses itself are fitted. (Since 2026-09-26 the network itself scales an oversized WAN 2.2 request down to about 1 MP and refuses only a side below 480, error 4101.)
- **Wan 3** (`wan3.0-video`) is a Premium Spark Alibaba model with fixed 30 fps, fixed or smart 2–30 s output, native audio, 480P/720P/1080P tiers, and `adaptive`, `16:9`, `4:3`, `1:1`, `3:4`, or `9:16` output. It accepts one first frame plus an optional last frame, or loose references up to 10 images, 5 videos, and 5 audio clips. It can also use one public document (PDF/Office/text/Markdown/Keynote/Pages/Numbers, up to 100 MB; PDF/DOCX/DOC/PPTX/PPT/Keynote/Pages up to 50 pages) or one public webpage; file and link context are mutually exclusive and cannot be combined with first/last anchors. Each video/audio reference is 1–15 s and each modality's clips total at most 15 s. Video references condition a new generation; Alibaba exposes no edit/extend task mode or task-type field, so use a dedicated video-to-video model when source-preserving editing is required. Provider prompt expansion defaults on; `--no-expand-prompt` preserves the exact prompt. Watermark defaults off. Send no negative prompt, steps, guidance, sampler, scheduler, ControlNet, or mask. Sogni retail rates before subscription discounts are $0.065/$0.13/$0.26 per output second at 480p/720p/1080p (as of 2026-08). The CLI renders 720P unless `--target-resolution 480` or `1080` is given, sending Alibaba's exact size for that tier and ratio; image-to-video keeps the first frame's shape with its short side at the tier.
- **Wan 3.0 Enhanced** (`wan3.0-spicy-video`; MuleRouter provider ID `w3.0-video`; aliases `wan3-enhanced`, `wan3-spicy`) runs at fixed 30 fps with fixed or smart 2–30 s output, native audio, prompt expansion, 480P/720P/1080P, and `adaptive`, `16:9`, `9:16`, `1:1`, `4:3`, or `3:4`. It accepts either first/last-frame anchors or up to 10 image, 5 video, and 5 audio loose references; the two modes cannot be mixed. It has no document/web context, watermark, negative prompt, source-video edit, or extend mode. Standard PAYG is $0.08/$0.16/$0.32 per output second at 480P/720P/1080P (as of 2026-09). Existing paid subscribers receive a one-time $10 Unlimited / $20 Unlimited Pro model credit through September 1, 2026 00:00 UTC (August 31 at 5:00 PM PT); this is a launch credit, not subscription coverage.
- **MiniMax H3 Standard, Balanced, LightX2V Turbo, and FastH3 Turbo** use a 32 px grid, fixed 24 fps, native 32 kHz stereo audio, 124–362 frames (`124 + n×17`, i.e. 5.17–15.08 s), and a 1,032,192-pixel render cap; Ref2VA Turbo's cap is 522,240 pixels, its own 960×544 canvas, and the CLI fits larger requests inside it. Standard, Balanced, LightX2V FL2VA Turbo, FastH3, and FastH3 Reference normally default to 1344×768 or 768×1344; Ref2VA Turbo defaults to 960×544. Standard uses 20 steps; Balanced uses fixed 8-step Euler/simple acceleration, with LightX2V for FL2VA and Larry v4 for Ref2VA; both Turbo engines use 4 steps. FL2VA H3 Turbo defaults to `er_sde` on Socket and permits `euler`, `er_sde`, or `sa_solver`; Ref2VA Turbo and the separate FastVideo VSA FastH3 engine use Euler/simple only. The CLI omits the sampler unless `--sampler` is passed. FastH3 is about 2x faster than LightX2V Turbo and up to 6x faster than Standard for comparable 768p, 15-second requests; it supports T2V/I2V/FLF2V, and FastH3 Reference (`minimax-h3-fasth3-r2v-turbo`) is its reference-to-video model. Guidance 1 is fixed and there is no negative-prompt input. Every Ref2VA tier accepts up to 9 images, 3 videos, and 3 audios, capped at 12 files; at least one visual reference is required. FastH3 keeps the FastVideo engine when an H3 LoRA is attached: base jobs require 23 GB and jobs with an H3 LoRA require 32 GB. The other FL2VA/Balanced/Turbo and image-only R2V paths require 32 GB-class workers, while video-conditioned R2V requires above 40 GB. See `references/video-prompting.md` § MiniMax H3 Prompting for the exact contracts.
- **LTX family** (`ltx2-*`, `ltx23-*`, `ltx25-*`) uses dimensions divisible by 64. The current wrapper caps non-WAN video dimensions at 2048 px on the long side.
- **Seedance** runs at fixed 24 fps. The 2.0 family (`seedance2`, `seedance2-mini`, Seedance 2.0 Mini Uncensored `seedance2-mini-uncensored`, `seedance2-fast`) supports 4–15 s durations; full `seedance2` supports native 4K via `--target-resolution 2160` while `seedance2-mini`, `seedance2-mini-uncensored` and `seedance2-fast` remain capped to the 720p lower-resolution path. `seedance2-5` and Seedance 2.5 Uncensored (`seedance2-5-uncensored`) render 4–30 s single clips at 480p/720p/1080p (no 4K), with `--output-format mov` and `--return-last-frame` for the final frame as an image. Other default/WAN paths support up to 10 s; LTX and WAN animate workflows support up to 20 s.
- For spoken dialogue, budget roughly 3 words per second plus about 1 second for each meaningful acting beat or pause. Keep quoted speech under the model's hard per-clip word budget.
- The script auto-normalizes video sizes to satisfy these constraints.
- Use `--target-resolution <px>` for bare resolution requests like "720p" — it targets the short side and preserves the inherited aspect ratio.
- Natural-language aspect requests like "portrait", "square", "16:9", or "9:16" are inferred when width/height aren't explicitly set. Combined requests like "720p 9:16" keep the requested short side while applying the requested shape.
- For i2v (and any workflow using `--ref` / `--ref-end`), the client wrapper resizes the reference image with strict aspect-fit (`fit: inside`) and uses the *resized* dimensions as the final video size. Because that resize uses rounding, a "valid" requested size can still produce an invalid final size (example: `1024×1536` requested, but ref becomes `1024×1535`). `sogni-agent` detects this for local refs and auto-adjusts to a nearby safe size.
- **LTX-2.5 first/last-frame default:** `--ref` + `--ref-end` with no `-m` uses `ltx25-22b-int8_i2v_distilled` and the dedicated FLF workflow template. It shares the I2V public model ID and does not attach the LTX-2.3 transition LoRA. Pin `ltx23-22b-fp8_i2v_distilled` explicitly only when the legacy transition-LoRA behavior is required.
- **Private mature-theme creativity:** optional uncensored LTX-2.3 video models are available for adults who explicitly want them. They remain opt-in and are not part of ordinary model recommendations; the agent loads their specialized guidance only for a relevant request.
- Pass `--strict-size` to fail instead — the script will print a suggested size.
V2V defaults mirror Sogni Chat workflow tuning: `canny`, `pose`, and `depth` use ControlNet strength `0.85` with detailer assist; `detailer` uses strength `1.0`. LTX 2.5 `pose` requires both `--ref-video` for the motion/pose sequence and `--ref` for the subject appearance; explicit LTX 2.3 rollback keeps its existing optional-image behavior. Use `-m seedance2-v2v` for Seedance V2V without ControlNet. Seedance accepts public HTTPS image, video, and audio references that pass CLI URL safety checks; localhost and private-network URLs are rejected before forwarding. The 2.0 family requires audio references to be paired with an image or video; Seedance 2.5 reference mode permits audio-only input.
The LTX-2.5 v2v selector `ltx25-v2v` supports two extra control modes: **`outpaint`** extends/expands the video canvas (e.g. make a vertical clip widescreen, or add space in a direction) — it is positional and mask-free, anchored with a position (`center|top|bottom|left|right`) and an optional target aspect ratio (`16:9|9:16|1:1|4:3|3:4|21:9`), and the canvas only grows, never crops; **`inpaint`** regenerates a masked region of the source video and **requires a mask image** (white pixels = region to regenerate) in direct CLI/SDK mode. The hosted `video_to_video` tool selects these with `controlMode` `outpaint`/`inpaint` and can derive an inpaint mask when the user did not upload one. The direct CLI and sogni-client SDK example expose them via `--control-type` / `control-type` (`canny|pose|depth|detailer|outpaint|inpaint`), with `--outpaint-position` for outpaint and `--mask` for inpaint. Pin `ltx23-v2v` only for rollback. See `references/video-editing.md` for details.
---
## LTX-2.x Prompting Guide
Every video family reads its own prompt grammar. `sogni-agent prompt-guide <model> --mode <mode>` prints the rules Sogni's own prompt writer uses for that model and mode (free and offline; with no model it lists every guide), and `references/video-prompting.md` has a section per model (LTX, MiniMax H3, Seedance, WAN 2.2, Wan 3, HappyHorse). This section summarizes the LTX one.
When you use LTX-2.5 or an LTX-2.3 rollback model, do **not** feed it short tag prompts like `"cinematic drone shot over tropical cliffs"`. LTX renders more reliably from a dense natural-language scene description.
- Write present-tense prose with no bullets, headers, or tag blocks.
- Text-to-video gives each shot one sentence: one continuous shot unless the user asks for cuts, and every requested shot kept in order, each later sentence opening with its cut time (`At exactly 3 seconds, a hard cut switches to a close-up of …`). Image-to-video and first/last-frame stay one continuous take.
- Start with shot scale and scene identity, then cover environment, time of day, textures, and named light sources.
- Keep characters and objects concrete and stable; give each shot one main action thread from start to finish.
- For dialogue, include the exact spoken words in double quotes with the speaker and delivery identified inline.
- Keep any on-screen text the user asks for exactly, in double quotes after "reads" (`a neon sign reads "OPEN ALL NIGHT"`), and add none they did not ask for.
- Express mood through visible behavior, motion, and sound cues — not vague adjectives.
- Use positive phrasing. Avoid script formatting, negative prompts, and filler words like "beautiful" or "nice".
- Fit every action the user names into the clip, in order. If they cannot all finish on screen, suggest a longer clip rather than dropping one.
**Example rewrite:**
```text
User ask: "make a 4k video of a woman in a neon alley"
LTX-2.5 prompt (one shot, so one sentence): "A medium shot frames a woman in her 30s in a dark trench coat standing in a rain-soaked neon alley at night, violet and amber signs reflecting across the wet pavement and steam drifting from a street vent behind her, as she turns toward the camera and steps forward with one hand tightening around her bag strap while the camera pushes in on her set jaw, rain tapping on a metal fire escape and a distant train humming through the block."
```
---
## Photobooth (Face Transfer)
Generate new stylized portraits from a face photo using InstantID ControlNet:
```bash
sogni-agent --photobooth --ref face.jpg "80s fashion portrait"
sogni-agent --photobooth --ref face.jpg -n 4 "LinkedIn professional headshot"
```
Uses SDXL Turbo (`coreml-sogniXLturbo_alpha1_ad`) at 1024×1024 by default. The face image is passed via `--ref` and styled by the prompt. Cannot be combined with `--video` or `-c` / `--context`.
`--photobooth` is face-reference generation, not full-image editing. If the request is "same image, different style" — for example an anime version that must keep the same face, pose, clothing, background, framing, and composition — use context editing with `-c/--context` instead (Krea 2 Identity Edit, `-m krea2_identity_edit_v1_2`, keeps the person recognizable).
Multi-angle mode (`--multi-angle` / `--angles-360`) auto-builds the `<sks>` prompt and applies the `multiple_angles` LoRA. It runs on Qwen Image Edit 2511, the only model with that LoRA, so use it only when asked for by name; an ordinary change of camera angle is a `-c` edit on the routed model. `--angles-360-video` generates i2v clips between consecutive angles (including last → first) and concatenates them with `ffmpeg` into a seamless loop.
`--balance` / `--balances` does not require a prompt and prints the account username, subscription plan (`Plan: Sogni Unlimited (active)` / `Plan: none`), and current `SPARK`, `PREMIUM SPARK`, and `SOGNI` balances before exiting. In `--json` mode, `spark` is total Spark and `premiumSpark` is the Premium portion already included in that total. Premium is `null` in JSON or `unknown` in text when the client does not expose it; zero means a known zero balance. The payload also carries `username` and `subscription` fields (`null` when unavailable). Use this read-only command to check for a top-up; never submit a paid render to discover the balance. `--doctor` likewise reports the authenticated user and an explicit `plan` check, so a wrong-account API key or a missing subscription is visible at a glance.
---
## Personas, Memory, and Personality
### Personas
Named people with saved reference photos and optional voice clips for identity-preserving generation:
```bash
# Add a persona
sogni-agent --persona-add "Mark" --ref face.jpg --relationship self --description "30s male, brown hair"
# Add with voice clip for video voice cloning
sogni-agent --persona-add "Sarah" --ref sarah.jpg --relationship partner --voice-clip voice.webm
# Generate using a persona (auto-injects photo as context)
sogni-agent --persona "Mark" -o hero.png "superhero in dramatic lighting"
# Video using a persona photo + saved voice identity
sogni-agent --video --persona "Sarah" 'A medium close-up frames Sarah as she smiles into the lens and says, "This is my voice."'
# List / remove
sogni-agent --persona-list
sogni-agent --persona-remove "Mark"
```
Stored at `~/.config/sogni/personas/`. Personas resolve by explicit saved name, id, or tag/alias; relationship phrases are not treated as persona identifiers.
### Memory (persistent preferences)
Save preferences that agents respect across sessions:
```bash
sogni-agent --memory-set preferred_style "watercolor and soft lighting"
sogni-agent --memory-set aspect_ratio "16:9"
sogni-agent --memory-list
sogni-agent --memory-remove preferred_style
```
Stored at `~/.config/sogni/memories.json`.
### Personality (custom agent instructions)
Tell the agent how it should behave:
```bash
sogni-agent --personality-set "Be concise, always use cinematic lighting"
sogni-agent --personality-get
sogni-agent --personality-clear
```
Stored at `~/.config/sogni/personality.txt`.
---
## Hosted API Modes
Hosted API modes require `SOGNI_API_KEY`.
**Choosing a mode.** Whatever is driving this CLI is usually a more capable planner than Sogni's hosted model, so prefer to plan yourself and let the server execute: direct-to-SDK flags for one-shot work, and `--api-workflow` with an explicit `--workflow-input` step graph for multi-step/durable work (you author the plan; the server runs it durably with replay — no hosted re-planning). Use `--api-chat` / `--durable-chat` when you deliberately want the hosted model to own a long server-side loop, or when several local files must be uploaded for one turn.
- **`--api-chat`** targets `/v1/chat/completions` with Sogni creative-agent tools and **delegates planning/tool-selection to the hosted model** — reach for it when the caller is a thin client, when you want the hosted model to drive a long server-side tool loop, or when several local files must be uploaded for one turn. The CLI sanitizes prompt-injection markers before forwarding messages and can use the current server-side creative-agent media tools, including video extension, segment replacement, overlays, subtitles, stitch/orbit/dance composition, and generated artifact indexing. Tune with `--api-tools creative-agent|creative-tools|none`, `--no-api-tool-execution`, `--llm-model`, and `--system`.
- **Sogni Intelligence controls** include `--task-profile general|coding|reasoning`, `--max-tokens`, and `--thinking` / `--no-thinking`, which forward to `/v1/chat/completions` as `task_profile`, `max_tokens`, and `chat_template_kwargs.enable_thinking`. Use `--list-api-models` or `--get-api-model <id>` to inspect `/v1/models`.
- **`--durable-chat`** starts a hosted `/v1/chat/runs` record through the SDK transport. Set `SOGNI_SKILL_USE_SDK_TRANSPORT=1` before using it. The CLI streams assistant deltas and de-duplicated per-job progress / ETA / result lines from hosted run events.
- **`--api-workflow`** targets `/v1/creative-agent/workflows` for durable, async workflow records with event streaming and cancellation. Requests carry `input.steps` plus snake_case controls such as `token_type`, `media_references`, `max_estimated_capacity_units`, and `confirm_cost`.
- **`--workflow-input`** forwards exact durable workflow JSON (`{ title?, steps: [...] }`). Use this when you need exact multi-step behavior such as repeated `replace_video_segment` steps with `replacementStartSeconds` / `replacementEndSeconds` for interleaved video slices.
- **`--api-workflow storyboard-video`** generates a storyline, creates a single storyboard sheet with GPT Image 2.5 Sunburst, then passes that artifact into Seedance 2.5 for 1080p video generation. The `-Q fast|hq|pro` preset maps to GPT Image low/medium/high quality for that storyboard sheet; explicit model and resolution choices still win.
- **Media references** from `-c`, `--ref`, `--ref-end`, `--keyframe`, `--ref-audio`, `--reference-audio-identity`, and `--ref-video` are forwarded as `media_references` metadata in hosted API requests; `--api-chat` / `--durable-chat` also tell the hosted agent which upload to pin at which time as MiniMax H3 `keyframes`. API chat also attaches image refs as vision inputs. Local file references are uploaded to Sogni media storage first, then forwarded as retrievable URLs so durable executors do not depend on `data:` URI support. Durable workflow JSON can bind those references into step arguments with `sourceStepId: "$input_media"`. Direct CLI generation also sends prompts and selected reference media to Sogni for remote processing.
- **Cost controls** use `--workflow-max-cost <n>` to reject workflow starts above a capacity-unit ceiling, and `--confirm-cost` / `--no-confirm-cost` to forward explicit billing confirmation.
- Manage runs with `--watch-workflow`, `--workflow-events`, `--stream-workflow`, `--list-workflows`, `--get-workflow`, `--cancel-workflow`, and `--resume-workflow`. Use `--workflow-input` to provide exact durable workflow JSON.
- **Replay records** use `/v1/replay/records`: `--list-replays [limit]`, `--get-replay <runId>`, and `--ingest-replay <json|@path>` expose redacted RunRecord storage for Sogni Intelligence replay/debug viewers.
Override the API origin with `--api-base-url`, `SOGNI_API_BASE_URL`, or `SOGNI_REST_ENDPOINT`.
Hosted API credentials are only sent to `https://api.sogni.ai` by default. Add trusted custom
hosts with `SOGNI_API_ALLOWED_HOSTS`; loopback or non-HTTPS local testing requires
`SOGNI_ALLOW_UNSAFE_API_BASE_URL=1`.
---
## Dynamic Prompt Variations
Generate diverse images in a single call with `{option1|option2|option3}` syntax:
```bash
# 3 images: "a red car", "a blue car", "a green car"
sogni-agent -n 3 "a {red|blue|green} car"
# Multiple groups cycle independently
sogni-agent -n 4 "a {cat|dog} in a {garden|kitchen}"
# -> "a cat in a garden", "a dog in a kitchen", "a cat in a garden", "a dog in a kitchen"
```
Options cycle sequentially per image. Without `{...}` syntax, `-n` produces multiple images with the same prompt.
For video, use the same pattern when every output shares the same source/end assets and settings and only the prompt text varies:
```bash
sogni-agent --video --ref hero.png -n 3 --duration 5 \
"{the subject smiles and waves|the subject turns toward the window|the subject raises a hand in greeting}"
```
If each clip needs different source images, end frames, durations, audio slices, or other per-output settings, keep those as separate per-clip workflow arguments instead of collapsing them into a Dynamic Prompt branch.
---
## Token Auto-Fallback
Use `--token-type auto` to retry native Sogni models with SOGNI tokens when SPARK is insufficient:
```bash
sogni-agent --token-type auto "a dragon eating tacos"
```
Tries SPARK first, then falls back to SOGNI if the balance is too low. Vendor models such as GPT Image 2, Seedance, HappyHorse, and Wan 3 require Premium Spark eligibility and never use SOGNI fallback. If usable balance is still insufficient, buy Spark Packs at https://docs.sogni.ai/pricing/#spark-packs.
On a **Sogni Unlimited** subscription, Sogni-hosted generation is covered by the plan instead of spending tokens — see the next section.
---
## Sogni Unlimited Subscription
[Sogni Unlimited](https://docs.sogni.ai/pricing/unlimited-plan-details) 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. Manage subscriptions where they were purchased — the Stripe billing portal for web checkouts, or the App Store / Google Play account settings for mobile.
### Plans
| Plan | Monthly | Annual |
| --- | --- | --- |
| **Unlimited** | $20 / mo | $199 / yr |
| **Unlimited Pro** | $50 / mo | $498 / yr |
App Store and Google Play prices may differ from web pricing due to platform fees. A 3-day free trial is available once per account (a payment method is required and the subscription converts to paid when the trial ends unless cancelled first).
Plan pricing, included features and models, usage allowances, fair-use controls, and other limits are subject to change at Sogni AI's discretion, subject to applicable law. Sogni will provide advance notice of material changes affecting an active paid subscription when required. Treat the live plan catalog and checkout as authoritative.
### What the subscription covers
- **Covered:** Sogni-hosted models on the Supernet — image, video, and music generation, including worker-hosted premium models. Covered renders bill to the subscription and do not spend Spark or SOGNI.
- **Not subscription-covered:** external-vendor models — **GPT Image 2 / GPT Image 2.5 Sunburst / GPT Image 2.5 Flare** (`gpt-image-2`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-flare`), **Seedance 2.0 / Seedance 2.0 Mini / Seedance 2.0 Mini Uncensored / Seedance 2.0 Fast / Seedance 2.5 / Seedance 2.5 Uncensored** (`seedance-2-0`, `seedance-2-0-mini`, `seedance-2-0-mini-uncensored`, `seedance-2-0-fast`, `seedance-2-5`, `seedance-2-5-uncensored`), **Seedream 5.0 Pro Uncensored** (`seedream-5-0-pro-uncensored`), **HappyHorse 1.1** (`happyhorse-1.1-t2v`, `happyhorse-1.1-i2v`, `happyhorse-1.1-r2v`), **Wan 3** (`wan3.0-video`), and **Wan 3.0 Enhanced** (`wan3.0-spicy-video`). They never fall back to SOGNI. Wan 3.0 Enhanced may use its separate launch-credit ledger before PAYG; that credit does not make the model subscription-covered.
- **Token choice stays yours:** selecting SOGNI (`--token-type sogni`) opts a job out of subscription coverage and spends SOGNI instead. Coverage applies when the active token is Spark.
By default the CLI sends no `billingMode`/coverage hint; the server decides coverage from the account's verified entitlement and the resolved model, and a subscription claim is never honored without a server-verified entitlement. `--billing-mode` makes the choice explicit when you need it: `subscription` requires Unlimited coverage (the job fails instead of spending tokens), `tokens` opts out of coverage and bills Spark/SOGNI, and `auto` states the default server behavior explicitly.
Do not use `tokenType: "spark"` by itself to determine that Spark paid for a render. `tokenType` is also the quote/accounting denomination for covered jobs. The server's separate `paymentModel` is authoritative: `subscription` means it skipped the artist Spark/SOGNI debit, while `paid_spark`, `free_spark`, and `sogni` identify token-funded paths. Some client result summaries do not expose `paymentModel`; in that case the payment source is unknown from that result alone. A request that completes successfully with `--billing-mode subscription` was covered—if coverage is unavailable, the server returns `4078` or `4080` instead of silently spending Spark.
With an active subscription, the CLI also skips its client-side "insufficient SPARK" pre-flight for covered video renders — a low token balance no longer blocks jobs the plan pays for. Vendor models and `--billing-mode tokens` keep the pre-flight, and the server remains authoritative either way.
### Rendering on Relaxed
Fast plan rendering pauses when the plan's daily or monthly fair-use capacity is used up (errors 4087 and 4089). Relaxed stays included, so you can keep rendering there:
```bash
sogni-agent --video --network relaxed --billing-mode subscription --detach --json \
-m minimax-h3-fastvideo-int8_i2v_turbo_2stage --ref start.png "A slow push-in"
sogni-agent --result <projectId> --wait -o clip.mp4 --json
```
Set `defaultNetwork` to `"relaxed"` in the plugin config to make it the default, or pass `--network fast` to override that for one run. Relaxed has far fewer workers, so a video can wait for hours, and anything unfinished 24 hours after you submit it is cancelled. Not every model runs there: `sogni-agent --list-models --model-network relaxed` shows which do for Unlimited members, and a job paid with Spark or SOGNI, or from a trial, can still be refused for a listed model. The CLI waits at least 30 minutes for a render on Relaxed by default. A render that takes longer keeps running, and `--result` collects it. With a configured default, a model with no Relaxed workers is refused rather than moved to Fast, except vendor models, which stay on Fast. Hosted chat and hosted workflows always run on Fast.
### Free-trial access
Trials include evaluation limits on generation volume, media size, and API access. Full plan limits apply once the trial converts to paid. Cancelling during the trial prevents the first charge and keeps trial access, with the same trial limits, until the original trial end date.
### Fair-use scheduling
Unlimited is fair-use, not unmetered. Published plan limits are:
- **Unlimited:** up to 4 concurrent image jobs and 1 concurrent video job, or 2 video jobs with fast/turbo models; queue up to 64 media, including up to 8 videos.
- **Unlimited Pro:** up to 16 concurrent image jobs and 4 concurrent video jobs, with standard MiniMax H3 limited to 2; queue up to 192 media, including up to 24 videos.
Actual throughput varies with demand, available Supernet capacity, and fair-use controls. Sustained high-volume or automated use may be delayed or rate-limited. Unlimited Pro receives higher subscription queue priority than Unlimited, and Premium Spark remains available for fastest paid priority. Subscription jobs cannot target specific workers.
### Billing states & cancellation
- **Active / trialing:** covered renders run normally.
- **Cancellation (paid):** Unlimited access continues until the end of the period already paid for; it simply does not renew.
- **Cancellation (during trial):** no charge is made, and trial access continues until the original trial end date. Cancelling does not extend the trial or make the account eligible for another one.
- **Grace / payment retry:** if a renewal payment fails, the provider retries it and **Unlimited access is paused** during the retry window — covered renders are declined with a renewal-retry error, and access resumes automatically once payment succeeds. You can keep rendering with Spark or SOGNI in the meantime.
- **Refunds:** mid-term refunds are not offered by default; App Store / Google Play purchases follow the store's refund process, and Stripe (web) refunds are handled by Sogni support.
### Priority Fast
`--priority` explicitly selects earlier Fast queue placement for a covered worker render on paid Unlimited or Unlimited Pro, behind Premium Spark. Daily and monthly fair-use consumption is 1.5×. It sets subscription billing and never falls back to token payment. Vendor models, Relaxed, hosted chat and hosted workflows are excluded. Existing render defaults stay the same.
### Subscription billing errors
When a generation cannot bill to the subscription, the CLI surfaces a structured error (`--json` includes `errorCode`, `errorCategory`, and a `hint`):
| Code | Meaning | What to do |
| --- | --- | --- |
| `4078` | Unlimited billing is not available for this generation (a vendor model that the subscription never covers, or no verified entitlement). | Use Premium Spark for vendor models (GPT Image 2 / Seedance / HappyHorse / Wan 3), or reconnect and retry for a transient entitlement read. |
| `4079` | Maximum queued jobs reached for the plan. | Wait for queued jobs to finish, then submit more. |
| `4080` | Renewal payment is being retried; Unlimited access is paused. | Pay for this render with Spark or SOGNI (`--token-type spark` / `sogni`) for now. **Do not auto-retry the covered job** — access resumes on its own once renewal succeeds. |
| `4081` | The feature requires a higher subscription plan. | Upgrade to Unlimited Pro. |
| `4087`, `4089` | The plan's daily or monthly Fast capacity is used up. | Render on Relaxed with `--network relaxed`, pay with Premium Spark using `--billing-mode tokens`, or wait for the reset. Don't retry on Fast. |
### Worker revenue share
Sogni workers that power subscription-covered jobs earn from a separate monthly pool — 51% of net subscription revenue — settled per UTC month and claimable in USDC on Base. Subscription jobs are excluded from the regular Spark/SOGNI token-economy leaderboard (they do not spend tokens) and accrue to this pool instead.
---
## Error Reporting & Output
- **Exit codes:** failures use a non-zero exit code with human-readable stderr.
- **Structured output:** add `--json` when an agent needs machine-parseable success/error data, or `--last` to inspect the last render. JSON failures include canonical `errorType`, `errorCategory`, and `retryable` fields where the shared runtime can classify the error.
- **Subscription billing errors:** subscription-billing failures carry `errorCode` `4078` / `4079` / `4080` / `4081` / `4087` / `4089`, `errorCategory: "subscription_billing"`, and an actionable `hint`. See [Subscription billing errors](#subscription-billing-errors) for what each means; in particular, do not auto-retry a `4080` (grace / renewal-retry) covered job — pay with Spark or SOGNI instead.
- **stdout stays parseable in `--json` mode:** progress lines, SSE workflow frames, and warnings go to stderr; stdout carries exactly one JSON object. `--last --json` wraps the record in a `{ "success": true, ... }` envelope and exits 1 with `errorCode: "NO_LAST_RENDER"` when nothing has been rendered yet.
- **Output files:** use `-o <path>` to save locally; otherwise the CLI prints a result URL.
- **Quiet mode:** `-q` / `--quiet` suppresses progress output without changing exit semantics.
- **Interrupts:** Ctrl-C exits with the conventional signal code and cleans up the CLI's temporary files.
---
## For AI Agents
This skill is designed to be loaded into agent runtimes as a first-class capability.
1. **Behavior contract — [`SKILL.md`](./SKILL.md)**
The canonical instructions for how the agent should call `sogni-agent`. Load this as the skill source.
2. **Install/setup hints — [`llm.txt`](./llm.txt)**
A condensed install/setup reference for agents that fetch `llm.txt` over HTTPS:
`https://raw.githubusercontent.com/Sogni-AI/sogni-creative-agent-skill/main/llm.txt`
3. **OpenClaw manifest — [`openclaw.plugin.json`](./openclaw.plugin.json)**
Plugin metadata, config schema, and defaults for OpenClaw-aware runtimes.
4. **Structured output — `--json`**
Use `--json` for machine-readable success/error payloads. Use `--last` to read the previous render's metadata.
5. **Agent-safe install/upgrade**
Prefer the `npm install -g` and `git -C "$DEST" pull --ff-only` paths above. Avoid generating clone-or-pull bootstrap scripts with `set -e`, `bash -c`, `sh -c`, or inline repository URLs — agent sandboxes correctly route those through approval and the install will stall.
6. **Verify with `doctor`**
After any install or upgrade, run `sogni-agent doctor --json` and confirm `"success": true` before reporting the install as working.
7. **Update notices for agents**
When a newer version exists, any command may print one advisory stderr line — `[sogni-agent] Update available: <current> -> <latest> ...` — at most once per day (stdout JSON is never touched). Agents should relay it to the user and offer `sogni-agent self-update`, or run `sogni-agent --snooze-update` if the user declines. Interactive TTY users get a banner instead. Each failed check carries a `detail` string with the fix.
8. **SSRF / URL safety**
The CLI validates every HTTP(S) media reference with an SSRF guard ([`ssrf-guard.mjs`](./ssrf-guard.mjs)) and re-validates each redirect hop on download. Localhost and private-network URLs are rejected; only public HTTPS references are forwarded as Seedance multimodal context.
---
## Development
Run the unit test suite (works without any Sogni credentials or private repos):
```bash
npm test
```
Paid integration tests require a separately authorized, bounded live run: explicitly set `SOGNI_INTEGRATION=1` when running `npm run test:integration` (requires a Sogni API key and submits real GPU jobs). Ordinary tests, `test:all`, CI and release checks stay offline.
Architecture notes, the private-runtime sync workflow, code-placement policy, and the release process live in [`CONTRIBUTING.md`](./CONTRIBUTING.md).
Issues and feature requests: [github.com/Sogni-AI/sogni-creative-agent-skill/issues](https://github.com/Sogni-AI/sogni-creative-agent-skill/issues).
---
## License
[MIT](./LICENSE) © Sogni AI
Personal LoRA imports and library management: read [Personal LoRAs](./references/personal-loras.md) for account-bound discovery, asynchronous import status, consent, compatible models, and rendering with owned adapters.