Developer Tutorials

Hands-on recipes for building with the Sogni SDK and Supernet — text-to-image, video, LLM chat, vision, tool calling, durable creative workflows, and full apps. Every recipe links to runnable source in Sogni-AI/sogni-client/examples so you can clone, set credentials, and node script.mjs in under a minute.

If you're new, start with the Sogni SDK overview for installation and authentication, then come back here for working recipes.

#Quickstart -- Run the example pack

The sogni-client/examples folder is the fastest way to feel the SDK. The examples are written in Node.js — Sogni itself is language-agnostic, but Node is the most convenient way to try the SDK end-to-end.

Prerequisite: Node.js 18+ (with npm). If node --version errors out, install Node first.

Clone the repo, build the SDK once at the root, then run any example:

git clone https://github.com/Sogni-AI/sogni-client.git
cd sogni-client
npm install
npm run build

cd examples
npm install
echo "SOGNI_API_KEY=your_api_key_here" > .env

The root npm install + npm run build step is required because the examples import the SDK from the parent build output, not from npm. Skip it and you'll see "Cannot find module" errors when running any script.

Every script supports --help, an interactive picker if you omit arguments, and saves output to ./output/. Most workflow scripts print a cost estimate and wait for confirmation before billing tokens.

#Image recipes

#Text-to-image with model switching

workflow_text_to_image.mjs — Z-Image Turbo, Z-Image, Flux.1 Schnell, and Flux.2 Dev behind one CLI.

node workflow_text_to_image.mjs "A cyberpunk city" --model z-turbo
node workflow_text_to_image.mjs "Professional portrait" --model flux2 --seed 12345
node workflow_text_to_image.mjs "A serene sunset" --model z-image --batch 4

What to learn: model selection by alias, --seed for reproducibility, batch generation, custom samplers/schedulers.

#Reference-guided edits with Qwen Image Edit

workflow_image_edit.mjs — pass 1–3 context images and a prompt; the model uses the references to guide style and content.

node workflow_image_edit.mjs "portrait in this style" --context ref.jpg
node workflow_image_edit.mjs "modern artwork" --context ref1.jpg --context2 ref2.jpg --model qwen-lightning

What to learn: context-image limits per model (Qwen 3, Flux.2 Dev 6, GPT Image 2 16), --model qwen-lightning for fast 4-step edits, --style and --negative prompts.

#Promise vs event-driven generation

Two short scripts that show the two ways to drive a project:

promise_based.mjs — await project.waitForCompletion(). Clean for batch jobs.
event_driven.js — project.on('progress', …), 'jobCompleted', 'completed', 'failed'. Use when you need real-time UI updates.

node promise_based.mjs   # async/await flow
node event_driven.js     # event-listener flow

#Video recipes

All video models run on the fast network. The Wan 2.2 14B family has Speed/LightX2V (4–8 steps) and Quality (20–40 steps) variants — start with Speed while iterating.

#Text-to-video

workflow_text_to_video.mjs

node workflow_text_to_video.mjs "A serene ocean wave at sunset"
node workflow_text_to_video.mjs "Dancing robots" --fps 32 --duration 5

#Image-to-video (animate a still)

workflow_image_to_video.mjs — auto-detects image dimensions, supports first/last-frame keyframes.

node workflow_image_to_video.mjs --image test-assets/placeholder.jpg "camera pans left slowly"

#Sound-to-video (lip sync)

workflow_sound_to_video.mjs — frame count is calculated from the audio. Supports .mp3, .m4a, .wav.

node workflow_sound_to_video.mjs --model lightx2v

#Video-to-video: motion transfer & character replacement

workflow_video_to_video.mjs — Animate-Move (transfer motion to a subject), Animate-Replace (swap a subject while preserving motion), and LTX-2.3 V2V ControlNet (canny, pose, depth, detailer).

node workflow_video_to_video.mjs --video source.mp4   # Animate-Move / Animate-Replace
node workflow_video_to_video.mjs "restyle as watercolor" --video source.mp4 --model ltx23-v2v-distilled

#Partner Seedance video (external provider)

workflow_partner_seedance_video.mjs — covers T2V, I2V, IA2V, V2V on Seedance 2.0 and 2.0 Fast, with Seedance-style role tags (@Image1, @Video1, @Audio1).

node workflow_partner_seedance_video.mjs                                                  # guided picker
node workflow_partner_seedance_video.mjs "A glass whale through a neon city" --fast --duration 4
node workflow_partner_seedance_video.mjs "cinematic reveal" --context test-assets/placeholder.jpg

Seedance 2.0 requires credit-card purchased Premium Spark; --no-execute prints the request without billing.

#Multi-angle and batched workflows

workflow_multiple_angles.mjs — fan out a single subject into multiple camera angles.
workflow_batch_i2v.mjs — animate a directory of images in one run.

#LLM chat, vision, and tool calling

The SDK ships an OpenAI-compatible chat surface running on the Supernet. The default model qwen3.6-35b-a3b-gguf-iq4xs handles text, vision, reasoning, and tool calling.

#Single-turn and streaming chat

node workflow_text_chat.mjs "What is the meaning of life?"
node workflow_text_chat_streaming.mjs "Tell me a story about a cat"

workflow_text_chat.mjs returns the full message; workflow_text_chat_streaming.mjs streams tokens and prints tokens/sec at the end.

#Multi-turn REPL with `/system`, `/think`, `/stats`

workflow_text_chat_multi_turn.mjs — persistent history, in-chat slash commands, optional reasoning mode.

node workflow_text_chat_multi_turn.mjs --system "You are a pirate. Respond in pirate speak."

#Vision: describe, OCR, compare images

workflow_text_chat_vision.mjs — load JPEG/PNG/WebP/GIF up to 20 MB. Built-in slash commands: /describe, /ocr, /objects, /analyze, /compare <path>.

node workflow_text_chat_vision.mjs --image photo.jpg

#Function calling (weather, time, math)

workflow_text_chat_tool_calling.mjs — the model decides which tool to invoke; you execute it locally and feed the result back.

node workflow_text_chat_tool_calling.mjs "What's the weather in Austin, TX?"
node workflow_text_chat_tool_calling.mjs "Convert 72°F to celsius and what's 15% of 249.99?"

The recipe ships four ready-made tools (get_weather, get_time, convert_units, calculate) — copy the pattern for your own.

#Generate media from natural language (Sogni Platform Tools)

The big one. Let an LLM detect "make me a cyberpunk city" / "compose a jazz song" / "animate this image", enhance the prompt, and call Sogni's media APIs server-side.

#Hosted creative-tools surface

workflow_text_chat_sogni_tools.mjs and workflow_creative_agent_tools.mjs — the LLM is given the full 24-tool family (generation, image adapters, video composition, prompt/script/lyrics planning) via chat.hosted.create().

node workflow_text_chat_sogni_tools.mjs "Create an image of a cyberpunk city at night"
node workflow_text_chat_sogni_tools.mjs "Generate a video of ocean waves at sunset"
node workflow_text_chat_sogni_tools.mjs "Compose a jazz song about the rain"
node workflow_creative_agent_tools.mjs "Create an orbit video plan for a crystal perfume bottle"
node workflow_creative_agent_tools.mjs "Plan a cyberpunk skyline video" --tools creative-tools --no-execute

Pick the tool surface via sogni_tools:

"creative-tools" (default) — generation + image adapters + composition + planning.
"creative-agent" — the same plus workflow control and asset-manifest tools.
false — text-only.

#Durable creative workflows (survive disconnect)

workflow_creative_agent_workflows.mjs — the sogni.workflows namespace. Workflows persist server-side; you can resume, reseed, replay events, and inspect from a second client.

node workflow_creative_agent_workflows.mjs "A chrome monorail over neon gardens" --watch
node workflow_creative_agent_workflows.mjs "A kinetic product teaser" --video-model wan22 --duration 5 --watch
node workflow_creative_agent_workflows.mjs --list
node workflow_creative_agent_workflows.mjs --stream <workflowId>

Core methods: start, list, get, events, streamEvents, resume (release waiting_for_user), reseed, cancel, and templates.{list, get, create, update, delete, fork}.

Reach for sogni.workflows when you need durable state, SSE replay, multi-step plans, request-level media references, or cross-session observability. Reach for chat.hosted.create() when you want a one-shot natural-language → media call. See the durable workflows reference for the full contract.

#Embed Sogni in a web app

examples/express — a minimal Express server that exposes the SDK to a browser front-end. Use it as the skeleton for any web product.

cd examples/express
npm install
node index.js   # http://localhost:3000

What it teaches: keeping credentials server-side, proxying generation calls, surfacing progress events to the browser.

#Build a SuperApp — open-source case studies

Three production-quality Sogni apps you can fork. Each shows a different integration shape.

#Telegram & Discord sticker bot

Sogni-AI/sogni-sticker-bot — battle-tested bot that turns chat prompts into stickers in Telegram and Discord. Also published as @sogni-ai/sogni-sticker-bot on npm.

What to learn:

Connecting one Sogni session to two chat platforms simultaneously.
Per-server whitelist/blacklist admin commands.
Background removal + sticker post-processing on top of the generated image.
!repeat to re-roll the previous prompt with a new seed.
Persisting bot state in a writable data directory.

If you want a working "users chat → AI image" loop in a familiar product surface, start here.

#Generate inside any n8n workflow

Sogni-AI/n8n-nodes-sogni — community node bringing Sogni image, video, image-edit, and LLM chat into n8n. Built on @sogni-ai/sogni-intelligence-client.

What to learn:

A no-code integration pattern — useful as a reference even if you write code, because the node JSON maps 1:1 to SDK parameters.
All 15 ControlNet types (canny, pose, depth, openpose, instantid, …) exposed as inputs.
13 ready-to-import example workflows including LTX-2.3 V2V, WAN Animate-Replace with SAM2, Qwen image-edit + Telegram posting, and an LLM-powered "describe this upload" form.
How to wire generation into Discord webhooks, Google Drive, social media, or scheduled cron jobs.

Install with npm install n8n-nodes-sogni in your n8n instance, then check examples/ in the repo.

#Drop Sogni into any agent runtime

Sogni-AI/setup-sogni-agent-skill — npx installer for the Sogni Creative Agent Skill. Installs the sogni-agent CLI globally and registers a SKILL.md into every supported agent runtime in one command.

npx setup-sogni-agent-skill

Supported runtimes: Claude Code, OpenAI Codex CLI, Hermes Agent, ChatGPT (web). Once installed, any of those agents can call Sogni's full creative surface via the skill — no integration code on your side.

Flags worth knowing:

npx setup-sogni-agent-skill --only=claude,codex          # restrict runtimes
npx setup-sogni-agent-skill --yes --no-credentials       # CI-safe
npx setup-sogni-agent-skill --version=2.3.0              # pin a release
npx setup-sogni-agent-skill --uninstall --remove-cli     # clean removal

What to learn: per-runtime install paths, marker-file based upgrades, the auth shape (SOGNI_API_KEY env or ~/.config/sogni/credentials).

See also Creative Agent Skill in the docs.

#Patterns and idioms

Small things that show up across every recipe — worth internalizing before you build.

#Cost estimation before billing

All workflow examples fetch a cost estimate and confirm before running:

📊 Cost Estimate:
   Spark: 0.45 (Balance remaining: 9.55)
   USD:  $0.0023

Proceed with generation? [Y/n]:

The pattern is estimateCost → confirm → create. Build the same loop into anything user-facing so a prompt with --batch 10 doesn't accidentally drain a wallet.

#Promise vs event flow

// Promise: clean for batch
const urls = await project.waitForCompletion();

// Events: needed for real-time UI
project.on('progress', p => updateBar(p));
project.on('jobCompleted', j => renderThumbnail(j.resultUrl));
project.on('failed', err => showError(err));

Use promises in background jobs and tests. Use events whenever a human is watching a progress bar.

#Three packages, one ecosystem

Use	Package
Direct SDK access (this page's examples)	`@sogni-ai/sogni-client`
Contracts + n8n-style helpers	`@sogni-ai/sogni-intelligence-client`
Language-neutral JSON schemas	`@sogni-ai/sogni-protocol`

See the SDK page for the full breakdown.

#Result URLs expire — download what you keep

All resultUrl values are valid for 24 hours. The workflow examples auto-download to ./output/; if you're building your own integration, persist binary data to your own storage immediately.

#One `appId` per connection

appId is required and must be unique. Opening a second connection with the same ID closes the first — useful for forcing logout, harmful if you reuse the same string across services.

#Further reading

Sogni SDK — installation, auth, models, full parameter reference.
TypeScript API docs — every ProjectParams, Job, and event payload.
API Reference — REST endpoints: /v1/chat/completions, /v1/creative-agent/workflows, media, wallet, replay.
Sogni Intelligence — LLM, agent, and tool-calling surface overview.
Creative Agent Skill — the sogni-agent CLI and skill format.
Sogni-AI/sogni-client — SDK source and the full examples folder.