Sogni SDK

The Sogni SDK (@sogni-ai/sogni-client) is a TypeScript/JavaScript library that gives developers direct access to the Sogni Supernet — a DePIN protocol for creative AI inference. It supports image generation, image editing, video generation, LLM chat with streaming and tool calling, and Sogni Platform Tools that let an LLM generate images, video, and music through natural language. The SDK works in Node.js and browser environments and communicates via a WebSocket connection with an event-based API for real-time progress tracking.

#Who it's for

The Sogni SDK is for developers, startups, agencies, agent builders, and product teams who want to embed Sogni's creative AI capabilities directly in their own applications — without going through the Sogni web or Mac apps. Use it to build image generators, video tools, photobooth experiences, agent workflows, or any product that needs fast, decentralized creative inference.

#Three packages — pick the one that fits

If you previously installed @sogni-ai/sogni-client-wrapper, that package has been renamed to @sogni-ai/sogni-intelligence-client. See the migration note.

#Installation

npm install @sogni-ai/sogni-client

or with Yarn:

yarn add @sogni-ai/sogni-client

#Authentication

To use the Sogni Supernet you need a Sogni account with a positive SOGNI or Spark token balance. Create a free account at app.sogni.ai or the Mac App — you get tokens just for signing up and confirming your email.

#Option 1: API Key (Recommended)

Get your API key at dashboard.sogni.ai — click your Username dropdown in the top-right corner to provision it.

import { SogniClient } from '@sogni-ai/sogni-client';

const sogni = await SogniClient.createInstance({
  appId: 'your-app-id', // Required — unique string, UUID recommended
  network: 'fast',       // 'fast' or 'relaxed'
  apiKey: 'your-api-key'
});

// No login() call needed — authenticated automatically
const models = await sogni.projects.waitForModels();

#Option 2: Username and Password

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

Note: appId must be unique — UUID is recommended. Only one connection per appId is allowed; a second connection with the same ID closes the first. These samples use ES modules (top-level await); wrap in an async function if you use CommonJS.

#Networks

Two worker networks are available:

• fast — High-end GPU workers, optimized for speed. Required for video generation. Higher token cost.
• relaxed — Apple Mac workers, optimized for cost. Supports image generation only. Lower token cost.

Cost scales with total pixel count and inference steps.

#Image Editing Context Images

Image edit projects accept contextImages for reference-guided editing. Model limits are enforced by the SDK and the Supernet: GPT Image 2 edit supports up to 16 context images, Flux.2 Dev supports up to 6, and Qwen Image Edit 2511 supports up to 3.

For GPT Image 2, cost estimates include the number of context images because OpenAI charges image input tokens in addition to output image tokens. The SDK and Sogni Socket pass a context-image count for pricing; Sogni Socket does not download reference images or inspect their dimensions during cost estimation.

#External Media Models

OpenAI GPT Image 2 and ByteDance Seedance 2.0 are external provider-backed models exposed through normal SDK project creation. They require credit card purchased Premium Spark.

External models return direct media URLs when the provider result is already hosted. Recent SDK versions preserve the canonical resultUrl field from job events/REST sync, so job.getResultUrl() can return the cached URL without requesting a Sogni signed download URL. Progress events may use direct provider progress or ETA-derived progress when step counts are not available.

#Quickstart: Generate an Image

import { SogniClient } from '@sogni-ai/sogni-client';

const sogni = await SogniClient.createInstance({
  appId: 'my-app-uuid',
  network: 'fast',
  apiKey: 'your-api-key'
});

await sogni.projects.waitForModels();

const mostPopularModel = sogni.projects.availableModels.reduce((a, b) =>
  a.workerCount > b.workerCount ? a : b
);

const project = await sogni.projects.create({
  type: 'image',
  modelId: mostPopularModel.id,
  positivePrompt: 'A cat wearing a hat',
  negativePrompt: 'low quality, bad quality, watermark',
  steps: 20,
  guidance: 7.5,
  numberOfMedia: 1,
  tokenType: 'spark',
  network: 'fast'
});

const imageUrls = await project.waitForCompletion();
console.log('Image URLs:', imageUrls);
// Images are available for 24 hours

#Image Generation

#Progress Events

Instead of await project.waitForCompletion(), you can listen to events for real-time updates:

project.on('progress', (progress) => {
  console.log('Progress:', progress);
});

project.on('jobCompleted', (job) => {
  console.log('Job done:', job.id, job.resultUrl);
});

project.on('completed', (images) => {
  console.log('All done:', images);
});

project.on('failed', (errorData) => {
  console.error('Failed:', errorData);
});

#FLUX.1 [schnell] Defaults

const fluxDefaults = {
  modelId: 'flux1-schnell-fp8',
  steps: 4,
  guidance: 1
};

#Connection Events

sogni.client.on('connected', ({ network }) => {
  console.log('Connected to Supernet:', network);
});

sogni.client.on('disconnected', ({ code, reason }) => {
  console.log('Disconnected:', code, reason);
});

Full ProjectParams type definition: sdk-docs.sogni.ai

#Image Editing

Use models like qwen_image_edit_2511_fp8 or qwen_image_edit_2511_fp8_lightning for reference-based editing:

import fs from 'fs';

const cnImage = fs.readFileSync('./source.jpg');

const project = await sogni.projects.create({
  type: 'image',
  network: 'fast',
  modelId: 'qwen_image_edit_2511_fp8_lightning',
  numberOfMedia: 1,
  positivePrompt: 'make the background a snowy mountain',
  steps: 4,
  guidance: 7.5,
  controlNet: {
    name: 'instrp2p',
    image: cnImage
  }
});

const urls = await project.waitForCompletion();

See the workflow_image_edit.mjs example for the full reference implementation.

#Video Generation

Video generation requires the fast network and uses Wan 2.2 14B FP8 models. Five workflow types are supported:

Add _lightx2v suffix for faster (4-step) inference; omit for highest quality.

#Text-to-Video

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,  // ~5 seconds at 16fps
  width: 512,
  height: 512
});

const videoUrls = await project.waitForCompletion();
console.log('Video URL:', videoUrls[0]);

#Image-to-Video

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

#Sound-to-Video

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

See the examples directory for Animate-Move, Animate-Replace, and other full workflow examples.

#LLM Chat and Tool Calling

The SDK includes an OpenAI-compatible chat completions API running on Sogni Supernet workers. Supports streaming, multi-turn conversations, reasoning mode, and tool calling.

#Chat Completion

const response = await sogni.projects.chatCompletion({
  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,
  temperature: 0.7
});

console.log(response.choices[0].message.content);

#Tool Calling

const tools = [{
  type: 'function',
  function: {
    name: 'get_weather',
    description: 'Get current weather for a location',
    parameters: {
      type: 'object',
      properties: {
        location: { type: 'string', description: 'City name' }
      },
      required: ['location']
    }
  }
}];

const response = await sogni.projects.chatCompletion({
  model: 'qwen3.6-35b-a3b-gguf-iq4xs',
  messages: [{ role: 'user', content: "What's the weather in Austin?" }],
  tools: tools,
  tool_choice: 'auto'
});

#Sogni Platform Tools

Combine LLM tool calling with Sogni's media generation. The LLM detects when a user wants to create an image, video, or music, enhances the prompt, and calls Sogni's generation APIs automatically:

• "Create an image of a cyberpunk city at night"
• "Generate a video of ocean waves at sunset"
• "Compose a jazz song about the rain"

See workflow_text_chat_sogni_tools.mjs for a complete implementation.

The default server-side chat tool surface is the creative-tools family used by Sogni Chat, including image adapters, multi-source animation, stitch/orbit/dance composition, video extension, segment replacement, overlays, subtitles, image/video analysis, metadata extraction, enhance_prompt, compose_script, compose_lyrics, and compose_instrumental. Use sogni.chat.hosted.create() as the SDK wrapper for /v1/chat/completions when you want API-hosted tool injection and execution from an app or server. Set sogni_tools: "creative-agent" when you want that same creative-tools surface plus workflow control, asset-manifest tools, compose_workflow, and compose_workflow_template, or sogni_tools: false for text-only chat. Use /v1/creative-agent/workflows through sogni.workflows when you need durable state, SSE event replay, cancellation, explicit hosted steps, or request-level media references bound into workflow steps. sogni.workflows.start() accepts either an inline input plan or a saved workflowId plus inputs; the same namespace exposes resume(id), reseed(id, { seedOverrides }), and templates.{list,get,create,update,delete,fork} for saved workflow templates.

#Featured Models

#Further Reading

• GitHub Repository — full source, examples, changelog
• TypeScript API Docs — complete ProjectParams, Job, Project reference
• Developer Tutorials — step-by-step recipes for common workflows
• Sogni Intelligence — LLM, agent, and tool-calling capabilities overview
• API Reference — REST API documentation