Source: https://docs.sogni.ai/sogni-sdk/

# Sogni SDK

The Sogni SDK gives developers direct access to the [Sogni Supernet](https://www.sogni.ai/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.

### [#](https://docs.sogni.ai/sogni-sdk/#who-its-for)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.

### [#](https://docs.sogni.ai/sogni-sdk/#choose-the-client-that-fits)Choose the client that fits

| Package | Use when |
| --- | --- |
| **[`sogni-client` for Python](https://docs.sogni.ai/sogni-sdk/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`](https://docs.sogni.ai/sogni-sdk/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`](https://www.npmjs.com/package/@sogni-ai/sogni-client/v/alpha?activeTab=versions)** _(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`](https://docs.sogni.ai/sogni-sdk/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](https://docs.sogni.ai/sogni-sdk/intelligence-client/#migrating-from-sogni-aisogni-client-wrapper).

* * *

## [#](https://docs.sogni.ai/sogni-sdk/#installation)Installation

### [#](https://docs.sogni.ai/sogni-sdk/#python-310)Python 3.10+

The Python client is published on PyPI:

```
python -m pip install sogni-client
```

Continue to the [Python SDK quickstart](https://docs.sogni.ai/sogni-sdk/python/) for a complete image-generation example, streaming chat, local image editing, and durable workflows.

### [#](https://docs.sogni.ai/sogni-sdk/#typescript-javascript)TypeScript / JavaScript

```
npm install @sogni-ai/sogni-client
```

or with Yarn:

```
yarn add @sogni-ai/sogni-client
```

* * *

## [#](https://docs.sogni.ai/sogni-sdk/#authentication)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](https://app.sogni.ai/) or the [Mac App](https://www.sogni.ai/studio) — you get tokens just for signing up and confirming your email.

Get your API key at [dashboard.sogni.ai/api-key](https://dashboard.sogni.ai/api-key).

### [#](https://docs.sogni.ai/sogni-sdk/#python-with-an-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.

### [#](https://docs.sogni.ai/sogni-sdk/#typescript-javascript-with-an-api-key)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();
```

### [#](https://docs.sogni.ai/sogni-sdk/#typescript-javascript-with-a-username-and-password)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.

* * *

## [#](https://docs.sogni.ai/sogni-sdk/#quick-start-guide)Quick Start Guide

For runnable examples and recipes, see the [Quick Start Guide](https://docs.sogni.ai/developer-tutorials/).

* * *

## [#](https://docs.sogni.ai/sogni-sdk/#further-reading)Further Reading

-   [Python SDK Quickstart](https://docs.sogni.ai/sogni-sdk/python/) — installation, runnable examples, namespaces, and lifecycle guidance
-   [Python Client on GitHub](https://github.com/Sogni-AI/sogni-client-python) — source, tests, and examples
-   [GitHub Repository](https://github.com/Sogni-AI/sogni-client) — full source, examples, changelog
-   [TypeScript API Docs](https://sdk-docs.sogni.ai/) — complete `ProjectParams`, `Job`, `Project` reference
-   [Developer Tutorials](https://docs.sogni.ai/developer-tutorials/) — step-by-step recipes for common workflows
-   [Sogni Intelligence](https://docs.sogni.ai/sogni-intelligence/introduction/) — LLM, agent, and tool-calling capabilities overview
-   [Upscaling Images](https://docs.sogni.ai/sogni-create/studio/creating-images/upscaling-images/) — RTX VSR from 2× through 8K and 16K
-   [Personal LoRAs](https://docs.sogni.ai/api-reference/personal-loras/) — import your own LoRAs and use them in projects (`projects.personalLoras`, `projects.availableLoras({ includePersonal: true })`)
-   [Saved uploads](https://docs.sogni.ai/api-reference/media/#saved-uploads) — reuse subscriber reference files across projects (`projects.assets`)
-   [Media Utilities, 3D and Speech](https://docs.sogni.ai/api-reference/media-utilities/) — background removal, object selection, image-to-3D, video upscaling, and speech
-   [API Reference](https://docs.sogni.ai/api-reference/) — REST API documentation