Production integrations

This page is for teams building a product on Sogni: an app with its own users, a backend that renders on their behalf, or a pipeline that runs every day. It covers which billing to use, which integration path fits your architecture, the limits to size your queue against, and the errors to handle.

#Billing for production workloads

Pay-as-you-go Premium Spark is the plan for production workloads. It has the highest queue priority, the highest per-account concurrency, and no daily fair-use budget on Sogni-hosted models. There is no separate Enterprise plan. Talk to us at [email protected] if your volume needs more than the limits below.

Unlimited plans are fair-use plans for one creator or household. A multi-user product or an unattended 24/7 pipeline should not run on one.

An account can hold an Unlimited plan and Premium Spark at the same time. When it does, the plan pays first by default. To bill Premium Spark on every request, send billing_mode: "tokens" on REST workflow calls, or billingMode: 'tokens' on SDK projects. Otherwise your requests get the plan's concurrency and queue limits, not Premium Spark's. See Plan or tokens.

#Choose an integration path

Your architecture	Use	Why
Serverless functions (Vercel, Lambda, Cloud Run), short-lived request handlers, many parallel invocations	Creative-agent workflows over REST, directly or through an SDK in REST-only mode	Stateless: start, poll, done. Nothing to hold open, and no socket connection per invocation.
A long-running server or worker process	The Sogni SDK with one persistent WebSocket connection	Real-time progress events and direct project control, from one connection that stays up.
An AI agent that plans its own work	Creative Agent Skill or durable chat runs	The agent picks the tools; the platform runs them durably.

Both SDKs have a REST-only mode that opens no socket and needs no app ID. Hosted workflows, chat runs, replay records, and account APIs all work in this mode:

const sogni = await SogniClient.createInstance({
  apiKey: process.env.SOGNI_API_KEY,
  disableSocket: true,
});

sogni = await SogniClient.create(api_key=os.environ["SOGNI_API_KEY"], disable_socket=True)

#Serverless pattern

A workflow runs on Sogni's servers, not inside your function, so your function's time limit does not bound the render.

1. Start. Send the workflow with an Idempotency-Key derived from your own job ID, and store the returned workflow ID. If the call times out, retry it with the same key: you get the workflow the first call created, not a second paid one.
2. Return. Let the handler finish. The workflow keeps running.
3. Observe. From a later invocation, a scheduled job, or the client, read GET /v1/creative-agent/workflows/:id with backoff, or follow /events/stream while a function is alive. Stop at a terminal status: completed, partial_failure, failed, or cancelled.
4. Collect. Artifact URLs are presigned and time-limited. Copy results to your own storage when the workflow finishes.

#Long-running SDK pattern

• Run one process (or a small fixed pool) that holds a connection and takes renders from your own queue.
• Give each connection a stable appId, generated once and saved in config. Reuse it across restarts, and never generate one per render or per process start.
• Keep the connection open between renders. Reconnecting per render adds latency and runs into the connection rules below.

#Limits

Limits apply per account, whether you render through REST workflows or the SDK: both draw on the same account-level render capacity. Numbers are current defaults (September 2026) and can change as network capacity changes.

#Render capacity

	Premium Spark (tokens)	Unlimited plans
Jobs rendering at once	Up to 16, shared across image, video, and audio	Per plan: see Limits & throttling
Jobs queued	Up to 512 per account	Unlimited: 16 media, including 8 videos. Pro: 64 media, including 24 videos.
Daily budget	None on Sogni-hosted models	Daily and monthly fair-use capacity on Fast
Queue priority	Highest paid priority	Below Premium Spark

Jobs beyond the concurrent limit wait in your queue; they are not refused. Third-party vendor models such as Seedance, GPT Image, and HappyHorse do not use Sogni's GPUs and do not count toward the concurrency limit. They share one combined daily spend limit of $250 per account; contact us to raise it.

#Creative-agent workflows

Limit	Default	When exceeded
Active workflows per account	10	409, with details.activeWorkflowCount and details.activeWorkflowLimit
Workflow starts per account	300 per hour	429, error code 126, with Retry-After and retryAfter

A workflow can carry many steps, so batching related renders into one workflow uses one active slot for all of them. A 409 for too many active workflows does not use up your start allowance. The platform also caps overall workflow capacity; a 429 with no retryAfter means the platform is busy, so retry with backoff and jitter.

The start limit can be raised for a production account. Email [email protected] with your account name and expected volume.

#SDK connections

• Up to 5 WebSocket connections at once per account. Opening a sixth closes the new connection with code 4028.
• One connection per appId. Connecting again with the same appId closes the earlier connection.
• Stable app IDs. Each account can introduce only a limited number of new app IDs per UTC day. Past that, connections close with code 4061 until the next UTC day. A fixed set of saved IDs never runs into this.

A client closed with a 4xxx code should not reconnect in a tight loop. Fix the cause (too many connections, a fresh app ID per start), then create a new client.

#Errors to handle

Code	Where	Meaning	What to do
409	Workflow start	Too many active workflows	Wait for one to finish or cancel one. Don't re-send the start in a loop.
429 / 126	Workflow start	Starting too fast	Wait for Retry-After. A start sent sooner is refused again.
429	Any REST call	Rate-limited or platform busy	Honor Retry-After when present. Otherwise back off with jitter and reduce concurrency.
4027	SDK project	Account queue is full	Wait for queued jobs to finish before submitting more.
4029, 4030	SDK project	Platform queue is full	Retry after a short backoff.
4028	SDK connection	Too many connections for this account	Close idle clients; hold fewer, longer-lived connections.
4061	SDK connection	Too many new app IDs today	Reuse saved app IDs.
4064	Project or workflow step	Daily third-party model spend limit reached	Resets each UTC day. Contact us to raise it.

See Getting Started for the REST error envelope, and Idempotency for retry keys.

#Production checklist

• Send billing_mode: "tokens" (REST) or billingMode: 'tokens' (SDK) on every request that should bill Premium Spark.
• Send an Idempotency-Key on every workflow start and reseed, and reuse it on retries.
• Set app_source (REST) or appSource (SDK) to your product name, so support can find your traffic.
• Size your worker pool to the render-capacity limits above, and queue the rest on your side.
• Honor Retry-After; never retry a refusal immediately.
• Keep SDK connections few and long-lived, each with a saved appId.
• Copy finished media to your own storage.
• Record workflow IDs and project IDs in your logs; they are what support needs to trace a render.