Sogni: Learn logo

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

Package Use when
@sogni-ai/sogni-intelligence-client (recommended for most agent builders) You want the raw SDK PLUS public-safe creative-agent contracts (ContractRegistry, AssetManifest, RunRecord, hosted-tool validators, structured tool envelopes, the gating/repair/prompt-contract data the platform itself uses). Includes promise-style helpers + n8n compatibility.
@sogni-ai/sogni-client (the raw SDK; this page) You only need direct, low-level access to image/video/audio generation, chat completions, durable runs, and creative workflows — without the contracts layer. The intelligence client depends on this.
@sogni-ai/sogni-protocol (language-neutral JSON artifacts) You're building a non-TypeScript SDK, a codegen pipeline, or just need one schema/manifest without pulling a contracts runtime. Zero runtime deps, pure JSON. Both packages above consume from it.

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.

Get your API key at dashboard.sogni.ai/api-key.

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.

#Quick Start Guide

For runnable examples and recipes, see the Quick Start Guide.

#Further Reading

Last updated 2026-04-21