Getting Started

#Introduction

The Sogni API exposes the Sogni Intelligence platform — an OpenAI-compatible LLM endpoint, direct synchronous creative tools, a durable agent runtime, and a creative-workflow engine — over a single REST surface at https://api.sogni.ai. The reference also covers project status, account balances, worker analytics, and model discovery. Hosted chat and workflows support streaming; project status and analytics use ordinary HTTP reads. Check each endpoint's access rules.

#Surfaces at a glance

• Chat Completions — OpenAI-compatible chat with optional server-side Sogni tool execution (image, video, music generation, plus composition planners).
• Direct Tool Execution — synchronous prompt, script, lyrics, and workflow-planning tools when your application already has exact JSON arguments.
• Chat Runs — durable counterpart to chat completions: persisted state, replayable SSE events, cancel and resume, cost-approval pauses.
• Creative Workflows — pre-planned multi-step jobs (storyboards, image→video, batch generation) with an in-band dependency graph and durable execution.
• Workflow Templates — saveable, parameterized recipes. Invoke by ID with inputs to compile a fresh durable workflow run.
• Media + Image URLs — presigned S3-style POST URLs for uploading reference assets and downloading generated artifacts.
• Wallet + Replay — on-chain balance lookups and the RunRecord ingest/read surface for replay tooling.

#Quick start

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

The legacy api-key header is also accepted as a fallback, but new integrations should use Authorization: Bearer.

#Versioning

Each endpoint has its own versioned path. Many 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 entire integration.

#Errors

The Sogni 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": "Durable workflow requires at least one step"
}

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

#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 this to make retries safe across network failures and double-clicks.

#Headers (preferred)

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

#Supported endpoints

• POST /v1/chat/runs — start a durable chat run (also accepts idempotency_key in the body)
• POST /v1/chat/runs/:id/confirm-cost — resume a cost-approval pause
• POST /v1/creative-agent/workflows — start a durable workflow

#Billing & tokens

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

#Selecting a token

{
  "token_type": "auto"   // "auto" (default) | "sogni" | "spark"
}

The X-Token-Type header is also accepted; the body field wins when both are present. Vendor-model jobs are normalized to spark automatically, regardless of preference.

#Vendor model gating

Models from external vendors (OpenAI GPT Image 2, ByteDance Seedance 2.0 / Fast / Mini, Alibaba HappyHorse 1.1) require an explicit opt-in by name ("model": "gpt-image-2", "videoModel": "seedance2", "videoModel": "happyhorse-1.1-t2v"). The LLM router will never pick them on the caller's behalf. Workflows that bind a vendor model in a step return 402 immediately if the calling account is not eligible for Premium Spark, so no upstream steps run before the gate.

#Cost approval

• Creative workflows use a two-step confirmation: submit with confirm_cost: false to receive a 400 carrying the structured estimatedCapacity, then resubmit with confirm_cost: true to proceed. Use max_estimated_capacity_units as a hard cap — submissions over budget are rejected before persistence regardless of confirmation.
• Chat runs opt in via runtime_config.requireJobConfirmation: true. Each paid media tool call then pauses the run in waiting_for_user with reason cost_approval_required and emits a run_awaiting_cost_confirmation SSE event; resume via POST /v1/chat/runs/:id/confirm-cost. The jobConfirmationThresholdUsd runtime-config field skips the pause when the estimate is below the threshold.