Sogni: Learn logo
Markdown

Sogni SDK

The Sogni SDK gives developers direct access to the Sogni Supernet — a DePIN protocol for creative AI inference. Official clients are available for Python and TypeScript/JavaScript. They support image generation and editing, deterministic NVIDIA RTX VSR image upscaling through 16K, video and audio generation, SAM 3.1 video selection masks, LLM chat with streaming and tool calling, and durable creative workflows.

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

#Choose the client that fits

Package Use when
sogni-client for Python (official beta) You want an async-first Python 3.10+ client for scripts, backends, notebooks, agents, or automation. Its API covers generation, uploads, chat, hosted tools, workflows, replay, and account operations.
@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 (raw TypeScript SDK) You need direct, low-level access from Node.js or a browser, including an event-based API for real-time progress. 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. The TypeScript 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

Queued worker-backed generations support optional Priority mode for paid Unlimited members: use priorityMode: true in JavaScript or priority_mode=True in Python, with Fast network and subscription billing. Priority uses 1.5× daily and monthly usage for earlier queue placement, behind Premium Spark, without changing rendering speed, quality or plan limits. Offer it only when the authenticated SDK account reports currentAccount.subscription.capabilities.priorityMode === true; availability may change after reconnecting. Chat and AI writing requests, including HTTP and API-key LLM calls, are not boosted and keep ordinary usage accounting. Omit the option for standard behavior.

#Python 3.10+

The Python client is published on PyPI:

python -m pip install sogni-client

Continue to the Python SDK quickstart for a complete image-generation example, streaming chat, local image editing, and durable workflows.

#TypeScript / JavaScript

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.

Create a developer key at dashboard.sogni.ai/api-keys. Give each app its own key; see API Keys for key types, spending limits and rotation.

#Python with an API key

import asyncio
import os

from sogni_client import SogniClient


async def main() -> None:
    async with await SogniClient.create(
        api_key=os.environ["SOGNI_API_KEY"],
        app_id="my-app-installation",  # stable: generate once and save it
    ) as sogni:
        models = await sogni.projects.wait_for_models()
        print(f"Loaded {len(models)} models")


asyncio.run(main())

A socket client needs a stable app_id: generate it once per installation and reuse it across restarts. A REST-only client (disable_socket=True) needs none.

#TypeScript / JavaScript with an API key

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

const sogni = await SogniClient.createInstance({
  appId: 'my-app-installation', // Required — stable across restarts; generate once and save it
  network: 'fast',       // 'fast' or 'relaxed'
  apiKey: 'your-api-key'
});

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

#TypeScript / JavaScript with a 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 identifies one application installation. Generate it once (a UUID works), save it, and reuse it across restarts. Do not generate a new one each time your code starts. 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.


#Connections and serverless

Each socket client holds one WebSocket connection. An account can have up to 5 open at once, and can introduce only a limited number of new app IDs per day. Keep connections few and long-lived, each with a saved appId.

For serverless functions and other short-lived processes, use REST-only mode. It opens no socket, needs no appId, and runs durable workflows, hosted chat, replay records, and account APIs:

const sogni = await SogniClient.createInstance({
  apiKey: process.env.SOGNI_API_KEY,
  disableSocket: true,
});

Socket-backed projects and chat completions are not available in REST-only mode. See Production Integrations for limits, billing, and architecture guidance.


#Quick Start Guide

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


#Further Reading

Last updated 2026-11-05