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 in the Sogni account 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 are long-lived UUIDs scoped to a wallet, intended for backend and SDK use. They are required for durable chat runs and creative workflow execution. Generate or rotate yours at dashboard.sogni.ai/api-key.
• Session tokens are short-lived browser JWTs issued by the Sogni auth flow. Most read endpoints accept either credential type.

The legacy api-key header is still accepted, but new integrations should use Authorization: Bearer.

#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. Some 429 bodies are a plain { "error": "Too Many Requests" }, and workflow template validation failures return { "status": "error", "data": { "validation": { "issues": [ … ] } } }. Branch on the HTTP status first.

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