Sogni SDK for JavaScript & Node.js

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.

Features

• 🎨 Image Generation - Create images with the latest frontier Open Source models like Stable Diffusion, Qwen Image, Z-Image Turbo, and Flux
• 🎨 Image Edit - Modify, merge, restyle, and transform images using prompts and/or multiple reference images using powerful models like Qwen Image Edit.
• 🎬 Video Generation - Generate videos using Wan 2.2 14B FP8 models with five workflow types:
  • Text-to-Video (t2v) - Generate videos from text prompts
  • Image-to-Video (i2v) - Animate static images
  • Sound-to-Video (s2v) - Generate videos synchronized with audio
  • Animate-Move - Transfer motion from reference video to image subject
  • Animate-Replace - Replace subjects in videos while preserving motion
• ⚡ Fast & Relaxed Networks - Choose between high-speed GPU network or cost-effective Mac network
• 🔄 Real-time Progress - Event-based API with progress tracking and live updates
• 🎯 Advanced Controls - Fine-tune generation with samplers, schedulers, ControlNets, and more
• 🤖 LLM Text Generation - Chat completions with streaming, multi-turn conversations, and thinking/reasoning mode via OpenAI-compatible API
• 🔧 LLM Tool Calling - Define custom tools (functions) that the LLM can invoke during conversations for real-time data and actions
• 🎨🎬🎵 Sogni Platform Tools - Generate images, reference-guided image edits, videos, audio-driven videos, video transforms, and music through natural language chat
• 🤖 Hosted Creative Tools - Use the default 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 tools
• ⏱️ Durable Creative Workflows - Persistent server-side multi-step workflows with SSE event streaming, Last-Event-ID resume, and cooperative cancellation via /v1/creative-agent/workflows
• 👁️ Vision Chat - Multimodal image understanding with scene description, OCR, object detection, visual analysis, and multi-image comparison via Qwen3.6 VLM

Migration notes

v3.x.x to v4.x.x

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, video and audio. See code examples below.
• numberOfImages renamed to numberOfMedia
• hasResultImage in Job class is now hasResultMedia
• Job and Project classes now have type property that can be image, video or audio

Installation

Add library to your project using npm or yarn:

npm install @sogni-ai/sogni-client

or

yarn add @sogni-ai/sogni-client

Core concepts

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.

Supernet Types

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.

Inference definitions: Projects and Jobs

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.

Client initialization

To initialize a client, you need to provide appId, and account credentials.

Option 1: API Key Authentication (Recommended)

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.

Option 2: Username & Password Authentication

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:

• These samples assume you are using ES modules, which allow 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.
• Only one connection per appId is allowed. If you try to connect with the same appId multiple times, the previous connection will be closed.

Connection metadata and event subscriptions

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.

Agent integrations can optionally declare connection and workload attribution without changing appSource. Defaults are immutable and per-request overrides are isolated, so concurrent operations cannot leak lineage into one another:

const sogni = await SogniClient.createInstance({
  appId: 'your-app-id',
  appSource: 'my-agent-integration',
  apiKey: 'your-api-key',
  attribution: {
    connection: {
      interactionKind: 'external_agent',
      agentFramework: 'codex',
      agentSurface: 'plugin'
    },
    workload: {
      workloadKind: 'agent_mediated',
      agentFramework: 'codex',
      agentSurface: 'plugin',
      executionMode: 'server'
    }
  }
});

await sogni.projects.create({
  type: 'image',
  modelId: 'z_image_turbo_bf16',
  positivePrompt: 'A cinematic mountain observatory',
  numberOfMedia: 1,
  attribution: {
    operationScope: 'child',
    rootOperationId: 'turn-123',
    parentOperationId: 'tool-call-456'
  }
});

The SDK supplies the project/job operation ID when it is omitted. Standalone attributed calls default to top_level; child calls should provide their stable root and immediate parent IDs. All attribution is optional, normalized again by the server, and excluded entirely from the wire for callers that do not configure it.

Usage

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);
});

Subscription entitlements

The account API exposes the public subscription plan catalog and the current wallet's entitlement snapshot:

const plans = await sogni.account.getSubscriptionPlans();

const subscription = await sogni.account.refreshSubscription();
if (sogni.account.currentAccount.isUnlimited) {
  console.log('Unlimited tier:', subscription.tier);
}

currentAccount.isUnlimited is true when the latest entitlement snapshot has active: true and tier is either unlimited or unlimited_pro. The server keeps active true for entitled states until access actually ends: trials and cancel-at-period-end windows remain entitled, with currentPeriodEnd reflecting the paid-through date. Canceling during a free trial is the exception: it ends Unlimited access immediately by default, so the next snapshot reports active: false. A grace_period snapshot is never entitled and returns active: false: it means the provider (Apple billing grace / Google Play grace / Stripe retries) is retrying the renewal payment, and unlimited render access is paused while the retry is in progress — render submissions under the plan return a specific error from the platform explaining that the renewal payment is being retried and that unlimited access resumes once it succeeds. Renders can still be paid with Spark/SOGNI in the meantime, and unlimited access resumes automatically when the renewal succeeds. During grace the snapshot's effective period end indicates the payment-retry window, not access. Period dates are ISO timestamp strings.

A canceled-but-still-paid subscription carries cancelAtPeriodEnd: true and keeps access until currentPeriodEnd. When a downgrade or plan switch is scheduled for the next renewal, the snapshot may also carry scheduledTier, scheduledTerm, and scheduledChangeAt (ISO timestamp) — absent when no change is pending — so UIs can render "Your plan will change to X on date" messaging while the current tier keeps its benefits.

When a job is explicitly submitted with billingMode: 'subscription' and the subscription cannot cover it, the platform rejects the job with a subscription-specific error code, exported as SUBSCRIPTION_ERROR_CODES from the package root:

• 4078 (NOT_ENTITLED) — no active subscription entitlement covers the job.
• 4079 (QUEUE_CAP) — the subscription's concurrent job queue cap was reached.
• 4080 (GRACE_RETRY) — the subscription is in its billing-grace window: the renewal payment is being retried and unlimited access is paused until it succeeds. On 4080, offer the user a "pay with Spark/SOGNI" fallback (token billing) instead of auto-retrying the subscription job in a loop — it will keep failing until the renewal succeeds.

billingMode ('auto' | 'subscription' | 'tokens', exported as BillingMode) is accepted by project params, creative workflows (sogni.workflows.start(), resume(), and reseed(), where it serializes as billing_mode), and all three chat transports: sogni.chat.completions.create() (socket), sogni.chat.hosted.create() (REST /v1/chat/completions), and sogni.chat.runs.create() (durable runs, where it serializes as billing_mode).

Chat job failures preserve this error contract. Streamed and non-streaming chat completions, hosted REST chat, and durable chat runs fail with a ChatJobError (exported from the package root): .message stays the human-readable server message, while code/errorCode carry the wire code string (e.g. '4080'), errorType carries the server's tag (e.g. 'subscription_unavailable'), and the subscriptionErrorCode getter maps the code back to the numeric SUBSCRIPTION_ERROR_CODES value when applicable — so apps can branch without string-matching.

Unlimited fair-use accounting and enforcement are handled dynamically by the Sogni socket service. The SDK does not expose per-period usage counters or plan limit tables for clients to store or display as durable user-facing limits.

To start Stripe checkout, use a plan's planId (unlimited or unlimited_pro) and term (monthly or annual). Checkout and portal sessions require user authentication; API-key auth is rejected for those browser redirect operations.

const { url } = await sogni.account.createSubscriptionCheckout('unlimited_pro', 'annual', {
  redirectType: 'web',
  appSource: 'my-integration'
});
window.location.href = url;

const portal = await sogni.account.createSubscriptionPortalSession();
window.location.href = portal.url;

Image Generation

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
};

Creating an image project

// 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.

Getting project status and results

In general, there are 2 ways to work with API:

1. Using promises or async/await syntax.
2. Listening to events on Project and Job class instances.

Using promises

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);

Using events

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.

Project parameters

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 2048
• height - if 'sizePreset' is set to 'custom' you may pass a custom pixel height between 256 and 2048
• steps - 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 Buffer
• startingImageStrength - 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

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.

Detecting available output presets

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

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.

Schedulers

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'
 }
 */

ControlNets

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:
  • canny
  • depth
  • inpaint
  • instrp2p
  • lineart
  • lineartanime
  • mlsd
  • normalbae
  • openpose
  • scribble
  • segmentation
  • shuffle
  • softedge
  • tile
  • instantid
• image - input image. Image size should match the size of the generated image. Can be File, Blob or Buffer
• strength - ControlNet strength 0 to 1. 0 full control to prompt, 1 full control to ControlNet
• mode - How control and prompt should be weighted. Can be:
  • balanced - (default) balanced, no preference between prompt and control model
  • prompt_priority - the prompt has more impact than the model
  • cn_priority - the controlnet model has more impact than the prompt
• guidanceStart - step when ControlNet first applied, 0 means first step, 1 means last step. Must be less than guidanceEnd
• guidanceEnd - step when ControlNet last applied, 0 means first step, 1 means last step. Must be greater than guidanceStart

Example:

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;
}

Video Generation (WAN 2.2, LTX-2.3, Seedance 2.0 & Happy Horse 1.1)

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.

Available Wan 2.2 Workflows

The Wan 2.2 model family supports five distinct video generation workflows:

1. Text-to-Video (t2v) - Generate videos from text prompts
2. Image-to-Video (i2v) - Animate a static image into a video (First and Last Frame supported)
3. Sound-to-Video (s2v) - Bring a character in an image to life with video and audio synchronization including lip syncing
4. Animate-Move - Transfer character motion and emotion from a reference video to a subject from an image into a new video
5. Animate-Replace - Replace a subject in a video while preserving motion

Model Variants

WAN workflows have two model variants optimized for different use cases:

• Speed variant (with _lightx2v suffix) - Faster inference (4-step), good quality
• Quality variant (without _lightx2v) - Slower inference, best quality

LTX-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 three canonical multimodal model IDs: seedance-2-0, seedance-2-0-mini, and seedance-2-0-fast. All accept optional image, video, and audio references, run at fixed 24fps, and require Spark billing; the full model supports up to 4K, while Mini and Fast cap output at 720p. Happy Horse 1.1 is an external-API video model with text-to-video, image-to-video, and reference-to-video modes (happyhorse-1.1-t2v / -i2v / -r2v); it accepts image-only references (no video or audio reference assets), and is Spark-only.

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-10eros-v1.4-fp8mixed_i2v (LTX-2.3 10Eros v1.4 Image-to-Video, 30GB+ workers, explicit safety-filter disablement required)
• ltx23-22b-fp8_v2v_distilled (LTX-2.3 Video-to-Video ControlNet, fast)
• seedance-2-0 (Seedance 2.0 multimodal video, external API, 4K capable)
• seedance-2-0-mini (Seedance 2.0 Mini multimodal video, external API, 720p cap)
• seedance-2-0-fast (Seedance 2.0 Fast multimodal video, external API, 720p cap)
• happyhorse-1.1-t2v (Happy Horse 1.1 Text-to-Video, external API, image-only references)
• happyhorse-1.1-i2v (Happy Horse 1.1 Image-to-Video, external API, one first-frame image)
• happyhorse-1.1-r2v (Happy Horse 1.1 Reference-to-Video, external API, 1-9 reference images)

The repository does not bundle sample prompts or input media for the 10Eros model. Creators who choose to use it must provide their own prompt and image to examples/workflow_image_to_video.mjs. Optional test prompts and images are available from the model author's sample gallery.

Video Parameters

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 pixels
• height - Video height in pixels
• steps - Increase inference steps to increase quality
• seed - Random seed for reproducibility
• referenceImage - Reference image for workflows that require it (i2v, s2v, animate-move, animate-replace)
• referenceVideo - Reference video for animate and v2v workflows
• referenceAudio - Reference audio for sound-to-video workflow
• referenceImageUrls - Loose image context URLs for Seedance and Happy Horse (Happy Horse r2v takes 1-9 reference images here); combined with referenceImage/referenceImageEnd, max 9 image assets
• referenceVideoUrls - Seedance-only video context URLs; combined with referenceVideo, max 3 video assets
• referenceAudioUrls - Seedance-only audio context URLs; combined with referenceAudio/referenceAudioIdentity, max 3 audio assets
• hasVideoInput - Estimate-only flag for estimateVideoCost; set this when estimating a canonical Seedance video-input job without passing referenceVideo/referenceVideoUrls

Seedance 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.

Text-to-Video Example

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: 1080,
  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: 1080,
  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();

Image-to-Video Example

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();

Sound-to-Video Example

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();

Animate-Move Example

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();

Animate-Replace Example

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();

LLM Text Generation & Tool Calling

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).

Chat Completions

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 tasks
• taskProfile: 'coding' + think: true for precise coding / webdev work
• taskProfile: 'general' + think: false for direct everyday responses
• taskProfile: 'reasoning' + think: false for analytical non-thinking tasks

You can still override sampling manually with temperature, top_p, top_k, min_p, presence_penalty, and repetition_penalty.

LLM Tool Calling (Function Calling)

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'
});

Sogni Platform Tools — Generate Media via Chat

Combine LLM intelligence with Sogni's media generation capabilities. The SDK exposes the full canonical hosted creative-tool surface through SogniTools.all (24 tools):

• Generation — generate_image, edit_image, generate_video, sound_to_video, video_to_video, generate_music
• Image adapters — restore_photo, apply_style, refine_result, change_angle, animate_photo (image-to-video with multi-source fan-out)
• Video composition / post-production — stitch_video, orbit_video, dance_montage, extend_video, replace_video_segment, overlay_video, add_subtitles
• Synchronous composition and planning — enhance_prompt, compose_script, compose_lyrics, compose_instrumental, compose_workflow, compose_workflow_template

Pass 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.).

When your app already knows the exact synchronous composition/planning tool and JSON arguments, skip the dispatcher round and call sogni.chat.hosted.executeTool() directly. Direct execution supports enhance_prompt, compose_script, compose_lyrics, compose_instrumental, compose_workflow, and compose_workflow_template; long-running media generation still belongs on hosted chat/runs or sogni.workflows.

const direct = await sogni.chat.hosted.executeTool({
  tool: 'enhance_prompt',
  arguments: {
    prompt: 'A cinematic portrait of a glass robot',
    destination_tool: 'generate_image'
  },
  tokenType: 'spark'
});

console.log(direct.data.message);

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. workflow_direct_creative_tool.mjs demonstrates direct one-call execution for known synchronous tools. 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.

Hosted Tool Surfaces — sogni_tools parameter

sogni.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.

See examples/workflow_direct_creative_tool.mjs when you already know the hosted synchronous tool to run and want to call it without asking the LLM to select a tool first.

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.

Durable Creative Workflows (server-side)

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 plan
• sogni.workflows.start({ workflowId, inputs, ...options }) — run a saved workflow template by id
• sogni.workflows.get(workflowId) and .list() — inspect snapshots
• sogni.workflows.events(workflowId) — poll event history
• sogni.workflows.streamEvents(workflowId, { after, lastEventId }) — SSE event stream with resume support
• sogni.workflows.resume(workflowId) — resume a workflow paused in waiting_for_user
• sogni.workflows.reseed(workflowId, { seedOverrides }) — clone a completed/partial run with fresh seeds
• sogni.workflows.cancel(workflowId) — cooperative cancellation
• sogni.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.

Code Examples

The examples directory contains working examples for all workflows:

Image Workflow Examples

• workflow_text_to_image.mjs - Text-to-image generation with multiple model options
• workflow_image_edit.mjs - Reference-based image generation using context images

Video Workflow Examples

• workflow_text_to_video.mjs - Text-to-video generation with WAN 2.2 and LTX-2.3
• workflow_image_to_video.mjs - Animate static images into videos with WAN 2.2 and LTX-2.3
• workflow_sound_to_video.mjs - Audio-synchronized video generation with lip-sync
• workflow_video_to_video.mjs - Motion transfer, character replacement, and LTX-2.3 ControlNet v2v

LLM Text Chat, Vision & Tool Calling Examples

• workflow_text_chat.mjs - Single-turn chat completion (non-streaming)
• workflow_text_chat_streaming.mjs - Streaming chat with token-by-token output
• workflow_text_chat_multi_turn.mjs - Multi-turn conversation with history, in-chat commands, and session stats
• workflow_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 calling
• workflow_creative_agent_tools.mjs - Server-side hosted Sogni tool injection for /v1/chat/completions
• workflow_creative_agent_workflows.mjs - Durable /v1/creative-agent/workflows start/list/get/events/stream/cancel through the SDK
• workflow_partner_seedance_video.mjs - Focused partner Seedance coverage: chat-completions T2V plus hosted-workflow T2V, I2V, IA2V, V2V, and multimodal context with uploaded media

Basic Examples

• promise_based.mjs - Image generation using promises/async-await
• event_driven.js - Image generation using event listeners

Featured Models

The 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 | | krea2_turbo_fp8_scaled | Krea 2 Turbo - Fast 8-step, strong in-image text | Text-heavy images and fast iteration, up to 2K | | krea2_identity_edit_v1_2 | Krea 2 Identity Edit LoRA v1.2 - Identity editing | Preserve a subject across edits with 1-2 reference images | | chroma1-hd_fp8_scaled | Chroma1-HD - Final high-res Chroma (uncensored) | Highest-fidelity Chroma output, LoRA-capable | | flux2_dev_fp8 | Flux.2 [dev] - Pro quality, context images | Professional images and reference-guided editing (up to 6 context images) | | 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 - 4K external API multimodal video | Full Seedance 2.0 24fps video generation with optional image, video, and audio context | | seedance-2-0-mini | Seedance 2.0 Mini - 720p external API video | Fastest, lower-cost 24fps Seedance video generation | | seedance-2-0-fast | Seedance 2.0 Fast - 720p external API video | Legacy faster 24fps video generation where fast tiers are enabled | | dark_beast_z_image_turbo_v9_bf16 | Dark Beast Z-Image Turbo v9 - Community (uncensored) | Uncensored, fast Z-Image fine-tune (2K output needs a 24GB+ VRAM worker) | | dark_beast_krea2_fp8 | Dark Beast KREA 2 - Community (uncensored) | Uncensored Krea 2 fine-tune (2K output needs a 24GB+ VRAM worker) | | dark_beast_krea2_identity_edit_v1_2 | Dark Beast Krea 2 Identity Edit - Community | Uncensored identity-preserving Krea 2 edit LoRA with 1-2 reference images | | one_obsession_v22_fp16 | One Obsession v22 - Community (Illustrious/anime) | Anime/illustration checkpoint, LoRA-capable | | 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:

• Interactive model and parameter selection
• Balance checking and cost confirmation
• Real-time progress tracking with ETA
• Error handling with detailed feedback
• Automatic file download and preview

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

AI Assistant Resources

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.

For AI Assistants

When helping users generate images, videos, or use LLM features with Sogni:

1. Image generation: Use type: 'image' with models like flux1-schnell-fp8
2. Video generation: Use type: 'video' with network: 'fast' (required)
3. Audio generation: Use type: 'audio' with ACE-Step 1.5 models
4. LLM text chat: Use sogni.chat.completions.create() for text generation with streaming and tool calling
5. Sogni Platform Tools: Combine LLM tool calling with Sogni media generation to create images, image edits, videos, audio-driven videos, video transforms, and music from natural language
6. Vision chat: Use qwen3.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.
7. WAN 2.2, LTX-2.3, and Seedance: These video families have different duration/FPS behaviors - see llms-full.txt for details

API Documentation

Full TypeScript API documentation is available at sdk-docs.sogni.ai.

Support

• Issues: GitHub Issues
• Documentation: docs.sogni.ai
• Website: sogni.ai