From Zero to AI Generation: A Walkthrough of the Sogni API

If you've previously integrated with an OpenAI-compatible image generation API — whether DALL-E 3, a Stable Diffusion API wrapper, or a self-hosted inference endpoint — then migrating to or adding Sogni takes less time than you might expect. The endpoint structure, authentication headers, and response schemas follow the same conventions. What's different is the network layer underneath and a few extended parameters that take advantage of our multi-model, distributed architecture.

This walkthrough covers the full path from API key to first successful generation, then dives into the parameters and patterns that experienced developers use to get the most out of the network.

Authentication and Base Setup

Authentication uses a standard Bearer token pattern. You pass your API key in the Authorization header exactly as you would with any OpenAI-compatible endpoint:

POST https://api.sognix.com/v1/images/generations
Authorization: Bearer sgn_your_api_key_here
Content-Type: application/json

If you're using the Python SDK:

from sogni import Sogni

client = Sogni(api_key="sgn_your_api_key_here")

response = client.images.generate(
    model="stable-diffusion-xl-base",
    prompt="A concept art scene of a coastal megacity at dusk, cinematic lighting",
    size="1024x1024",
    n=1
)

print(response.data[0].url)

The response schema is OpenAI-compatible — data is a list of objects with either a url field (hosted URL) or b64_json (base64-encoded PNG), depending on your response_format parameter. URLs expire after 60 minutes by default; download and store the output on your side if persistence is needed.

Model Selection: The Part That's Unique to Sogni

The model parameter is where Sogni diverges most meaningfully from a single-model API. Rather than a fixed model version, you're selecting from a catalog of models running across the network — each with different characteristics for resolution, style, speed, and VRAM requirements.

A few models worth knowing for different use cases:

• stable-diffusion-xl-base — SDXL base; strong all-around, excellent prompt adherence, 1024×1024 native resolution. Good default for most applications.
• flux-schnell — FLUX.1-schnell distilled; very fast inference (typically 4–8 steps), optimized for iteration speed over maximum quality. Useful when you're generating many variations.
• flux-dev — FLUX.1-dev; higher quality output, more nuanced composition, 12–20 steps typical. Better for final outputs.
• stable-diffusion-3-5 — SD 3.5 architecture with improved text handling and structural coherence. Strong for designs with readable text elements or precise compositional requirements.

Model availability on the network is dynamic — the scheduler routes to nodes with the requested model warm-cached. If a specific model has low node availability at a given moment, you'll see slightly higher latency while the network warms up a cold node. In practice, the popular models above maintain warm cache across the network and rarely cause visible latency spikes.

Extended Parameters You'll Actually Use

Beyond the base OpenAI-compatible parameters, the Sogni API accepts a sogni_params object for network-specific controls:

response = client.images.generate(
    model="flux-dev",
    prompt="Product photography of a ceramic coffee mug, clean white background, soft diffused light",
    size="1024x1024",
    n=4,
    sogni_params={
        "negative_prompt": "blurry, low quality, distorted handles",
        "steps": 20,
        "cfg_scale": 7.0,
        "seed": 42,
        "scheduler": "euler_ancestral"
    }
)

Key parameters:

• negative_prompt — Diffusion models respond to negative guidance; this is often the fastest way to remove unwanted artifacts. For product photography, excluding "background clutter, shadows, reflections" typically improves outputs more than adding more positive description.
• steps — The number of denoising steps. More steps generally improve coherence up to a point (model-dependent; SDXL saturates around 40–50, FLUX-schnell is designed for 4–8). Higher steps = higher latency and higher credit cost.
• cfg_scale — Classifier-free guidance scale. Higher values increase prompt adherence but can reduce naturalness; typical range is 5–12. Values above 15 tend to produce oversaturated, artifact-prone outputs.
• seed — Fix the seed to reproduce a specific composition. Useful in development when you want to iterate on prompt changes while holding the underlying structure constant.

Batch Generation and Async Jobs

For applications generating large volumes — e-commerce product visualizers, design variation tools, batch rendering pipelines — the synchronous single-request pattern creates unnecessary bottlenecks. The Sogni API supports two patterns for scale:

Parallel requests with n: Setting n to 4 or 8 distributes the job across multiple nodes simultaneously. Your single API call fans out and returns when all n images are ready. This is the simplest pattern and works well for small batches.

Async job submission: For batches of 20+ images or long video generation jobs, use the /v1/jobs endpoint to submit asynchronously and poll for completion:

# Submit async job
job = client.jobs.create(
    model="flux-dev",
    prompt="Character concept sheet, front and side view, fantasy warrior",
    size="1024x1024",
    n=20,
    sogni_params={"steps": 25}
)

# Poll until complete
import time
while job.status not in ("completed", "failed"):
    time.sleep(2)
    job = client.jobs.retrieve(job.id)

if job.status == "completed":
    for image in job.output:
        print(image.url)

The async pattern removes the HTTP timeout constraint and allows the scheduler to spread the job across available nodes over time rather than trying to fulfill it simultaneously. For very large batches, this can actually complete faster than parallel synchronous requests because it doesn't compete for instantaneous node availability.

Error Handling and the Differences That Matter

Error responses follow OpenAI conventions — HTTP status codes with a JSON body containing error.type and error.message. The error types you'll encounter that differ from a single-model API:

• model_unavailable — The requested model has insufficient warm nodes at this moment. Retry with backoff, or switch to a fallback model.
• insufficient_credits — Your account credit balance is below the cost of the requested generation. This is distinct from authentication failure.
• vram_constraint — The requested resolution or model combination exceeds what the current node pool can serve. Reduce resolution or use a lighter model variant.

We're not saying these errors are frequent — in normal operation, the scheduler handles node selection transparently. But building retry logic around model_unavailable with a fallback model chain is good practice for any production application.

The 10% You Need to Know

The 90% that's identical to any OpenAI-compatible image API: endpoint structure, auth headers, request/response schema, the n and size parameters. The 10% that's Sogni-specific: the sogni_params extended object for diffusion controls, the multi-model catalog and its warm-cache implications, the async job endpoint for batch workloads, and the network-specific error types. Understanding those four things gets you to production-ready integration with full control over generation quality and throughput.