This library provides an easy way to interact with the Sogni Supernet - a DePIN protocol for creative AI inference. It is written in TypeScript and can be used in both TypeScript and JavaScript projects such as backend Node.js and browser environments.
Behind the scenes this SDK uses a WebSocket connection for communication between clients, server, and workers. It harnesses an event-based API to interact with Supernet to make things super efficient.
Version 4 adds support for video generation, including the new Wan 2.2 14B FP8 model family with five workflow types (text-to-video, image-to-video, sound-to-video, animate-move, and animate-replace). There are the following breaking changes:
type is required when calling sogni.projects.create(params), valid values are image and video. See code examples below.numberOfImages renamed to numberOfMediahasResultImage in Job class is now hasResultMediaJob and Project classes now have type property that can be image or videoAdd library to your project using npm or yarn:
npm install @sogni-ai/sogni-client
or
yarn add @sogni-ai/sogni-client
In order to use Sogni Supernet, you need an active Sogni account with a positive SOGNI or Spark token balance. You can authenticate using either an API key (recommended) or username and password. You can create a free account in our Web App or Mac App which will give you tokens just for signing up and confirming your email. You can get daily bonus tokens by claiming them (under rewards) each 24-hours.
Spark tokens can be purchased with a credit card in a Mac or Web app.
Your account is tied to a Base Wallet that is created during signup.
There are 2 worker network types available:
fast - this network runs on high-end GPUs and is optimized for speed. It is more expensive than relaxed network. Required for video generation.relaxed - this network runs on Apple Mac devices and is optimized for cost. It is cheaper than fast network. Supports image generation only.In both options, the more complex your query is (the more steps), the higher the cost in tokens.
One request for image or video generation is called a Project. A project can generate one or more images or videos. Each generated image or video is represented by a Job.
When you send a project to Supernet, it will be processed by one or more workers. The resulting media will be encrypted and uploaded to Sogni servers where it will be stored for 24 hours. After this period, media files will be auto-deleted.
To initialize a client, you need to provide appId, and account credentials.
API key authentication is the simplest way to connect. The client auto-authenticates via the WebSocket connection — no separate login() call is needed.
import { SogniClient } from '@sogni-ai/sogni-client';
const sogni = await SogniClient.createInstance({
appId: 'your-app-id', // Required, must be unique string, UUID is recommended
network: 'fast', // Network to use, 'fast' or 'relaxed'
apiKey: 'your-api-key' // API key for authentication
});
// No login() call needed — the client is authenticated automatically
const models = await sogni.projects.waitForModels();
Note: With API key auth, most REST API calls (balance, profile, etc.) are available. Sensitive account operations (withdrawals, staking, 2FA) are not available with API key auth.
import { SogniClient } from '@sogni-ai/sogni-client';
const sogni = await SogniClient.createInstance({
appId: 'your-app-id',
network: 'fast',
});
await sogni.account.login('your-username', 'your-password');
const models = await sogni.projects.waitForModels();
Important Note:
await on the top level, if you are CommonJS you will need to wrap await calls in an async function.appId must be unique string, UUID is recommended. It is used to identify your application.appId is allowed. If you try to connect with the same appId multiple times, the previous connection will be closed.After authentication, the client will have an active WebSocket connection to Sogni Supernet. Within a short period of time the client will receive the current balance and list of available models. After this you can start using the client to generate images or videos.
It is advised to watch for connected and disconnected events on the client instance to be notified when the connection is established or lost:
// Will be triggered when the client is connected to Supernet
sogni.client.on('connected', ({network}) => {
console.log('Connected to Supernet:', network);
});
// Will be triggered when websocket connection is lost or the client is disconnected from Supernet
sogni.client.on('disconnected', ({code, reason}) => {
console.log('Disconnected from Supernet:', code, reason);
});
Sogni supports a wide range of models for image generation. You can find a list of available models in
sogni.projects.availableModels property during runtime or query it using sogni.projects.getAvailableModels() method.
For a start, you can try FLUX.1 [schnell] with the following parameters:
const fluxDefaults = {
modelId: 'flux1-schnell-fp8',
steps: 4,
guidance: 1
}
// Find model that has the most workers
const mostPopularModel = sogni.projects.availableModels.reduce((a, b) =>
a.workerCount > b.workerCount ? a : b
);
// Create a project using the most popular model
const project = await sogni.projects.create({
type: 'image',
modelId: mostPopularModel.id,
positivePrompt: 'A cat wearing a hat',
negativePrompt:
'malformation, bad anatomy, bad hands, missing fingers, cropped, low quality, bad quality, jpeg artifacts, watermark',
stylePrompt: 'anime',
steps: 20,
guidance: 7.5,
numberOfMedia: 1,
outputFormat: 'jpg', // Can be 'png' or 'jpg', defaults to 'png'
tokenType: 'spark', // 'sogni' or 'spark'
network: 'fast' // 'fast' or 'relaxed'
});
Note: Full project parameter list can be found in ProjectParams docs.
In general, there are 2 ways to work with API:
async/await syntax.Project and Job class instances.const project = await sogni.projects.create({
type: 'image',
modelId: mostPopularModel.id,
steps: 20,
guidance: 7.5,
positivePrompt: 'A cat wearing a hat',
negativePrompt:
'malformation, bad anatomy, bad hands, missing fingers, cropped, low quality, bad quality, jpeg artifacts, watermark',
stylePrompt: 'anime',
numberOfMedia: 4,
tokenType: 'spark', // 'sogni' or 'spark'
network: 'fast' // 'fast' or 'relaxed'
});
project.on('progress', (progress) => {
console.log('Project progress:', progress);
});
const imageUrls = await project.waitForCompletion();
// Now you can use image URLs to download images.
// Note that images will be available for 24 hours only!
console.log('Image URLs:', imageUrls);
const project = await sogni.projects.create({
type: 'image',
modelId: mostPopularModel.id,
steps: 20,
guidance: 7.5,
positivePrompt: 'A cat wearing a hat',
negativePrompt:
'malformation, bad anatomy, bad hands, missing fingers, cropped, low quality, bad quality, jpeg artifacts, watermark',
stylePrompt: 'anime',
numberOfMedia: 4,
tokenType: 'spark', // 'sogni' or 'spark'
network: 'fast' // 'fast' or 'relaxed'
});
// Fired when one of project jobs completed, you can get the resultUrl from the job
// without waiting for the entire project to complete
project.on('jobCompleted', (job) => {
console.log('Job completed:', job.id, job.resultUrl);
});
// Fired when one of project jobs failed
project.on('jobFailed', (job) => {
console.log('Job failed:', job.id, job.error);
});
// Receive project completion percentage in real-time
project.on('progress', (progress) => {
// console.log('Project progress:', progress);
});
// Fired when the project is fully completed
project.on('completed', async (images) => {
console.log('Project completed:', images);
});
// Fired when the project failed
project.on('failed', async (errorData) => {
console.log('Project failed:', errorData);
});
Here is a full list of project parameters that you can use:
modelId - ID of the model to use for image generation.positivePrompt - text prompt that describes what you want to see in the image. Can be an empty string.negativePrompt - text prompt that describes what you don't want to see in the image. Can be an empty string.stylePrompt - text prompt that describes the style of the image. Can be an empty string.numberOfImages - number of images to generate.tokenType - select token type to pay for render. Can be either sogni or spark.sizePreset - optionally pass the ID of a size preset to use. If not passed, the default output is a square at
either 512x512, 768x768 or 1024x1024 (SDXL and Flux) based on the default resolution of the selected model.
See Detecting available output presets section below for available presets for your model. The token cost and
render time of the job is heavily influenced by total pixel count where a 2048x2048 image is 4x the cost and render
time of a 1024x1024 image as it is 4x the generated pixel count. You may also pass custom along with width and
height project parameters to request a custom dimension. Note that not all size presets and custom aspect ratios
produce consistently good results with all models. If your output features skewed anatomy or doubling of features
you should experiment with a different model or output size.width - if 'sizePreset' is set to 'custom' you may pass a custom pixel width between 256 and 2048height - if 'sizePreset' is set to 'custom' you may pass a custom pixel height between 256 and 2048steps - number of inference steps between random pixels to final image. Higher steps generally lead to higher
quality images and more details but varies by model, prompt, guidance, and desired look. For most Stable Diffusion
models 20-40 steps is ideal with 20 being 2x faster to render than 40. For Flux 4 steps is optimal. Lightning,
Turbo and LCM models are designed for quality output in as little as 1 step. (More info).guidance - guidance scale. For most Stable Diffusion models, optimal value is 7.5 (More info).network - network type to use, fast or relaxed. This parameter allows to override default network type for this project.disableNSFWFilter - disable NSFW filter for this project. NSFW filter is enabled by default and workers won't upload resulting images if they are detected as NSFW.seed - uint32 number to use as seed. If not provided, random seed will be used. If numberOfImages is greater than 1, provided seed will be user only for one of them. (More info).numberOfPreviews - number of preview images to generate. If not provided, no preview images will be generated.sampler - sampler algorithm (More info). For available options, see the "Samplers" section below.scheduler - scheduler to use (More info). For available options, see the "Schedulers" section below.startingImage - guide image in PNG format. Can be File, Blob or BufferstartingImageStrength - strong effect of starting image should be. From 0 to 1, default 0.5.controlNet - Stable Diffusion ControlNet parameters. See ControlNets section below for more info.outputFormat - output image format. Can be png or jpg. If not specified, png will be used. JPG format results in smaller file sizes but may have slightly lower quality due to compression.TypeScript type definitions for project parameters can be found in ProjectParams docs.
You can get a list of available output presets for a specific network and model using sogni.projects.getOutputPresets method.
const presets = await sogni.projects.getSizePresets('fast', 'flux1-schnell-fp8');
console.log('Available output presets:', presets);
Sample response:
[
{
"label": "Square",
"id": "square",
"width": 512,
"height": 512,
"ratio": "1:1",
"aspect": "1"
},
{
"label": "Square HD",
"id": "square_hd",
"width": 1024,
"height": 1024,
"ratio": "1:1",
"aspect": "1"
},
{
"label": "Portrait: Standard",
"id": "portrait_7_9",
"width": 896,
"height": 1152,
"ratio": "7:9",
"aspect": "0.78"
},
{
"label": "Portrait: 35mm",
"id": "portrait_13_19",
"width": 832,
"height": 1216,
"ratio": "13:19",
"aspect": "0.68"
},
{
"label": "Portrait: Mobile",
"id": "portrait_4_7",
"width": 768,
"height": 1344,
"ratio": "4:7",
"aspect": "0.57"
},
{
"label": "Portrait: Extended",
"id": "portrait_5_12",
"width": 640,
"height": 1536,
"ratio": "5:12",
"aspect": "0.42"
},
{
"label": "Landscape: Standard",
"id": "landscape_9_7",
"width": 1152,
"height": 896,
"ratio": "9:7",
"aspect": "1.28"
},
{
"label": "Landscape: 35mm",
"id": "landscape_19_13",
"width": 1216,
"height": 832,
"ratio": "19:13",
"aspect": "1.46"
},
{
"label": "Landscape: Widescreen",
"id": "landscape_7_4",
"width": 1344,
"height": 768,
"ratio": "7:4",
"aspect": "1.75"
},
{
"label": "Landscape: Ultrawide",
"id": "landscape_12_5",
"width": 1536,
"height": 640,
"ratio": "12:5",
"aspect": "2.4"
}
]
Samplers control the denoising process — the sequence of steps that transforms random noise into your final image.
Avaliable sampler options depend on a model. You can use api to get available samplers for a specific model:
const modelOptions = await sogni.projects.getModelOptions('flux1-schnell-fp8');
console.log(modelOptions.sampler);
/*
{
allowed: [ 'euler', 'euler_a', 'dpm_pp_2m', 'dpmpp_2m_sde', 'dpm_pp_sde' ],
default: 'euler'
}
*/
See Samplers and Schedulers docs for more info.
Control how steps are distributed. For more info see Schedulers and Samplers docs.
Available scheduler options depend on a model. You can use api to get available schedulers for a specific model:
const modelOptions = await sogni.projects.getModelOptions(modelId);
console.log(modelOptions.scheduler);
/*
{
allowed: [
'simple',
'karras',
'linear',
'sgm_uniform',
'beta',
'normal',
'ddim',
'kl_optimal'
],
default: 'simple'
}
*/
EXPERIMENTAL FEATURE: This feature is still in development and may not work as expected. Use at your own risk.
ControlNet is a neural network that controls image generation in Stable Diffusion by adding extra conditions. See more info and usage samples in ControlNets docs for Sogni Studio.
To use ControlNet in your project, you need to provide controlNet object with the following properties:
name - name of the ControlNet to use. Currently supported:
cannydepthinpaintinstrp2plineartlineartanimemlsdnormalbaeopenposescribblesegmentationshufflesoftedgetileinstantidimage - input image. Image size should match the size of the generated image. Can be File, Blob or Bufferstrength - ControlNet strength 0 to 1. 0 full control to prompt, 1 full control to ControlNetmode - How control and prompt should be weighted. Can be:
balanced - (default) balanced, no preference between prompt and control modelprompt_priority - the prompt has more impact than the modelcn_priority - the controlnet model has more impact than the promptguidanceStart - step when ControlNet first applied, 0 means first step, 1 means last step. Must be less than guidanceEndguidanceEnd - step when ControlNet last applied, 0 means first step, 1 means last step. Must be greater than guidanceStartExample:
const cnImage = fs.readFileSync('./cn.jpg');
const project = await sogni.projects.create({
type: 'image',
network: 'fast',
modelId: 'coreml-cyberrealistic_v70_768',
numberOfMedia: 1,
positivePrompt: 'make men look older',
steps: 20,
guidance: 7.5,
controlNet: {
name: 'instrp2p',
image: cnImage
}
});
Full ControlNet type definition:
export type ControlNetName =
| 'canny'
| 'depth'
| 'inpaint'
| 'instrp2p'
| 'lineart'
| 'lineartanime'
| 'mlsd'
| 'normalbae'
| 'openpose'
| 'scribble'
| 'segmentation'
| 'shuffle'
| 'softedge'
| 'tile'
| 'instantid';
export type ControlNetMode = 'balanced' | 'prompt_priority' | 'cn_priority';
export interface ControlNetParams {
name: ControlNetName;
image?: File | Buffer | Blob;
strength?: number;
mode?: ControlNetMode;
guidanceStart?: number;
guidanceEnd?: number;
}
The Sogni SDK supports advanced video generation workflows powered by Wan 2.2 14B FP8 models. These models are available on the fast network and support various video generation workflows.
The Wan 2.2 model family supports five distinct video generation workflows:
Each workflow has two model variants optimized for different use cases:
_lightx2v suffix) - Faster inference (4-step), good quality_lightx2v) - Slower inference, best qualityExample model IDs:
wan_v2.2-14b-fp8_t2v_lightx2v (Text-to-Video, speed)wan_v2.2-14b-fp8_t2v (Text-to-Video, quality)wan_v2.2-14b-fp8_i2v_lightx2v (Image-to-Video, speed)wan_v2.2-14b-fp8_i2v (Image-to-Video, quality)wan_v2.2-14b-fp8_s2v_lightx2v (Sound-to-Video, speed)wan_v2.2-14b-fp8_s2v (Sound-to-Video, quality)wan_v2.2-14b-fp8_animate-move_lightx2v (Animate-Move, speed)wan_v2.2-14b-fp8_animate-replace_lightx2v (Animate-Replace, speed)When creating video projects, you can specify:
fps - Frames per second: 16 or 32 (default: 16)frames - Number of frames: 17-161 (default: 81, which is ~5 seconds at 16fps)width - Video width in pixelsheight - Video height in pixelssteps - Increase inference steps to increase qualityseed - Random seed for reproducibilityreferenceImage - Reference image for workflows that require it (i2v, s2v, animate-move, animate-replace)referenceVideo - Reference video for animate workflows (animate-move, animate-replace)referenceAudio - Reference audio for sound-to-video workflowconst project = await sogni.projects.create({
type: 'video',
network: 'fast',
modelId: 'wan_v2.2-14b-fp8_t2v_lightx2v',
positivePrompt: 'A serene ocean wave crashing on a beach at sunset',
fps: 16,
frames: 81,
width: 512,
height: 512
});
const videoUrls = await project.waitForCompletion();
console.log('Video URL:', videoUrls[0]);
const referenceImage = fs.readFileSync('./input-image.png');
const project = await sogni.projects.create({
type: 'video',
network: 'fast',
modelId: 'wan_v2.2-14b-fp8_i2v_lightx2v',
positivePrompt: 'camera zooms in slowly',
referenceImage: referenceImage,
fps: 16,
frames: 81
});
const videoUrls = await project.waitForCompletion();
const referenceImage = fs.readFileSync('./image.jpg');
const referenceAudio = fs.readFileSync('./audio.m4a');
const project = await sogni.projects.create({
type: 'video',
network: 'fast',
modelId: 'wan_v2.2-14b-fp8_s2v_lightx2v',
referenceImage: referenceImage,
referenceAudio: referenceAudio,
fps: 16,
frames: 81
});
const videoUrls = await project.waitForCompletion();
Transfer motion from a reference video to a subject in an image:
const referenceImage = fs.readFileSync('./subject.jpg');
const referenceVideo = fs.readFileSync('./motion-source.mp4');
const project = await sogni.projects.create({
type: 'video',
network: 'fast',
modelId: 'wan_v2.2-14b-fp8_animate-move_lightx2v',
referenceImage: referenceImage,
referenceVideo: referenceVideo,
fps: 16,
frames: 81
});
const videoUrls = await project.waitForCompletion();
Replace a subject in a video while preserving the original motion:
const referenceImage = fs.readFileSync('./new-subject.jpg');
const referenceVideo = fs.readFileSync('./original-video.mp4');
const project = await sogni.projects.create({
type: 'video',
network: 'fast',
modelId: 'wan_v2.2-14b-fp8_animate-replace_lightx2v',
referenceImage: referenceImage,
referenceVideo: referenceVideo,
fps: 16,
frames: 81
});
const videoUrls = await project.waitForCompletion();
The Sogni SDK supports LLM text generation through the Sogni Supernet, providing an OpenAI-compatible chat completions API with streaming, multi-turn conversations, and tool calling (function calling).
Send prompts to LLM workers on the Sogni network and receive text responses — with optional token-by-token streaming:
// Non-streaming chat completion
const response = await sogni.projects.chatCompletion({
model: 'qwen3-30b-a3b-gptq-int4',
messages: [
{ role: 'system', content: 'You are a helpful assistant.' },
{ role: 'user', content: 'What is the Sogni Supernet?' }
],
max_tokens: 4096,
temperature: 0.7
});
console.log(response.choices[0].message.content);
Define custom tools that the LLM can invoke during conversations. The LLM decides when a tool is needed, returns structured arguments, and you execute the function locally before feeding results back:
const tools = [
{
type: 'function',
function: {
name: 'get_weather',
description: 'Get current weather for a location',
parameters: {
type: 'object',
properties: {
location: { type: 'string', description: 'City name' }
},
required: ['location']
}
}
}
];
const response = await sogni.projects.chatCompletion({
model: 'qwen3-30b-a3b-gptq-int4',
messages: [{ role: 'user', content: "What's the weather in Austin?" }],
tools: tools,
tool_choice: 'auto'
});
Combine LLM intelligence with Sogni's media generation capabilities. The LLM detects when a user wants to create an image, video, or music, enhances the prompt, and calls Sogni's generation APIs — turning natural language into creative output:
See the workflow_text_chat_sogni_tools.mjs example for a complete implementation that wires LLM tool calling to Sogni's image, video, and audio generation APIs.
The examples directory contains working examples for all workflows:
workflow_text_to_image.mjs - Text-to-image generation with multiple model optionsworkflow_image_edit.mjs - Reference-based image generation using context imagesworkflow_text_to_video.mjs - Text-to-video generation with WAN 2.2 modelsworkflow_image_to_video.mjs - Animate static images into videosworkflow_sound_to_video.mjs - Audio-synchronized video generation with lip-syncworkflow_video_to_video.mjs - Motion transfer and character replacement (Animate-Move/Animate-Replace)workflow_text_chat.mjs - Single-turn chat completion (non-streaming)workflow_text_chat_streaming.mjs - Streaming chat with token-by-token outputworkflow_text_chat_multi_turn.mjs - Multi-turn conversation with history, in-chat commands, and session statsworkflow_text_chat_tool_calling.mjs - LLM tool calling with built-in tools (weather, time, unit conversion, math)workflow_text_chat_sogni_tools.mjs - Generate images, videos, and music through natural language via LLM tool callingpromise_based.mjs - Image generation using promises/async-awaitevent_driven.js - Image generation using event listenersThe workflow examples showcase a few powerful open-source frontier models supported by Sogni Supernet:
| Model ID | Description | Use Case |
|---|---|---|
z_image_turbo_bf16 |
Z-Image Turbo - Ultra-fast 8-step generation | Quick text-to-image prototyping and iteration |
z_image_bf16 |
Z-Image - High quality 20-step generation | Detailed, high quality image output |
qwen_image_edit_2511_fp8_lightning |
Qwen Image Edit Lightning - Fast 4-step editing | Rapid reference-based image generation |
qwen_image_edit_2511_fp8 |
Qwen Image Edit - High quality 20-step editing | Professional image editing with context awareness |
wan_v2.2-14b-fp8_t2v_lightx2v |
Wan 2.2 T2V - Text-to-video | Generate videos from text prompts |
qwen3-30b-a3b-gptq-int4 |
Qwen3 30B - LLM chat & tool calling | Text generation, reasoning, and tool calling |
qwen3.5-35b-a3b-gguf-q4km |
Qwen3.5 35B - LLM chat & tool calling | Latest model with 32K context, reasoning, and tool calling |
All workflow examples include:
Run any workflow example:
cd examples
npm install
node workflow_text_to_image.mjs
node workflow_image_edit.mjs
node workflow_text_to_video.mjs
node workflow_text_chat_streaming.mjs "Tell me a story"
node workflow_text_chat_sogni_tools.mjs "Create an image of a sunset over mountains"
This SDK provides documentation optimized for AI coding assistants like Claude Code, GitHub Copilot, Cursor, and Open Claw:
| File | Description |
|---|---|
llms.txt |
Indexed quick reference with code examples |
llms-full.txt |
Comprehensive documentation with complete API reference |
CLAUDE.md |
Claude Code-specific guidance and project context |
These files follow the llms.txt convention for LLM-friendly documentation.
When helping users generate images, videos, or use LLM features with Sogni:
type: 'image' with models like flux1-schnell-fp8type: 'video' with network: 'fast' (required)type: 'audio' with ACE-Step 1.5 modelssogni.projects.chatCompletion() for text generation with streaming and tool callingllms-full.txt for detailsFull TypeScript API documentation is available at sdk-docs.sogni.ai.