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

# Sogni Python SDK

The official [`sogni-client`](https://github.com/Sogni-AI/sogni-client-python) package brings Sogni image, video, audio, and LLM inference to Python. It is async-first, typed, and designed for Python scripts, services, notebooks, agents, and automation running on Python 3.10 or newer.

> Keep API keys in environment variables or a system keychain; never commit them to source control.

## [#](https://docs.sogni.ai/sogni-sdk/python/#install)Install

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

The package is [`sogni-client`](https://pypi.org/project/sogni-client/) on PyPI. Its version tracks the TypeScript client, so `5.36.2` here matches `@sogni-ai/sogni-client` `5.36.2`.

Or clone the repository to run its examples and tests:

```
git clone https://github.com/Sogni-AI/sogni-client-python.git
cd sogni-client-python
python -m pip install -e .
```

Create a Sogni account at [app.sogni.ai](https://app.sogni.ai/), then copy an API key from [dashboard.sogni.ai/api-key](https://dashboard.sogni.ai/api-key):

```
export SOGNI_API_KEY="your_api_key_here"
```

## [#](https://docs.sogni.ai/sogni-sdk/python/#generate-an-image)Generate an image

This complete example starts a project, waits for it to finish, and prints each output URL:

```
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:
        project = await sogni.projects.create(
            type="image",
            model_id="z_image_turbo_bf16",
            positive_prompt="A tiny observatory above a sea of clouds",
            negative_prompt="text, watermark",
            number_of_media=1,
            width=1024,
            height=1024,
            steps=8,
        )

        for url in await project.wait_for_completion():
            print(url)


asyncio.run(main())
```

Creating and closing the client with `async with` is recommended. `SogniClient.create()` generates a unique application ID automatically; pass `app_id="..."` only when you deliberately need a stable socket identity.

## [#](https://docs.sogni.ai/sogni-sdk/python/#edit-a-local-image)Edit a local image

Pass one or two local paths through `context_images`. For a two-image edit, put the base scene first and the identity or detail reference second.

```
project = await sogni.projects.create(
    type="image",
    model_id="krea2_identity_edit_v1_2",
    positive_prompt=(
        "Change only the jacket to vivid sapphire blue. Preserve the exact "
        "facial identity, expression, framing, background, and lighting."
    ),
    number_of_media=1,
    width=1024,
    height=1024,
    steps=10,
    guidance=1,
    token_type="spark",
    context_images=["reference.png"],
)

print(await project.wait_for_completion())
```

Wait without a client-side timeout. A timeout raises `asyncio.TimeoutError` but does not cancel the project, so a short one abandons a render that is still running on the Supernet; the project carries its own runtime budget and the client resumes it across reconnects. Call `project.cancel()` when you actually want to stop it.

See the runnable [`krea_identity_edit.py`](https://github.com/Sogni-AI/sogni-client-python/blob/main/examples/krea_identity_edit.py) example for command-line arguments and batch generation.

## [#](https://docs.sogni.ai/sogni-sdk/python/#generate-speech-with-qwen3-tts)Generate speech with Qwen3-TTS

Qwen3-TTS exposes three audio models for studio voices, voice cloning, and voice design. The prompt is the script to read aloud.

```
project = await sogni.projects.create(
    type="audio",
    model_id="qwen3_tts_1.7b_custom_voice_bf16",
    positive_prompt="Every render on the Supernet runs on somebody else's GPU.",
    number_of_media=1,
    speaker="serena",
    instruct="warm and unhurried, close to the mic",
    output_format="mp3",
)

print(await project.wait_for_completion())
```

Voice Clone uses `qwen3_tts_1.7b_voice_clone_bf16` and requires a 3–30 second `reference_audio` clip. Supply `reference_text` with the exact words spoken in that clip whenever possible; the transcript is the strongest control on how closely the clone preserves the source voice and accent. Voice Design uses `qwen3_tts_1.7b_voice_design_bf16` and requires `instruct` to describe the speaker to invent.

See the [Qwen3-TTS model guide](https://www.sogni.ai/models/qwen3-tts) for supported studio voices, languages, limits, pricing, and complete API examples.

## [#](https://docs.sogni.ai/sogni-sdk/python/#stream-an-llm-response)Stream an LLM response

The socket chat API supports both complete responses and async streaming:

```
stream = await sogni.chat.completions.create(
    model="qwen3.6-35b-a3b-gguf-iq4xs",
    messages=[{"role": "user", "content": "Pitch three surreal album covers."}],
    stream=True,
)

async for chunk in stream:
    print(chunk.get("content", ""), end="", flush=True)
```

Use `sogni.chat.hosted.create(...)` for the hosted OpenAI-compatible completion API. Both paths use the same API key.

## [#](https://docs.sogni.ai/sogni-sdk/python/#run-a-durable-creative-workflow)Run a durable creative workflow

Durable workflows persist server-side so another process can resume them and replay their events:

```
workflow = await sogni.workflows.start(
    input={"prompt": "Create a four-panel character turnaround"},
    idempotency_key="turnaround-001",
)

async for event in sogni.workflows.stream_events(workflow["id"]):
    print(event["event"], event["data"])
```

## [#](https://docs.sogni.ai/sogni-sdk/python/#client-namespaces)Client namespaces

| Namespace | What it covers |
| --- | --- |
| `sogni.projects` | Generation, uploads, model discovery, estimates, progress, and recovery |
| `sogni.chat` | Socket chat, hosted chat, streaming, tools, and durable chat runs |
| `sogni.workflows` | Creative workflows, templates, event streams, resume, and replay |
| `sogni.account` | Login, balances, rewards, transactions, and subscriptions |
| `sogni.replay` | Recorded project and workflow events |
| `sogni.stats` | Supernet and account statistics |

Python `snake_case` arguments are preferred. Common JavaScript-style aliases remain accepted to make migration from the TypeScript client easier. `AsyncSogniClient` is an alias of `SogniClient`; it is not a synchronous wrapper.

## [#](https://docs.sogni.ai/sogni-sdk/python/#authentication-options)Authentication options

API-key authentication is the simplest option for services and scripts:

```
sogni = await SogniClient.create(api_key=os.environ["SOGNI_API_KEY"])
```

The client also supports access and refresh tokens:

```
sogni = await SogniClient.create(auth_type="token")
await sogni.set_tokens(token=access_token, refresh_token=refresh_token)
```

Username/password login and signing are available through `sogni.account.login`. API-key use does not require storing a wallet password.

## [#](https://docs.sogni.ai/sogni-sdk/python/#next-steps)Next steps

-   Run the repository's [image generation](https://github.com/Sogni-AI/sogni-client-python/blob/main/examples/generate_image.py), [identity edit](https://github.com/Sogni-AI/sogni-client-python/blob/main/examples/krea_identity_edit.py), and [streaming chat](https://github.com/Sogni-AI/sogni-client-python/blob/main/examples/stream_chat.py) examples.
-   Read the [Qwen3-TTS model guide](https://www.sogni.ai/models/qwen3-tts) for studio voice, voice clone, and voice design parameters.
-   Browse the [Python client source and tests](https://github.com/Sogni-AI/sogni-client-python) for the complete public surface.
-   Read the [API reference](https://docs.sogni.ai/api-reference/) for REST endpoints and payloads.
-   Use the [TypeScript/JavaScript SDK](https://docs.sogni.ai/sogni-sdk/) when you need a Node.js or browser client.