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:
appIdidentifies 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 perappIdis allowed; a second connection with the same ID closes the first. These samples use ES modules (top-levelawait); 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
- Python SDK Quickstart — installation, runnable examples, namespaces, and lifecycle guidance
- Python Client on GitHub — source, tests, and examples
- GitHub Repository — full source, examples, changelog
- TypeScript API Docs — complete
ProjectParams,Job,Projectreference - Developer Tutorials — step-by-step recipes for common workflows
- Sogni Intelligence — LLM, agent, and tool-calling capabilities overview
- Upscaling Images — RTX VSR from 2× through 8K and 16K
- Personal LoRAs — import your own LoRAs and use them in projects (
projects.personalLoras,projects.availableLoras({ includePersonal: true })) - Saved uploads — reuse subscriber reference files across projects (
projects.assets) - Media Utilities, 3D and Speech — background removal, object selection, image-to-3D, video upscaling, and speech
- API Reference — REST API documentation