Getting Started

#Introduction

The Sogni REST API lives at https://api.sogni.ai. One surface covers an OpenAI-compatible chat endpoint, synchronous creative tools, a durable agent runtime, a creative-workflow engine, project status, account balances, worker analytics, and model discovery. Hosted chat and workflows stream over Server-Sent Events; everything else is an ordinary JSON read or write.

#What's here

#Quick start

The shortest path to a result: a chat completion that runs Sogni creative tools server-side.

curl https://api.sogni.ai/v1/chat/completions \
  -H "Authorization: Bearer $SOGNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Generate a cinematic image of a neon alley in Tokyo during rain."}
    ]
  }'

#Authentication

Authenticated endpoints accept a bearer token in the Authorization header. Create API keys on the API Keys page of your Sogni dashboard. Public endpoints, including aggregate worker analytics and generation-model discovery, do not require a key.

Authorization: Bearer YOUR_API_KEY

#Two credential types

• API keys belong to one account and are meant for servers, SDKs and agents. They are required for durable chat runs and creative workflow execution. An account can hold up to 99: developer keys (sogni_dev_…) for apps and the API, worker keys (sogni_wkr_…) for GPU workers only, and the account's Original key, a UUID that keeps working everywhere. Developer keys can have daily, monthly and lifetime spending limits. See API Keys.
• Session tokens are short-lived browser JWTs issued by the Sogni auth flow. Most read endpoints accept either credential type.

The api-key: YOUR_API_KEY header is also accepted. Never send a key in a URL.

#Versioning

Each endpoint has its own versioned path. Most use /v1/*; newer-shape replacements include owner-scoped project status at /v2/projects/:id and account balances at /v4/account/balance. Use the exact path shown for each endpoint. Do not change the version prefix across your whole integration.

#Errors

The API uses standard HTTP status codes. Successful responses return 200, 201, or 202; failures return 4xx for caller mistakes and 5xx for server-side problems. Error bodies are JSON.

#Error envelopes

LLM routes (/v1/chat/completions, /v1/models) emit the OpenAI-compatible error shape:

{
  "error": {
    "message": "'messages' is required and must be a non-empty array",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_request_error"
  }
}

All other endpoints emit the Sogni envelope:

{
  "status": "error",
  "errorCode": 102,
  "message": "Creative workflow requires input.steps"
}

Sogni envelopes may also include details (structured context, such as why a 409 happened) and retryAfter in seconds. OpenAI-shaped errors may include details. The API's rate limiter uses the Sogni envelope on 429 and also keeps "error": "Too Many Requests" for older clients. Workflow template validation failures return { "status": "error", "data": { "validation": { "issues": [ … ] } } }. Branch on the HTTP status first.

#403 with error code: 1010

A 403 whose body is the plain text error code: 1010, not one of the JSON envelopes above, comes from Cloudflare, which sits in front of the API. Cloudflare's Browser Integrity Check rejects the default User-Agent header that Python's standard library sends (Python-urllib/3.x), so urllib.request calls are refused before they reach the API. The API key is never checked, so this error says nothing about your key or account. Some anonymous read-only routes, such as the public model catalog, skip the check. That is why they can succeed from the same script while authenticated calls fail.

Send an explicit User-Agent that names your app on every request:

import os, urllib.request

req = urllib.request.Request(
    "https://api.sogni.ai/v2/account/me",
    headers={
        "User-Agent": "my-app/1.0",
        "Authorization": f"Bearer {os.environ['SOGNI_API_KEY']}",
    },
)
with urllib.request.urlopen(req) as res:
    print(res.status, res.read().decode())

HTTP clients that send their own User-Agent, such as requests and httpx, are not affected. Neither are the official SDKs: sogni-client on PyPI and @sogni-ai/sogni-client on npm. If a request with an explicit User-Agent returns 401, it reached the API, and the key or account is the problem. Check that the Authorization header carries a current key from dashboard.sogni.ai/api-key.

#Rate limits

When a request is rate-limited, the API returns 429 Too Many Requests. Honor the Retry-After header when present. Otherwise, retry with exponential backoff and jitter. Reduce concurrency instead of immediately repeating failed requests.

Default limits for workflows, render concurrency, and SDK connections, and how to design around them, are in Production Integrations.

#Idempotency

Write endpoints that can produce side effects accept an idempotency key. Reusing the same key for the same caller returns the original result instead of starting a duplicate run. Use it to make retries safe across network failures and double-clicks.

#Headers

Idempotency-Key: 7c9e6f7c-23a1-4f06-9d33-2dd5d6c8f5fb

X-Idempotency-Key is accepted as an alias.

#Supported endpoints

• POST /v1/chat/runs starts a durable chat run and also accepts idempotency_key in the body.
• POST /v1/chat/runs/:id/confirm-cost resolves a chat-run cost-approval pause and also accepts idempotency_key in the body.
• POST /v1/creative-agent/workflows starts a durable workflow (header only).
• POST /v1/creative-agent/workflows/:id/confirm-cost resolves a workflow cost-approval pause and also accepts idempotency_key in the body.
• POST /v1/creative-agent/workflows/:id/reseed starts a new take of a finished workflow (header only). A reseed mints new seeds, so without a key a retry starts a second take.

#Billing and tokens

Spend is denominated in two token types. Pick one explicitly with token_type on a request, or let the API choose.

#Selecting a token

Accepted values are auto (default), sogni, and spark. When tokens are billed, auto pays with Spark first and falls back to SOGNI.

{ "token_type": "auto" }

/v1/chat/completions also accepts an X-Token-Type header (the body field wins); other endpoints read token_type from the body only. Vendor-model jobs are normalized to spark automatically, regardless of preference.

#Plan or tokens

token_type only picks which token pays. Whether an active Unlimited plan or your token balance pays is a separate field, billing_mode, accepted by chat completions, tool execution, chat runs, and workflows (start, resume, and reseed).

With an active plan, changing token_type between spark and auto does not move a job off the plan. To spend Premium Spark you hold, which gets fastest-priority queue access ahead of plan-covered jobs, send billing_mode: "tokens". Vendor models are never plan-covered and always bill Premium Spark. A request that asks to pay in SOGNI (token_type: "sogni") is not plan-covered either.

{ "token_type": "spark", "billing_mode": "tokens" }

#Vendor model gating

Models from external vendors (OpenAI GPT Image 2 and GPT Image 2.5 Sunburst / Flare, ByteDance Seedance 2.0 / Mini, Seedance 2.5, Seedance 2.5 Uncensored, Seedance 2.0 Mini Uncensored, Seedream 5.0 Pro Uncensored, Alibaba HappyHorse 1.1, Wan 3, and Wan 3 Uncensored) bill Premium Spark. Hosted chat may choose a GPT Image model for storyboard or character-sheet work; if the account is not eligible for Premium Spark, chat uses a Sogni-hosted model instead. Workflows never substitute: a workflow that names a vendor model returns 402 with details.vendorModels before any step runs, including a confirm_cost: false estimate.

#Cost approval

• Creative workflows use a two-step confirmation. Submit with confirm_cost: false to get a 400 whose details.estimatedCapacity holds the estimate, then resubmit with confirm_cost: true. max_estimated_capacity_units is a hard cap: plans over it are rejected with 400 before anything is saved. Template runs (workflow_id) always return 202 with a preview and wait for POST /v1/creative-agent/workflows/:id/confirm-cost.
• Chat runs opt in with runtime_config.requireJobConfirmation: true. When the model calls a paid media tool, the run pauses in waiting_for_user with reason cost_approval_required, holds every paid call from that round, and emits run_awaiting_cost_confirmation for each held call. Resume or decline with POST /v1/chat/runs/:id/confirm-cost, echoing waiting.details.costApprovalPreview. confirm_cost and max_estimated_capacity_units are recorded on chat runs but not enforced.