Sogni Creative Agent Skill

Sogni Creative Agent Skill gives agent runtimes and local tools access to Sogni image generation, image editing, photobooth face transfer, video generation, durable hosted workflows, personas, memories, balances, and model discovery.

It ships as the sogni-agent Node.js CLI plus a SKILL.md behavior file for Claude Code, OpenClaw, Hermes Agent, Manus, and other skill-based runtimes. Use it when you want an agent to create media through Sogni without hand-building every REST request.

Useful source files:

• GitHub repository
• SKILL.md - agent behavior rules and workflow guidance.
• README.md - human setup and CLI examples.
• llm.txt - short install/setup reference for agents.
• openclaw.plugin.json - OpenClaw plugin manifest and config schema.

The current local package is @sogni-ai/sogni-creative-agent-skill version 2.1.3.

#Install

For most users, install the CLI globally and point the agent runtime at the repository's SKILL.md:

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

For OpenClaw's published plugin:

openclaw plugins install sogni-creative-agent-skill

For a local OpenClaw checkout that you want to update continuously:

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

Do not install the repository root into OpenClaw with openclaw plugins install -l "$PWD". The generated .openclaw-link/ directory is the minimal plugin surface; the root contains development tests that OpenClaw safety scanning can block.

For Hermes Agent, Manus, Claude Code, or another skill-based runtime, use the root repository SKILL.md as the behavior source and invoke the globally installed sogni-agent CLI.

When upgrading from inside an agent runtime, prefer direct package-manager commands or an existing checkout update:

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

DEST="$HOME/Documents/git/sogni/sogni-creative-agent-skill"
git -C "$DEST" pull --ff-only
npm --prefix "$DEST" install

#Credentials

Create a Sogni account at app.sogni.ai, then get a Sogni API key from dashboard.sogni.ai by clicking your username. Save it to a local credentials file:

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 directly in the environment. Both direct CLI generation and hosted API modes (--api-chat, --api-workflow) require SOGNI_API_KEY.

#Common Commands

# Generate an image
sogni-agent -Q hq -o dragon.png "a dragon eating tacos"

# Edit an image
sogni-agent -c subject.jpg "add a neon cyberpunk glow"

# Photobooth face transfer
sogni-agent --photobooth --ref face.jpg "80s fashion portrait"

# Text-to-video
sogni-agent --video "A narrator says \"welcome to the story\" as ocean waves crash"

# Image-to-video
sogni-agent --video --ref cat.jpg "gentle camera pan"

# Image+audio-to-video
sogni-agent --video --ref cover.jpg --ref-audio song.mp3 \
  "music video with synchronized motion"

# Persona or voice identity with LTX native audio
sogni-agent --video --reference-audio-identity voice.webm \
  "NARRATOR: \"This is my voice.\""

# Direct music generation (instrumental or with lyrics)
sogni-agent --music --duration 30 "uplifting cinematic synthwave theme"

# Check balances
sogni-agent --balance

Use --json when an agent needs structured success/error output.

#Hosted API Modes

sogni-agent --api-chat calls /v1/chat/completions with Sogni creative-agent tools:

sogni-agent --api-chat \
  "Create a 4-shot product video concept for a red sneaker"

Useful chat controls:

sogni-agent --api-workflow starts a durable /v1/creative-agent/workflows run:

sogni-agent --api-workflow image-to-video \
  --video-prompt "The camera slowly pushes in as the sketch comes alive" \
  "A graphite robot sketch on a drafting table"

Use --workflow-input for exact hosted workflow JSON:

sogni-agent --api-workflow hosted-tool-sequence \
  --workflow-input ./workflow.json \
  --watch-workflow

Use --api-workflow storyboard-video to generate a storyline, render a single GPT Image 2 storyboard sheet, then pass that sheet into Seedance as the video reference. The -Q fast|hq|pro preset maps to GPT Image 2 low/medium/high quality for the storyboard sheet:

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"

Workflow management flags map to the REST workflow routes:

Local media flags such as -c, --ref, --ref-audio, and --ref-video stay on the direct CLI generation path. Hosted workflow calls should use hosted media URLs or Sogni artifact URLs inside --workflow-input JSON.

#Direct Media Workflows

For local multi-clip workflows, use the CLI's built-in FFmpeg wrappers (--extract-last-frame, --concat-videos, --concat-audio) instead of raw shell commands.

Seedance accepts public HTTPS image, video, and audio references as multimodal context. Localhost and private-network URLs are rejected before forwarding:

sogni-agent --video -m seedance2 --workflow t2v \
  --ref 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"

#Music Generation

Generate instrumental tracks or full songs with lyrics directly through --music:

# Instrumental
sogni-agent --music --duration 30 \
  "uplifting cinematic synthwave theme for a product launch"

# Song with lyrics, BPM, key, and output format
sogni-agent --music --lyrics "Rise with the morning light" --bpm 128 \
  --keyscale "C major" --output-format mp3 "bright indie pop chorus"

Music controls:

--audio remains the video-reference alias for --ref-audio; use --music or --generate-music for direct audio-only generation.

#Video Prompting

LTX-2.3 works best with dense natural-language scene descriptions, not short tag prompts. Write one continuous paragraph in present tense, describe one shot, include concrete objects and lighting, and keep motion continuous.

Example:

A medium cinematic shot frames a woman in her 30s standing in a rain-soaked neon alley at night, violet and amber signs reflecting across the wet pavement while warm steam drifts from street vents. She wears a dark trench coat with damp strands of black hair clinging near her cheek as light glances across the fabric texture and the brick walls behind her. She turns toward the camera and steps forward with measured focus, one hand tightening around the strap of her bag while rain taps softly on the metal fire escape and a distant train hum rolls through the block. The camera performs a slow push-in as her jaw sets and her breathing steadies, maintaining smooth stabilized motion and a tense urban-thriller mood.

For HD, 1080p, 4K, UHD, or high-resolution video requests, the skill prefers LTX-2.3 selectors:

Seedance selectors are useful for vendor-hosted video paths with public HTTPS references:

Seedance reference URLs must be public HTTPS URLs. Localhost and private-network URLs are rejected before forwarding.

#Sizing Rules

• WAN models use dimensions divisible by 16, minimum 480 px, maximum 1536 px.
• LTX models use dimensions divisible by 64. The CLI caps non-WAN video dimensions at 2048 px on the long side.
• Seedance runs at fixed 24 fps and supports 4-15 second clips.
• Other default/WAN video paths support up to 10 seconds; LTX and WAN animate workflows can support up to 20 seconds.
• --target-resolution <px> targets the short side while preserving the inherited aspect ratio.
• For i2v and any workflow using --ref or --ref-end, the wrapper resizes the reference with aspect-fit and uses the resized dimensions as final video size.
• With local refs, sogni-agent auto-adjusts nearby sizes to satisfy model divisibility. Use --strict-size to fail and print a suggested size instead.

#Quality And Models

Use -Q / --quality for images instead of memorizing model IDs:

The fast and hq presets use Z-Image Turbo. For image editing, use Qwen Image Edit 2511 Lightning or Flux.2.

Recommended explicit selectors:

--token-type auto tries Spark first and retries with SOGNI if Spark balance is insufficient:

sogni-agent --token-type auto "a dragon eating tacos"

#Personas, Memory, And Personality

Personas save named people with reference photos and optional voice clips:

sogni-agent --persona-add "Mark" --ref face.jpg --relationship self \
  --description "30s male, brown hair"

sogni-agent --persona-add "Sarah" --ref sarah.jpg \
  --relationship partner --voice-clip voice.webm

sogni-agent --persona "Mark" -o hero.png "superhero in dramatic lighting"
sogni-agent --video --persona "Sarah" "SARAH: \"This is my voice.\""
sogni-agent --persona-list

Personas are stored under ~/.config/sogni/personas/.

Memories store persistent preferences:

sogni-agent --memory-set preferred_style "watercolor and soft lighting"
sogni-agent --memory-list

Memories are stored at ~/.config/sogni/memories.json.

Personality stores custom agent instructions:

sogni-agent --personality-set "Be concise, always use cinematic lighting"
sogni-agent --personality-get
sogni-agent --personality-clear

Personality is stored at ~/.config/sogni/personality.txt.

#Paths And Overrides

Defaults live under ~/.config/sogni/ for credentials, last-render metadata, personas, memories, and personality.

Useful overrides:

#Troubleshooting

Run the complete CLI reference with:

sogni-agent --help