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.

Beta: Install the client directly from its official GitHub repository while the package surface stabilizes. Keep API keys in environment variables or a system keychain; never commit them to source control.

#Install

Install the latest client from GitHub:

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

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(timeout=900))

See the runnable krea_identity_edit.py example for command-line arguments and batch generation.

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