Sogni Creative Agent Skill

Give the AI agent you already use a creative studio. Install the Sogni Creative Agent Skill, then ask in everyday language for an image, an edit, a video, a song, a storyboard, or a complete multi-step media workflow. The agent handles the model choices and calls Sogni's decentralized GPU network through the sogni-agent CLI.

It works with Claude Code, OpenAI Codex, Hermes Agent, OpenClaw, Manus and other SKILL.md-aware runtimes. It can also run as a local MCP server in Claude Desktop or Codex.

With the skill, your agent can:

• Generate, edit, inpaint, restore, restyle and refine images, including identity-preserving edits, photobooth portraits, multiple angles and seamless patterns.
• Create video from text, images, first/last frames, audio, or a source video with LTX-2.5, while retaining LTX-2.3 for rollback and its voice ID/transition/10Eros integrations.
• Make instrumental music or complete songs with lyrics, BPM, key and time-signature controls.
• Build storyboards, image-folder reels, seamless loops and durable workflows that can be watched, resumed or cancelled.
• Remember personas and creative preferences across sessions, discover live models and reuse the previous render.

Prefer to create in a browser? Sogni Chat needs no installation and includes more than 30 creative tools plus 400 free credits each month. Open a tab and start describing what you want.

#Build polished ads with your agent

This is especially powerful for ads and product launches. A complete spot can begin with one real product photo:

1. Drop a reference. The agent uses the product's shape, color and branding as visual anchors.
2. Get a storyboard. Describe the ad and the agent plans the beats, timecodes, copy and voice-over, then renders a storyboard sheet.
3. Render the ad. Each panel becomes a keyframe that Seedance can animate with motion, pacing and native audio.

Saved personas add consistent faces and voices for virtual influencers, product demos and repeatable UGC campaigns.

For more exact post-production, let your agent plan the concept and copy, use Sogni to generate product stills, character shots, video clips and music, then finish the piece in a code-based compositor such as Remotion or HyperFrames.

Sogni supplies the generative media; Remotion or HyperFrames gives the agent precise control over typography, product UI, logos, calls to action, timing and aspect-ratio variants. One agent can take a brief from idea to a rendered family of 16:9, 9:16 and 1:1 ads without a manual timeline-editing handoff.

#Quick start: ask your agent

#1. Tell your agent to install it

In a current skill-aware agent, this should be all you need to say:

Install the Sogni Creative Agent Skill.

The agent should find the official package, install the CLI and skill for its runtime, request any necessary permissions, and verify the result. If it needs a source, give it the repository explicitly:

Install the Sogni Creative Agent Skill from:
https://github.com/Sogni-AI/sogni-creative-agent-skill

This conversational install works well in Claude Code, OpenAI Codex, Hermes, OpenClaw, Manus and other agents that can discover skills and run shell commands.

#2. Add your API key when asked

Sign in to dashboard.sogni.ai, open the account menu and copy your Sogni API key. Let the installer save it, or set SOGNI_API_KEY in the agent's environment. Never commit it to a project.

#3. Prefer the terminal? Run the installer

Start Claude Code, Claude Desktop, Codex or Hermes once so its local configuration directory exists, then run:

npx setup-sogni-agent-skill

The installer detects supported local runtimes, installs the sogni-agent CLI, registers the skill or local MCP server and prompts for your API key. It does not configure OpenClaw; use the OpenClaw steps below. Skip this step if your agent already completed the conversational install.

#4. Reload your agent and verify

Start a new Claude Code or Codex session, fully quit and reopen Claude Desktop, or run /reset in Hermes. Then check the installation:

sogni-agent doctor

For an automated agent, use sogni-agent doctor --json and confirm that the response contains "success": true.

#5. Ask for something

Try one of these in your agent:

• “Generate a cinematic product photo of my red sneaker on black glass.”
• “Keep this person's identity, but change the wardrobe and location.”
• “Animate these two images into a smooth transition.”
• “Turn this image folder into a seamless, music-backed loop.”
• “Create a 15-second vertical launch ad, then finish the titles in Remotion.”
• “Make a 30-second synthwave instrumental for this product video.”

You can also test the CLI directly:

sogni-agent -Q fast -o ./first-sogni-image.png "a friendly robot painting a mural"

Final files should use a relative -o path so they remain in your current project instead of a temporary directory.

#Requirements

• Node.js 22.11.0 or newer.
• A Sogni API key from dashboard.sogni.ai.
• macOS, Linux or Windows.
• ffmpeg and ffprobe are optional for generation, but required for local video inspection, frame extraction, concatenation, audio remixing, 360 assembly and Loop Maker finishing. Use FFMPEG_PATH and FFPROBE_PATH if they are not on PATH.

#Installation options

Ask your agent to “Install the Sogni Creative Agent Skill” before copying commands manually. The one-command installer is the easiest fallback. If you prefer a native plugin or need to configure one runtime only, use the matching section below.

The installer can target several runtimes at once:

npx setup-sogni-agent-skill --only=claude,codex,hermes

Selected local runtimes must have been started once so their configuration directories exist.

#Install the current CLI manually

Use this when an agent runtime already knows how to load a SKILL.md, or when you want npm's current stable CLI release:

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

Then configure the runtime to load the repository's SKILL.md and call the globally installed sogni-agent executable. Do not invoke node sogni-agent.mjs from a copied skill directory; some installers keep the skill metadata and executable in different locations.

#Claude Code

The one-command installer writes a personal skill to ~/.claude/skills/. As an alternative, install the CLI globally and run these two commands inside Claude Code:

/plugin marketplace add Sogni-AI/sogni-creative-agent-skill
/plugin install sogni-creative-agent@sogni

Choose either the Claude Code plugin or the personal skill installed by npx, not both. Registering both creates duplicate skills and wastes agent context.

#OpenAI Codex

The one-command installer writes the full skill to ~/.codex/skills/sogni-creative-agent-skill/. The repository also ships a namespaced Codex plugin with the focused Creative Agent and Loop Maker skills:

npm install -g @sogni-ai/sogni-creative-agent-skill@latest
codex plugin marketplace add Sogni-AI/sogni-creative-agent-skill
codex plugin add sogni-creative-agent@sogni

Start a new Codex session after installing. You can then ask normally, invoke $sogni-creative-agent:loop-maker ./images directly, or type @ in the Codex app and choose Sogni Loop Maker.

Choose the Codex plugin or the personal ~/.codex/skills/ install, not both. The package also includes an MCP server for teams that prefer MCP tools; see the repository README for that optional setup.

#Hermes Agent

Hermes can install the dedicated, security-scannable skill bundle directly from its Skills Hub (via skills.sh):

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

Run /reset in Hermes afterward so the new session loads it. The Hub bundle contains only the skill instructions and references that Hermes scans; the npm package supplies the separate sogni-agent-hermes CLI used to perform media work.

For a combined CLI and personal-skill setup, the existing installer remains available:

npx setup-sogni-agent-skill --only=hermes

That installer writes the skill under ~/.hermes/skills/media/sogni-creative-agent-skill/. Choose either the Skills Hub bundle or this personal-skill install, not both, to avoid loading duplicate instructions.

#Claude Desktop

Claude Desktop uses the package's local MCP server rather than loading SKILL.md directly:

npx setup-sogni-agent-skill --only=desktop

Fully quit and reopen Claude Desktop. Generated images can display inline in chat. You can instead download the sogni-creative-agent.mcpb bundle from GitHub Releases and install it through Settings → Extensions. Do not use both methods, or Claude Desktop will show duplicate Sogni tools.

#OpenClaw

The general installer does not configure OpenClaw. Install the global CLI, then choose one OpenClaw registration:

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

# ClawHub skill
openclaw skills install sogni-creative-agent-skill

# Or the published code plugin; note the required npm: prefix
openclaw plugins install npm:@sogni-ai/sogni-creative-agent-skill

For a continuously updated local checkout, link the generated .openclaw-link/ directory rather than the repository root:

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

The root contains development files that OpenClaw's safety scanner may reject. .openclaw-link/ is the intentionally minimal plugin surface.

#ChatGPT Custom GPT

Print the current Custom GPT setup instructions with:

npx setup-sogni-agent-skill --only=chatgpt

This embeds prompt-side skill behavior in a Custom GPT. ChatGPT on the web cannot execute the sogni-agent CLI on your computer, so local rendering and file access are not available through this route alone.

#Manus and other SKILL.md runtimes

Give the agent the GitHub repository, ask it to install the skill, and make the root SKILL.md available as its behavior source. The runtime also needs shell access to the globally installed sogni-agent command.

#Credentials

The one-command installer prompts for the key. For manual setup, save it in a private 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 export SOGNI_API_KEY in the runtime environment instead. Both direct generation and hosted modes such as --api-chat, --durable-chat and --api-workflow require the key.

Never put a Sogni API key in a project file, prompt, skill file, manifest or documentation example committed to source control.

#Verify, update or remove the skill

Run the health check immediately after an install or upgrade, or when a command fails:

sogni-agent doctor
sogni-agent doctor --json

doctor checks Node, credentials and file permissions, configuration-directory access, ffmpeg, live authentication, account status and version freshness. It makes a live network request, so it is not intended as a preflight before every generation.

Update the global CLI with:

sogni-agent self-update
sogni-agent --whats-new

You can also use npm install -g @sogni-ai/sogni-creative-agent-skill@latest. A once-daily update notice may appear on stderr after a command; it is advisory and does not change JSON stdout.

To remove installed runtime files and the global CLI while keeping personas, memories and credentials:

npx setup-sogni-agent-skill --uninstall --remove-cli

Add --purge only when you also want to remove ~/.config/sogni/. The uninstaller first writes a timestamped tar backup beside that directory. Treat the backup as sensitive because it contains your API key.

#Everyday commands

sogni-agent --help is the canonical full flag reference. These examples cover the most common jobs.

#Images and image editing

# Quality presets choose the model, steps and size
sogni-agent -Q fast -o ./concept.png "a premium watch on volcanic glass"
sogni-agent -Q pro -o ./hero.png "a premium watch on volcanic glass"

# Generate diverse variants in one call
sogni-agent -n 3 -o ./cars.png "a {red|blue|green} sports car at dusk"

# General source-preserving edit
sogni-agent -c ./product.jpg -o ./edited.png \
  "replace the background with a bright modern kitchen"

# Preserve a person's or character's identity while changing the scene
sogni-agent -c ./person.jpg -m krea2_identity_edit_v1_2 -o ./portrait.png \
  "same identity, editorial wardrobe, warm studio lighting"

# Create a new portrait from a face reference
sogni-agent --photobooth --ref ./face.jpg -o ./portrait.png \
  "1980s fashion editorial"

# Reuse the previous result without finding its path
sogni-agent --last-image -o ./refined.png "make the lighting more dramatic"

Identity-preserving Krea edits accept one or two references. With two, pass the base scene first and the person, outfit, pose, detail or style reference second. General Qwen edits accept up to three context images; gpt-image-2 accepts up to 16.

Krea 2 Turbo also supports up to eight ordered LoRAs through repeatable --lora and --lora-strength options. Use sogni-agent --list-models or --search-models <query> to inspect the current catalog rather than guessing an ID.

For product turnarounds and alternate viewpoints:

# One controlled angle
sogni-agent --multi-angle -c ./product.jpg --azimuth front-right \
  --elevation eye-level --distance medium -o ./angle.png \
  "clean studio product photo"

# Eight azimuths; add --angles-360-video to assemble a looping MP4
sogni-agent --angles-360 -c ./product.jpg -o ./turnaround.png \
  "clean studio product photo"

For wallpaper, fabric, game textures or other edge-to-edge repeating art, ordinary generation is not enough. The skill includes a tested Krea 2 seamless-tiling recipe and renders several candidates because tiling is probabilistic; ask the agent for a “seamless repeating pattern” and it will load the detailed tiling guidance.

#Video and animation

# Text-to-video
sogni-agent --video -o ./launch.mp4 \
  "A polished red sneaker rests on black glass as a narrow white spotlight sweeps across the sole and the camera makes one slow push forward."

# Animate one image (single-image i2v defaults to WAN 2.2 LightX2V)
sogni-agent --video --ref ./product.png -o ./product-motion.mp4 \
  "The camera arcs gently around the product while the background light shifts."

# Animate directly from a first frame to a last frame (defaults to LTX-2.5 FLF)
sogni-agent --video --ref ./first.png --ref-end ./last.png \
  -o ./transition.mp4 "A fluid cinematic transformation connects the two scenes."

# Face lip-sync from an image and speech recording
sogni-agent --video --ref ./face.jpg --ref-audio ./speech.m4a \
  -m wan_v2.2-14b-fp8_s2v_lightx2v -o ./talking-head.mp4 \
  "Natural lip sync and subtle head movement."

# Seedance 2.0 native 4K and audio
sogni-agent --video -m seedance2 --target-resolution 2160 --duration 8 \
  -o ./reveal-4k.mp4 "A polished product reveal with native ambient sound."

# HappyHorse reference-to-video with consistent subjects
sogni-agent --video -m happyhorse-1.1-r2v \
  -c ./subject.png -c ./location.png -o ./scene.mp4 \
  "Blend the references into one continuous shot with native sound."

When the skill selects an LTX model, it expands short requests into a dense, continuous-shot prompt. If you call LTX directly, describe the subject, lighting, one action thread, camera motion, atmosphere and any spoken dialogue in one flowing paragraph.

#Video editing and multimodal references

# Detail and remaster an existing clip with LTX-2.3 V2V
sogni-agent --video --workflow v2v --ref-video ./input.mp4 \
  -m ltx23-22b-fp8_v2v_distilled --control-type detailer \
  -o ./remastered.mp4 "Preserve the motion and improve fine detail."

# Extend the canvas without cropping
sogni-agent --video --workflow v2v --ref-video ./vertical.mp4 \
  -m ltx23-22b-fp8_v2v_distilled --control-type outpaint \
  --outpaint-position center --outpaint-aspect-ratio 16:9 \
  -o ./widescreen.mp4 "Continue the environment naturally into the new space."

# Regenerate a masked region; white pixels in the mask are replaced
sogni-agent --video --workflow v2v --ref-video ./input.mp4 \
  -m ltx23-22b-fp8_v2v_distilled --control-type inpaint \
  --mask ./mask.png -o ./replaced.mp4 "Replace the sign with a clean blank panel."

Seedance supports two reference styles. Use --ref and --ref-end for canonical first and last frames, or repeat -c for loose image references and name them in the prompt as @Image1, @Image2 and so on. Seedance can also accept public HTTPS video and audio references. Localhost and private-network URLs are rejected before forwarding.

Use --video-start and --duration to select a source-video window, or --audio-start and --audio-duration for an audio window. Add --looping for an A→B→A i2v loop.

#Image-folder reels and Loop Maker

Use SourceReel when you want separate animated holds and bridge transitions:

# Preview the plan without spending on renders
sogni-agent --source-reel ./images --reel-plan-only

# Render and stitch the reel
sogni-agent --source-reel ./images --reel-output ./reel.mp4 \
  --reel-image-seconds 3 --reel-transition-seconds 3

Use Sogni Loop Maker when you want a polished music-backed loop that visually removes duplicates and renders one direct first-frame/last-frame clip for each image pair. Ask your agent to “Use Sogni Loop Maker on this folder,” run /sogni-creative-agent:loop-maker in Claude Code, or invoke $sogni-creative-agent:loop-maker ./images in Codex.

Loop Maker preserves the original images, closes the last-to-first transition, creates a soundtrack and verifies the finished file. Remotion or HyperFrames is optional for a later pass when the ad needs timed typography, brand overlays or compositor effects.

#Local video finishing

Use the CLI's safe wrappers instead of writing raw ffmpeg commands:

sogni-agent --extract-first-frame ./clip.mp4 ./first.png
sogni-agent --extract-frame-at ./clip.mp4 2.5 ./middle.png
sogni-agent --extract-last-frame ./clip.mp4 ./last.png
sogni-agent --verify-video ./clip.mp4
sogni-agent --concat-videos ./joined.mp4 ./one.mp4 ./two.mp4
sogni-agent --remix-audio ./joined.mp4 ./final.mp4 --bed-audio ./music.mp3 --audio-loop

Concatenation normalizes mismatched frame rates, sizes, sample aspect ratios and pixel formats, and supplies silent audio where needed. --remix-audio stream-copies the picture and re-encodes only the audio.

#Music

# Instrumental; MP3 by default
sogni-agent --music --duration 30 -o ./launch-theme.mp3 \
  "uplifting cinematic synthwave for a product launch"

# Full song with lyrics and musical controls
sogni-agent --music --music-model sft --duration 45 \
  --lyrics "Rise with the morning light" --bpm 128 --keyscale "C major" \
  --timesig 4 --output-format mp3 -o ./song.mp3 \
  "bright indie pop chorus"

--music-model turbo maps to ACE-Step 1.5 XL Turbo, the default. sft maps to the XL quality variant with stronger lyric handling. Durations can range from 10 to 600 seconds; output can be MP3, FLAC or WAV.

#Personas, memory and personality

Save a named person with reference photos and an optional voice clip:

sogni-agent --persona-add "Mark" --ref ./mark.jpg --relationship self \
  --description "brown hair, usually wears dark tailored jackets"

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

sogni-agent --persona "Mark" -o ./hero.png \
  "a cinematic superhero portrait"

sogni-agent --video --persona "Sarah" -o ./intro.mp4 \
  'SARAH: "Welcome to the launch."'

Store standing preferences and agent instructions:

sogni-agent --memory-set preferred_style "clean editorial lighting"
sogni-agent --memory-list
sogni-agent --personality-set "Be concise and use cinematic lighting."
sogni-agent --personality-get

Personas, memories and personality remain under ~/.config/sogni/ and are shared by integrations on the same machine.

#Direct generation or hosted workflows?

Let the calling agent plan the work whenever it already understands the request. Pick the execution mode that matches the job:

#Durable workflows

Submit an exact step graph authored by your agent:

sogni-agent --api-workflow --workflow-input @./plan.json --watch-workflow

Or use the built-in storyboard-to-video preset:

sogni-agent --api-workflow storyboard-video --storyboard-frames 6 \
  -Q hq "Create a 9:16 bakery launch video with a neon window reveal"

The preset creates a storyline, renders a GPT Image 2 storyboard sheet and passes it to Seedance for video generation. Use --workflow-max-cost, --confirm-cost and --workflow-idempotency-key for cost and retry control. Manage runs with --list-workflows, --get-workflow, --workflow-events, --resume-workflow and --cancel-workflow.

#Hosted chat

sogni-agent --api-chat \
  "Turn the attached product photo into a launch concept" --ref ./product.jpg

SOGNI_SKILL_USE_SDK_TRANSPORT=1 sogni-agent --durable-chat \
  "Create a launch campaign and animate the hero clip"

Hosted chat lets Sogni's model own the server-side tool loop. Local file references used in hosted modes are uploaded to Sogni media storage so the backend can retrieve them. Prefer direct CLI generation when that extra hosted-media persistence is unnecessary.

Direct generation still sends prompts and required reference media to Sogni's network for rendering; “direct” means that it avoids the additional hosted chat/workflow planning and media-storage layer, not that GPU generation happens entirely on the local machine.

Useful hosted-chat controls:

Current releases attach privacy-safe host attribution to Sogni-owned requests so the service can distinguish Codex, Claude Code, Claude Desktop, Hermes and OpenClaw surfaces. It can include framework, surface, workload and semantic-operation labels; it does not include prompts, user file paths, credentials or headers sent to presigned uploads.

#Local contract and storyboard diagnostics

Platform integrators can inspect the public skill runtime without making a generation request:

These are developer diagnostics, not end-user rendering commands.

#Models and quality

The media catalog changes faster than a documentation page. Search the live catalog before hard-coding a model:

sogni-agent --list-models
sogni-agent --search-models krea
sogni-agent --list-models --model-media video
sogni-agent --list-models --model-tag uncensored

For image generation, quality presets are the friendliest default:

Use explicit model selectors only when the job needs a particular capability:

The current skill also exposes ltx23-eros as an explicit-only LTX-2.3 image-to-video option for lawful adult use. It requires an input image, --no-filter, and a worker with at least 30 GB of GPU memory. The agent never chooses it merely because another model rejected a request; the user must explicitly request the model and acknowledge disabling the filter.

#Video sizing notes

• WAN dimensions must be divisible by 16 and remain between 480 and 1536 pixels.
• LTX dimensions must be divisible by 64; the wrapper caps the long side at 2048 pixels.
• Full Seedance supports 4–15 second clips and native 4K through --target-resolution 2160. Seedance Mini and Fast remain on the lower-resolution 720p path.
• HappyHorse supports 3–15 second 720p/1080p clips at 24 fps with synchronized native audio.
• The CLI auto-adjusts local reference sizes to nearby valid dimensions. Add --strict-size when you prefer a failure with a suggested size.

#Billing and Sogni Unlimited

Run this to see balances and the available subscription state:

sogni-agent --json --balance

An active Sogni Unlimited plan covers eligible Sogni-hosted Supernet image, video and music generation under a fair-use policy. External-vendor models — GPT Image 2, Seedance 2.0 and HappyHorse 1.1 — always require Premium Spark and are not covered by Unlimited.

Useful controls:

• --token-type auto tries Spark first and can retry eligible native Sogni models with SOGNI tokens when Spark is insufficient.
• --billing-mode subscription requires Unlimited coverage and fails instead of silently charging tokens when coverage is unavailable.
• --billing-mode tokens opts out of subscription coverage for that request.

Do not infer that Spark was charged only because a result says tokenType: "spark"; that is the quote denomination. paymentModel: "subscription" is the authoritative sign that an eligible render used Unlimited coverage.

For current plans, fair-use behavior and Spark Packs, see Pricing. For durable workflow limits and approvals, see Billing & Cost Control.

#Useful paths and overrides

The CLI leases distinct app IDs automatically when several agents run at once. Preserve ~/.config/sogni/app-ids/ between sessions; repeatedly creating new IDs can hit the account limit.

#Troubleshooting

Machine-readable failures use one JSON object on stdout when --json is set:

{
  "success": false,
  "error": "Reference image size is invalid for this video model.",
  "errorCode": "INVALID_VIDEO_SIZE",
  "errorType": "PARAMETER_INVALID",
  "errorCategory": "schema_validation",
  "retryable": false,
  "hint": "Use the suggested width and height, or omit --strict-size."
}

Progress, warnings and workflow events go to stderr, so stdout remains safe for an agent to parse.

#Source and deeper references

• GitHub repository — source, issues and releases.
• npm package — the published sogni-agent CLI and stable release metadata.
• SKILL.md — behavior and routing rules loaded by skill-aware agents.
• README.md — complete installation and CLI examples.
• llm.txt — condensed setup guidance for agents.
• references/ — detailed guides for prompting, models, video editing, hosted APIs, Loop Maker, personas and seamless tiling.
• skills/README.md — focused per-capability skill surface.
• CHANGELOG.md — release-by-release changes.