Sogni Python SDK

The official sogni-client 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.

#Install

python -m pip install sogni-client

The package is 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, then copy an API key from dashboard.sogni.ai/api-key:

export SOGNI_API_KEY="your_api_key_here"

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

#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 example for command-line arguments and batch generation.

#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 for supported studio voices, languages, limits, pricing, and complete API examples.

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

#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"])

#Client namespaces

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.

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

#Next steps

• Run the repository's image generation, identity edit, and streaming chat examples.
• Read the Qwen3-TTS model guide for studio voice, voice clone, and voice design parameters.
• Browse the Python client source and tests for the complete public surface.
• Read the API reference for REST endpoints and payloads.
• Use the TypeScript/JavaScript SDK when you need a Node.js or browser client.