Sogni: Learn logo

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, 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

#Python 3.10+

The Python client is in beta. Install the latest version directly from its official GitHub repository:

python -m pip install "sogni-client @ git+https://github.com/Sogni-AI/sogni-client-python.git@main"

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.

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

#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"]) as sogni:
        models = await sogni.projects.wait_for_models()
        print(f"Loaded {len(models)} models")


asyncio.run(main())

SogniClient.create() creates a unique application ID automatically. Pass app_id="..." only when you deliberately need a stable socket identity.

#TypeScript / JavaScript with an 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();

#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 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-08-25