Source: https://docs.sogni.ai/developer-tutorials/

# Developer Tutorials

Hands-on recipes for building with the [Sogni SDK](https://docs.sogni.ai/sogni-sdk/) and Supernet — text-to-image, video, LLM chat, vision, tool calling, durable creative workflows, and full apps. The full recipe pack links to runnable TypeScript/JavaScript source in [`Sogni-AI/sogni-client/examples`](https://github.com/Sogni-AI/sogni-client/tree/main/examples) so you can clone, set credentials, and `node script.mjs` in under a minute.

If you're new, start with the [Sogni SDK](https://docs.sogni.ai/sogni-sdk/) overview for installation and authentication, then come back here for working recipes.

**Using Python?** Start with the official [Sogni Python SDK quickstart](https://docs.sogni.ai/sogni-sdk/python/). The [`sogni-client-python`](https://github.com/Sogni-AI/sogni-client-python) repository includes runnable examples for image generation, Krea Identity Edit, and streaming LLM chat.

* * *

## [#](https://docs.sogni.ai/developer-tutorials/#quickstart-run-the-example-pack)Quickstart -- Run the example pack

The [`sogni-client/examples`](https://github.com/Sogni-AI/sogni-client/tree/main/examples) folder is the complete TypeScript/JavaScript recipe pack. The examples in this section are written in **Node.js**; Python users can follow the [Python SDK guide](https://docs.sogni.ai/sogni-sdk/python/) for the equivalent async client patterns.

**Prerequisite:** [Node.js](https://nodejs.org/) 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.

* * *

## [#](https://docs.sogni.ai/developer-tutorials/#image-recipes)Image recipes

### [#](https://docs.sogni.ai/developer-tutorials/#text-to-image-with-model-switching)Text-to-image with model switching

[`workflow_text_to_image.mjs`](https://github.com/Sogni-AI/sogni-client/blob/main/examples/workflow_text_to_image.mjs) — [Krea 2 Turbo](https://www.sogni.ai/models/krea-2-turbo), Z-Image Turbo, Z-Image, Flux.1 Schnell, and Qwen Image 2512 behind one CLI.

```
node workflow_text_to_image.mjs "A cyberpunk city" --model z-turbo
node workflow_text_to_image.mjs "A neon sign that reads OPEN" --model krea-2-turbo
node workflow_text_to_image.mjs "Professional portrait" --model qwen-2512 --seed 12345
node workflow_text_to_image.mjs "A serene sunset" --model z-image --batch 4
```

What to learn: model selection by alias, Krea 2 Turbo's fast few-step text-to-image path, `--seed` for reproducibility, batch generation, custom samplers/schedulers.

### [#](https://docs.sogni.ai/developer-tutorials/#reference-guided-edits-with-qwen-image-edit)Reference-guided edits with Qwen Image Edit

[`workflow_image_edit.mjs`](https://github.com/Sogni-AI/sogni-client/blob/main/examples/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, GPT Image 2 16), `--model qwen-lightning` for fast 4-step edits, `--style` and `--negative` prompts.

### [#](https://docs.sogni.ai/developer-tutorials/#promise-vs-event-driven-generation)Promise vs event-driven generation

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

-   [`promise_based.mjs`](https://github.com/Sogni-AI/sogni-client/blob/main/examples/promise_based.mjs) — `await project.waitForCompletion()`. Clean for batch jobs.
-   [`event_driven.js`](https://github.com/Sogni-AI/sogni-client/blob/main/examples/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
```

* * *

## [#](https://docs.sogni.ai/developer-tutorials/#video-recipes)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.

### [#](https://docs.sogni.ai/developer-tutorials/#text-to-video)Text-to-video

[`workflow_text_to_video.mjs`](https://github.com/Sogni-AI/sogni-client/blob/main/examples/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
```

### [#](https://docs.sogni.ai/developer-tutorials/#image-to-video-animate-a-still)Image-to-video (animate a still)

[`workflow_image_to_video.mjs`](https://github.com/Sogni-AI/sogni-client/blob/main/examples/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"
```

### [#](https://docs.sogni.ai/developer-tutorials/#sound-to-video-lip-sync)Sound-to-video (lip sync)

[`workflow_sound_to_video.mjs`](https://github.com/Sogni-AI/sogni-client/blob/main/examples/workflow_sound_to_video.mjs) — frame count is calculated from the audio. Supports `.mp3`, `.m4a`, `.wav`.

```
node workflow_sound_to_video.mjs --model lightx2v
```

### [#](https://docs.sogni.ai/developer-tutorials/#video-to-video-motion-transfer-character-replacement)Video-to-video: motion transfer & character replacement

[`workflow_video_to_video.mjs`](https://github.com/Sogni-AI/sogni-client/blob/main/examples/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
```

### [#](https://docs.sogni.ai/developer-tutorials/#partner-seedance-video-external-provider)Partner Seedance video (external provider)

[`workflow_partner_seedance_video.mjs`](https://github.com/Sogni-AI/sogni-client/blob/main/examples/workflow_partner_seedance_video.mjs) — covers T2V, I2V, IA2V, and V2V on [Seedance 2.0](https://www.sogni.ai/models/seedance-2-0) and Seedance 2.0 Mini, with Seedance-style role tags (`@Image1`, `@Video1`, `@Audio1`). Mini replaces the legacy Fast tier with faster renders at a lower cost.

```
node workflow_partner_seedance_video.mjs                                                  # guided picker
node workflow_partner_seedance_video.mjs "A glass whale through a neon city" --mini --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.

### [#](https://docs.sogni.ai/developer-tutorials/#multi-angle-and-batched-workflows)Multi-angle and batched workflows

-   [`workflow_multiple_angles.mjs`](https://github.com/Sogni-AI/sogni-client/blob/main/examples/workflow_multiple_angles.mjs) — fan out a single subject into multiple camera angles.
-   [`workflow_batch_i2v.mjs`](https://github.com/Sogni-AI/sogni-client/blob/main/examples/workflow_batch_i2v.mjs) — animate a directory of images in one run.

* * *

## [#](https://docs.sogni.ai/developer-tutorials/#llm-chat-vision-and-tool-calling)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.

### [#](https://docs.sogni.ai/developer-tutorials/#single-turn-and-streaming-chat)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`](https://github.com/Sogni-AI/sogni-client/blob/main/examples/workflow_text_chat.mjs) returns the full message; [`workflow_text_chat_streaming.mjs`](https://github.com/Sogni-AI/sogni-client/blob/main/examples/workflow_text_chat_streaming.mjs) streams tokens and prints tokens/sec at the end.

### [#](https://docs.sogni.ai/developer-tutorials/#multi-turn-repl-with-system-think-stats)Multi-turn REPL with `/system`, `/think`, `/stats`

[`workflow_text_chat_multi_turn.mjs`](https://github.com/Sogni-AI/sogni-client/blob/main/examples/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."
```

### [#](https://docs.sogni.ai/developer-tutorials/#vision-describe-ocr-compare-images)Vision: describe, OCR, compare images

[`workflow_text_chat_vision.mjs`](https://github.com/Sogni-AI/sogni-client/blob/main/examples/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
```

### [#](https://docs.sogni.ai/developer-tutorials/#function-calling-weather-time-math)Function calling (weather, time, math)

[`workflow_text_chat_tool_calling.mjs`](https://github.com/Sogni-AI/sogni-client/blob/main/examples/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.

* * *

## [#](https://docs.sogni.ai/developer-tutorials/#generate-media-from-natural-language-sogni-platform-tools)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.

### [#](https://docs.sogni.ai/developer-tutorials/#hosted-creative-tools-surface)Hosted creative-tools surface

[`workflow_text_chat_sogni_tools.mjs`](https://github.com/Sogni-AI/sogni-client/blob/main/examples/workflow_text_chat_sogni_tools.mjs) and [`workflow_creative_agent_tools.mjs`](https://github.com/Sogni-AI/sogni-client/blob/main/examples/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.

### [#](https://docs.sogni.ai/developer-tutorials/#direct-synchronous-tool-execution)Direct synchronous tool execution

[`workflow_direct_creative_tool.mjs`](https://github.com/Sogni-AI/sogni-client/blob/main/examples/workflow_direct_creative_tool.mjs) — call `enhance_prompt`, `compose_script`, `compose_lyrics`, `compose_instrumental`, `compose_workflow`, or `compose_workflow_template` directly through `sogni.chat.hosted.executeTool()`.

```
node workflow_direct_creative_tool.mjs "A cinematic portrait of a glass robot"
node workflow_direct_creative_tool.mjs --tool compose_workflow "Plan a 3-shot neon bakery teaser"
node workflow_direct_creative_tool.mjs --tool compose_lyrics "A synth-pop song about rain"
```

Use this when your app already knows the exact synchronous composition/planning tool and JSON arguments. It skips the extra `/v1/chat/completions` dispatcher round that would only force a known tool call.

### [#](https://docs.sogni.ai/developer-tutorials/#durable-creative-workflows-survive-disconnect)Durable creative workflows (survive disconnect)

[`workflow_creative_agent_workflows.mjs`](https://github.com/Sogni-AI/sogni-client/blob/main/examples/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](https://github.com/Sogni-AI/sogni-api/blob/main/docs/llm-api.md#durable-creative-agent-workflows) for the full contract.

* * *

## [#](https://docs.sogni.ai/developer-tutorials/#embed-sogni-in-a-web-app)Embed Sogni in a web app

[`examples/express`](https://github.com/Sogni-AI/sogni-client/tree/main/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.

* * *

## [#](https://docs.sogni.ai/developer-tutorials/#build-a-superapp-open-source-case-studies)Build a SuperApp — open-source case studies

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

### [#](https://docs.sogni.ai/developer-tutorials/#telegram-discord-sticker-bot)Telegram & Discord sticker bot

[`Sogni-AI/sogni-sticker-bot`](https://github.com/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`](https://www.npmjs.com/package/@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.

### [#](https://docs.sogni.ai/developer-tutorials/#generate-inside-any-n8n-workflow)Generate inside any n8n workflow

[`Sogni-AI/n8n-nodes-sogni`](https://github.com/Sogni-AI/n8n-nodes-sogni) — community node bringing Sogni image, video, image-edit, and LLM chat into [n8n](https://n8n.io/). 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/`](https://github.com/Sogni-AI/n8n-nodes-sogni/tree/main/examples) in the repo.

### [#](https://docs.sogni.ai/developer-tutorials/#drop-sogni-into-any-agent-runtime)Drop Sogni into any agent runtime

[`Sogni-AI/setup-sogni-agent-skill`](https://github.com/Sogni-AI/setup-sogni-agent-skill) — `npx` installer for the [Sogni Creative Agent Skill](https://github.com/Sogni-AI/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](https://docs.sogni.ai/more-superapps/creative-agent-skill/) in the docs.

* * *

## [#](https://docs.sogni.ai/developer-tutorials/#patterns-and-idioms)Patterns and idioms

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

### [#](https://docs.sogni.ai/developer-tutorials/#cost-estimation-before-billing)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.

### [#](https://docs.sogni.ai/developer-tutorials/#promise-vs-event-flow)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.

### [#](https://docs.sogni.ai/developer-tutorials/#four-packages-one-ecosystem)Four packages, one ecosystem

| Use | Package |
| --- | --- |
| Direct async Python access | [`sogni-client`](https://docs.sogni.ai/sogni-sdk/python/) |
| Direct TypeScript/JavaScript 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](https://docs.sogni.ai/sogni-sdk/) for the full breakdown.

### [#](https://docs.sogni.ai/developer-tutorials/#result-urls-expire-download-what-you-keep)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.

### [#](https://docs.sogni.ai/developer-tutorials/#one-appid-per-connection)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.

* * *

## [#](https://docs.sogni.ai/developer-tutorials/#further-reading)Further reading

-   [Sogni SDK](https://docs.sogni.ai/sogni-sdk/) — installation, auth, models, full parameter reference.
-   [Python SDK quickstart](https://docs.sogni.ai/sogni-sdk/python/) — async image generation, editing, chat, and durable workflows.
-   [TypeScript API docs](https://sdk-docs.sogni.ai/) — every `ProjectParams`, `Job`, and event payload.
-   [API Reference](https://docs.sogni.ai/api-reference/) — REST endpoints: `/v1/chat/completions`, `/v1/creative-agent/tools/execute`, `/v1/creative-agent/workflows`, media, wallet, replay.
-   [Sogni Intelligence](https://docs.sogni.ai/sogni-intelligence/introduction/) — LLM, agent, and tool-calling surface overview.
-   [Creative Agent Skill](https://docs.sogni.ai/more-superapps/creative-agent-skill/) — the `sogni-agent` CLI and skill format.
-   [`Sogni-AI/sogni-client-python`](https://github.com/Sogni-AI/sogni-client-python) — Python source, tests, and runnable examples.
-   [`Sogni-AI/sogni-client`](https://github.com/Sogni-AI/sogni-client) — SDK source and the full [examples folder](https://github.com/Sogni-AI/sogni-client/tree/main/examples).