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.
creative-tools surface for media generation, editing, analysis, metadata, prompt enhancement, script writing, lyrics, and instrumental structures; set sogni_tools: "creative-agent" to add workflow control and asset-manifest toolsLast-Event-ID resume, and cooperative cancellation via /v1/creative-agent/workflowsVersion 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, video and audio. 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, video or audioAdd 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. Each email-verified account is allowed 400 free Spark render credits per month. On the API, free credits can be used with Z-Image Turbo; paid credits can access all models and features.
To get your API key: Log in to dashboard.sogni.ai, click your Username dropdown in the top-right corner, and provision your API key.
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.
Get your API key: Log in to dashboard.sogni.ai and click your Username dropdown in the top-right corner to provision your key.
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.Use appSource to identify the product or integration behind a client connection. The SDK forwards it during authentication and on socket-backed project/chat requests so server-side reporting can attribute usage consistently.
By default, the SDK receives the full socket event stream, including live model worker counts through swarmModels and swarmLLMModels. Proxy, server-side, or headless clients that do not need ongoing worker count updates can opt out of the grouped model availability stream:
const sogni = await SogniClient.createInstance({
appId: 'your-app-id',
appSource: 'my-integration',
network: 'fast',
apiKey: 'your-api-key',
socketEventSubscriptions: {
modelAvailability: false
}
});
If your process needs the initial model list before submitting work, keep the default subscription, wait for models, then unsubscribe from future count updates:
const models = await sogni.projects.waitForModels();
await sogni.setSocketEventSubscriptions({
modelAvailability: false
});
modelAvailability is a subscription group covering swarmModels and swarmLLMModels. You can also opt in or out of individual socket event names with the same boolean map, and omitted subscriptions preserve default server behavior.
Group flags dominate individual flags. Disabling a group (e.g. modelAvailability: false) suppresses every event in the group, and re-enabling a single event under that group later (e.g. swarmModels: true) does not override the group-level suppression — the group flag still wins. To re-enable a single event, re-enable the group it belongs to (or clear it via setSocketEventSubscriptions({ reset: true }) before reapplying selective subscriptions). Subscriptions you do not list keep their current server-side state.
Runtime subscription changes made via setSocketEventSubscriptions are remembered locally and re-applied on every reconnect, so a long-lived client only needs to express its preference once.
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);
});
External API-backed jobs may not report diffusion steps. For those jobs, SDK progress uses provider progress or ETA-derived progress and remains a finite 0-100 number. GPT Image 2 and Seedance results can arrive as direct hosted URLs; the SDK preserves those URLs on job.resultUrl and job.getResultUrl() returns the cached URL without requesting a Sogni signed download URL.
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. External API-backed models such as GPT Image 2 and Seedance are Spark-only.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, jpg, or webp for GPT Image 2; most native image models support png or jpg. If not specified, png will be used.TypeScript type definitions for project parameters can be found in ProjectParams docs.
GPT Image 2 is available through the normal image project API:
const project = await sogni.projects.create({
type: 'image',
network: 'fast',
modelId: 'gpt-image-2',
positivePrompt: 'A clean product render of translucent headphones on a white background',
numberOfMedia: 1,
width: 1024,
height: 1024,
gptImageQuality: 'high',
outputFormat: 'webp',
tokenType: 'spark'
});
const imageUrls = await project.waitForCompletion();
For GPT Image 2 edits, pass contextImages; the SDK supports up to 16 context images for this model. Cost estimates can include gptImageQuality, outputFormat, and contextImages so external input-image pricing is represented.
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:
WAN workflows have two model variants optimized for different use cases:
_lightx2v suffix) - Faster inference (4-step), good quality_lightx2v) - Slower inference, best qualityLTX-2.3 models use distilled and dev variants for fast/high-quality generation with native audio. Seedance 2.0 models use the external API path and are available through two canonical multimodal model IDs: seedance-2-0 and seedance-2-0-fast. Both accept optional image, video, and audio references, run at fixed 24fps, and require Spark billing; the Fast model caps output at 720p.
Example 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)ltx23-22b-fp8_t2v_distilled (LTX-2.3 Text-to-Video, fast)ltx23-22b-fp8_i2v_distilled (LTX-2.3 Image-to-Video, fast)ltx23-22b-fp8_v2v_distilled (LTX-2.3 Video-to-Video ControlNet, fast)seedance-2-0 (Seedance 2.0 multimodal video, external API)seedance-2-0-fast (Seedance 2.0 Fast multimodal video, external API, 720p cap)When creating video projects, you can specify:
duration - Duration in seconds. WAN supports 1-10s, LTX-2.3 supports 4-20s, Seedance direct SDK projects currently support 4-15s.fps - Frames per second. WAN supports 16/32 output, LTX-2.3 supports 1-60 native FPS, Seedance is fixed at 24fps.frames - Number of frames. Prefer duration; the SDK calculates model-correct frame counts.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 and v2v workflowsreferenceAudio - Reference audio for sound-to-video workflowreferenceImageUrls - Seedance-only loose image context URLs; combined with referenceImage/referenceImageEnd, max 9 image assetsreferenceVideoUrls - Seedance-only video context URLs; combined with referenceVideo, max 3 video assetsreferenceAudioUrls - Seedance-only audio context URLs; combined with referenceAudio/referenceAudioIdentity, max 3 audio assetshasVideoInput - Estimate-only flag for estimateVideoCost; set this when estimating a canonical Seedance video-input job without passing referenceVideo/referenceVideoUrlsSeedance 2.0 can combine image, video, and audio reference assets in one external API request. Reference limits are up to 9 image assets, 3 video assets, 3 audio assets, and 12 asset files total. Text+audio without at least one image or video reference is not supported by Seedance. URL-array references must be HTTPS URLs that the vendor can fetch; local multi-reference files should be uploaded first, as shown in examples/workflow_partner_seedance_video.mjs. In prompts and creative briefs, refer to attachments by Seedance-style tags: @Image1, @Video1, and @Audio1, counted independently by modality in attachment order. Assign each useful reference a role, such as product identity, motion timing, camera path, edit rhythm, background music, or speech reference. Prefer positive preservation language like "maintain the same product silhouette and logo placement from @Image1"; exact readable text, logos, lip-sync, voice cloning, and real-human-reference behavior still need review. Seedance dispatch omits negative prompts; Wan 2.2 and LTX 2.3 video models can still use negativePrompt. Seedance jobs are Spark-only and should not use SOGNI token fallback.
const 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]);
Seedance 2.0 example:
const project = await sogni.projects.create({
type: 'video',
network: 'fast',
modelId: 'seedance-2-0',
positivePrompt: 'A cinematic neon skyline time lapse, sweeping camera motion',
duration: 5,
fps: 24,
width: 1920,
height: 1088,
tokenType: 'spark'
});
const videoUrls = await project.waitForCompletion();
Seedance multimodal context example:
const project = await sogni.projects.create({
type: 'video',
network: 'fast',
modelId: 'seedance-2-0',
positivePrompt:
'Use @Image1 as the product identity, @Image2 for detail inserts, @Video1 for camera movement, and @Audio1 for music rhythm. Create one cohesive launch spot with smooth continuity and crisp product preservation.',
duration: 8,
fps: 24,
width: 1920,
height: 1088,
referenceImageUrls: [
'https://cdn.example.com/product-front.png',
'https://cdn.example.com/product-detail.png'
],
referenceVideoUrls: ['https://cdn.example.com/motion-reference.mp4'],
referenceAudioUrls: ['https://cdn.example.com/music-reference.m4a'],
tokenType: 'spark'
});
const videoUrls = await project.waitForCompletion();
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 result = await sogni.chat.completions.create({
model: 'qwen3.6-35b-a3b-gguf-iq4xs',
messages: [
{ role: 'system', content: 'You are a helpful assistant.' },
{ role: 'user', content: 'What is the Sogni Supernet?' }
],
max_tokens: 4096,
think: false,
taskProfile: 'general'
});
console.log(result.content);
Qwen3.6-specific preset selection can be hinted with think plus taskProfile:
taskProfile: 'general' + think: true for thoughtful general taskstaskProfile: 'coding' + think: true for precise coding / webdev worktaskProfile: 'general' + think: false for direct everyday responsestaskProfile: 'reasoning' + think: false for analytical non-thinking tasksYou can still override sampling manually with temperature, top_p, top_k,
min_p, presence_penalty, and repetition_penalty.
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.chat.completions.create({
model: 'qwen3.6-35b-a3b-gguf-iq4xs',
messages: [{ role: 'user', content: "What's the weather in Austin?" }],
tools: tools,
tool_choice: 'auto',
think: false,
taskProfile: 'reasoning'
});
Combine LLM intelligence with Sogni's media generation capabilities. The SDK exposes the full canonical hosted creative-tool surface through SogniTools.all (24 tools):
generate_image, edit_image, generate_video, sound_to_video, video_to_video, generate_musicrestore_photo, apply_style, refine_result, change_angle, animate_photo (image-to-video with multi-source fan-out)stitch_video, orbit_video, dance_montage, extend_video, replace_video_segment, overlay_video, add_subtitlesenhance_prompt, compose_script, compose_lyrics, compose_instrumental, compose_workflow, compose_workflow_templatePass SogniTools.all (or individual definitions like generateImageTool, animatePhotoTool, composeScriptTool) to an LLM via the tools parameter, then route tool calls through sogni.chat.hosted.create() / sogni.chat.runs.create() for server-side execution. Generated artifacts are threaded through a per-request media context so later rounds can reference earlier outputs by index (sourceImageIndex, videoIndices, audioIndex, etc.).
For direct /v1/chat/completions hosted-tool execution, media-bearing tool arguments use inline data: URIs. For user-uploaded image/audio/video inputs, use the SDK video project examples or the sogni.workflows wrapper for /v1/creative-agent/workflows; these can consume HTTPS artifact URLs produced by Sogni's upload endpoints. Durable workflows validate explicit steps before the workflow starts and can bind SDK request-level mediaReferences into tool arguments with sourceStepId: "$input_media".
The workflow_text_chat_sogni_tools.mjs example demonstrates the core text-to-image, text-to-video, and text-to-music composition flows. Dedicated workflow examples like workflow_image_edit.mjs, workflow_sound_to_video.mjs, and workflow_video_to_video.mjs cover the asset-backed workflows directly.
sogni_tools parametersogni.chat.hosted.create() (the SDK wrapper for /v1/chat/completions) can inject the canonical creative-tools surface server-side via the sogni_tools parameter. The default creative-tools value injects the full media, composition, and planning surface. sogni_tools: "creative-agent" adds workflow control and asset-manifest tools on top.
Use default sogni_tools: true or sogni_tools: "creative-tools" when you want the full creative media tool surface plus synchronous composition tools: enhance_prompt, compose_script, compose_lyrics, and compose_instrumental.
Notable creative-tools include:
| Tool | Behavior |
|---|---|
restore_photo, apply_style, refine_result, change_angle |
Image-edit adapters backed by the shared image-edit workflow |
animate_photo |
Image-to-video, with multi-source fan-out via sourceImageIndices (composed into one MP4 by default; opt out with stitched: false) |
stitch_video |
Compose selected video clips into one MP4 (with optional audio overlay) |
orbit_video |
Generate orbit clips around a subject and stitch them |
dance_montage |
Generate dance clips and stitch when multi-clip |
extend_video, replace_video_segment |
Extend or replace a bounded segment of an existing video; replacements may trim source windows with replacementStartSeconds / replacementEndSeconds |
overlay_video, add_subtitles |
Burn in text/logo overlays or subtitle cues onto existing videos via ffmpeg |
enhance_prompt |
Expand or adapt rough prompts into model-ready image, video, music, or edit prompts |
compose_script |
Draft scripts, storyboards, trailers, social shorts, campaign beats, or video prompts |
compose_lyrics |
Write vocal song lyrics and suggested musical parameters |
compose_instrumental |
Write instrumental structure and suggested musical parameters |
Composition and post-production tools (stitch_video, orbit_video, dance_montage, animate_photo fan-out, extend_video, replace_video_segment, overlay_video, and add_subtitles) return or update MP4 artifacts. stitch_video concatenates whole clips end-to-end; alternating or interleaved time slices should be represented as repeated replace_video_segment steps with bounded replacement source windows. See the LLM API reference for the full schema list.
import { SogniClient } from '@sogni-ai/sogni-client';
const sogni = await SogniClient.createInstance({
appId: 'creative-agent-demo',
apiKey: process.env.SOGNI_API_KEY,
network: 'fast'
});
const result = await sogni.chat.hosted.create({
model: 'qwen3.6-35b-a3b-gguf-iq4xs',
messages: [{ role: 'user', content: 'Create a 15s trailer-style launch video for this product concept' }],
sogni_tools: 'creative-tools',
sogni_tool_execution: true,
token_type: 'spark'
});
See examples/workflow_creative_agent_tools.mjs for a runnable REST API-key example that can toggle tool surface and server-side execution.
For focused partner Seedance video tests, examples/workflow_partner_seedance_video.mjs starts with a guided workflow picker when run with no arguments. The guided path covers T2V, I2V, IA2V, V2V, the full and fast Seedance tiers where available, hosted workflow execution, native audio, keyframe interpolation, multimodal context, and cost estimation. The command-line path still supports direct scripted calls:
node examples/workflow_partner_seedance_video.mjs
node examples/workflow_partner_seedance_video.mjs "A glass whale swimming through a neon city" --duration 4
node examples/workflow_partner_seedance_video.mjs "A glass whale swimming through a neon city" --fast --duration 4
node examples/workflow_partner_seedance_video.mjs "slow cinematic reveal" --context examples/test-assets/placeholder.jpg
node examples/workflow_partner_seedance_video.mjs "slow cinematic reveal" --context examples/test-assets/placeholder.jpg --fast
node examples/workflow_partner_seedance_video.mjs "the portrait sings with stage lighting" --mode ia2v --context examples/test-assets/placeholder.jpg --audio examples/test-assets/placeholder.m4a
node examples/workflow_partner_seedance_video.mjs "turn the clip into a polished perfume commercial" --video examples/test-assets/placeholder.mp4
node examples/workflow_partner_seedance_video.mjs "Use @Video1 as the source clip, @Video2 for edit rhythm, @Image1 for product identity, @Image2 for palette, and @Audio1 as the music guide. Preserve the product silhouette and create one launch spot." --workflow --mode v2v --video examples/test-assets/placeholder.mp4 --video https://cdn.example.com/motion-2.mp4 --context examples/test-assets/placeholder.jpg --context examples/test-assets/placeholder2.jpg --audio examples/test-assets/placeholder.m4a
Guided mode defaults text-to-video to /v1/creative-agent/workflows so the entrypoint exercises the durable workflow API first. Scripted T2V calls without media still default to /v1/chat/completions unless --workflow is passed. Media modes default to /v1/creative-agent/workflows with explicit input.steps and upload local media from examples/test-assets automatically. Pass --image/--context, --audio, or --video repeatedly to use Seedance multimodal context; the example enforces the vendor limits of 9 image assets, 3 video assets, 3 audio assets, and 12 total assets. --expand-prompt is enabled by default and sends expand_prompt: true so the API runs the shared @sogni/creative-agent Seedance LLM prompt shaper before dispatch; pass --no-expand-prompt only when you want to submit the compact prompt directly. Keep prompts as compact creative briefs with explicit @ImageN/@VideoN/@AudioN role assignments rather than BytePlus JSON. --no-execute prints the workflow request without submitting it; local media is still uploaded first so the printed request contains real HTTPS media URLs. Use --no-estimate when you only want to inspect request construction.
Long-running multi-step creative workflows can be persisted on the server and observed independently of the chat completion that started them. The SDK exposes these authenticated endpoints through sogni.workflows:
sogni.workflows.start({ input, ...options }) — start a durable workflow with an inline plansogni.workflows.start({ workflowId, inputs, ...options }) — run a saved workflow template by idsogni.workflows.get(workflowId) and .list() — inspect snapshotssogni.workflows.events(workflowId) — poll event historysogni.workflows.streamEvents(workflowId, { after, lastEventId }) — SSE event stream with resume supportsogni.workflows.resume(workflowId) — resume a workflow paused in waiting_for_usersogni.workflows.reseed(workflowId, { seedOverrides }) — clone a completed/partial run with fresh seedssogni.workflows.cancel(workflowId) — cooperative cancellationsogni.workflows.templates.{list, get, create, update, delete, fork} — CRUD + fork for the saved workflow templates backing start({ workflowId }).start() accepts exact hosted-tool steps plus optional request-level mediaReferences. The SDK follows the platform camelCase style (mediaReferences, tokenType, maxEstimatedCapacityUnits, and confirmCost) and serializes the REST request to snake_case internally. A dependency with sourceStepId: "$input_media" can inject the matching uploaded image, video, or audio URL or index into a later step. The API validates step arguments before accepting the workflow and again before each execution step, so shape errors fail before billing later media work.
const sogni = await SogniClient.createInstance({
appId: 'creative-workflow-demo',
apiKey: process.env.SOGNI_API_KEY,
disableSocket: true
});
const workflow = await sogni.workflows.start({
tokenType: 'spark',
input: {
title: 'Generated keyframe to video',
steps: [
{
id: 'keyframe',
toolName: 'generate_image',
arguments: {
prompt: 'A graphite sketch of a robot pianist in a smoky jazz club',
model: 'flux2'
}
},
{
id: 'clip',
toolName: 'generate_video',
arguments: {
prompt: 'slow dolly-in, warm stage lights, subtle hand motion',
videoModel: 'ltx23',
duration: 5
},
dependsOn: [{
sourceStepId: 'keyframe',
sourceArtifactIndex: 0,
targetArgument: 'referenceImageIndices',
mediaType: 'image',
transform: 'image_index',
required: true
}]
}
]
},
});
for await (const event of sogni.workflows.streamEvents(workflow.workflowId)) {
console.log(event.event, event.data);
}
See examples/workflow_creative_agent_workflows.mjs for start/list/get/events/stream/cancel coverage. The underlying REST endpoints remain documented in the LLM API durable workflows reference.
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 and LTX-2.3workflow_image_to_video.mjs - Animate static images into videos with WAN 2.2 and LTX-2.3workflow_sound_to_video.mjs - Audio-synchronized video generation with lip-syncworkflow_video_to_video.mjs - Motion transfer, character replacement, and LTX-2.3 ControlNet v2vworkflow_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_vision.mjs - Vision chat with multimodal image understanding (scene description, OCR, object detection, visual analysis, multi-image comparison)workflow_text_chat_tool_calling.mjs - LLM tool calling with built-in tools (weather, time, unit conversion, math)workflow_text_chat_sogni_tools.mjs - Core image/video/music generation through natural language via LLM tool callingworkflow_creative_agent_tools.mjs - Server-side hosted Sogni tool injection for /v1/chat/completionsworkflow_creative_agent_workflows.mjs - Durable /v1/creative-agent/workflows start/list/get/events/stream/cancel through the SDKworkflow_partner_seedance_video.mjs - Focused partner Seedance coverage: chat-completions T2V plus hosted-workflow T2V, I2V, IA2V, V2V, and multimodal context with uploaded mediapromise_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 |
seedance-2-0 |
Seedance 2.0 - External API multimodal video | Full Seedance 2.0 24fps video generation with optional image, video, and audio context |
seedance-2-0-fast |
Seedance 2.0 Fast - 720p external API video | Faster 24fps video generation where fast tiers are enabled |
qwen3.6-35b-a3b-gguf-iq4xs |
Qwen3.6 35B VLM - LLM chat, tool calling & vision | Latest model with 262,144 native context length, reasoning, tool calling, and multimodal image understanding |
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"
node workflow_text_chat_vision.mjs --image photo.jpg
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 |
AGENTS.md |
Public guidance and project context for coding agents |
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.chat.completions.create() for text generation with streaming and tool callingqwen3.6-35b-a3b-gguf-iq4xs VLM for multimodal image understanding with image_url content parts carrying inline base64 JPEG/PNG data: URIs. Vision requests allow up to 20 images, 10MB each, with longest side capped at 1024px. This 1024px dimension cap applies only to the vision image_url path, not to media-generation tool image inputs.llms-full.txt for detailsFull TypeScript API documentation is available at sdk-docs.sogni.ai.