Source: https://docs.sogni.ai/sogni-intelligence/openai-sdk-compatibility/

# 🔌OpenAI SDK Compatibility

Sogni Intelligence's [`/v1/chat/completions`](https://docs.sogni.ai/sogni-intelligence/chat-completions/) endpoint speaks the OpenAI Chat Completions wire protocol. Any OpenAI-compatible SDK or client works as a drop-in by overriding the **base URL** and **API key** — no changes to message shape, streaming, tool calling, or vision input.

```
Base URL: https://api.sogni.ai/v1
Auth:     Bearer <YOUR_SOGNI_API_KEY>
```

Get your API key at [dashboard.sogni.ai/api-key](https://dashboard.sogni.ai/api-key). External-vendor models (GPT Image 2 and 2.5, [Seedance 2.0](https://www.sogni.ai/models/seedance-2-0), [Seedance 2.5](https://www.sogni.ai/models/seedance-2-5), Fast / Mini, and [HappyHorse 1.1](https://www.sogni.ai/models/happyhorse-1-1)) need a positive **Premium Spark** balance — see [Billing & Cost Control](https://docs.sogni.ai/sogni-intelligence/billing-and-cost-control/).

* * *

## [#](https://docs.sogni.ai/sogni-intelligence/openai-sdk-compatibility/#typescript-javascript-openai-package)TypeScript / JavaScript (`openai` package)

```
npm install openai
```

```
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.SOGNI_API_KEY,
  baseURL: "https://api.sogni.ai/v1",
});

const completion = await client.chat.completions.create({
  model: "qwen3.6-35b-a3b-gguf-iq4xs",
  messages: [{ role: "user", content: "Hello — what can you help me build?" }],
});

console.log(completion.choices[0].message.content);
```

That's the whole change. Streaming, tool calling, vision parts, and the OpenAI response shape work as you'd expect.

* * *

## [#](https://docs.sogni.ai/sogni-intelligence/openai-sdk-compatibility/#python-openai-package)Python (`openai` package)

```
pip install openai
```

```
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SOGNI_API_KEY"],
    base_url="https://api.sogni.ai/v1",
)

completion = client.chat.completions.create(
    model="qwen3.6-35b-a3b-gguf-iq4xs",
    messages=[{"role": "user", "content": "Hello!"}],
)

print(completion.choices[0].message.content)
```

* * *

## [#](https://docs.sogni.ai/sogni-intelligence/openai-sdk-compatibility/#curl)curl

```
curl https://api.sogni.ai/v1/chat/completions \
  -H "Authorization: Bearer $SOGNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.6-35b-a3b-gguf-iq4xs",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

* * *

## [#](https://docs.sogni.ai/sogni-intelligence/openai-sdk-compatibility/#model-selection)Model selection

`GET /v1/models` returns the live model catalog. If you omit `model`, requests default to `qwen3.6-35b-a3b-gguf-iq4xs`.

```
const models = await client.models.list();
for (const m of models.data) console.log(m.id);
```

See [Introduction → Current Model IDs](https://docs.sogni.ai/sogni-intelligence/introduction/#current-model-ids) for the current public list.

* * *

## [#](https://docs.sogni.ai/sogni-intelligence/openai-sdk-compatibility/#sogni-specific-extras)Sogni-specific extras

The OpenAI SDK sends unknown body fields through unchanged via `extra_body` (Python) or by passing the field at the top level (TS — the type may need a cast). Useful Sogni-only fields:

| Field | Use |
| --- | --- |
| `sogni_tools` | `true` / `"creative-tools"` (default) injects Sogni media tools; `"creative-agent"` adds workflow planners; `false` / `"none"` disables Sogni tool injection. |
| `sogni_tool_execution` | Defaults to `true` with API-key auth — the API executes the tool server-side and returns assistant text + media links. Set `false` to receive raw `tool_calls` for your own loop. |
| `media_references` | Request-level media (HTTPS URLs or inline `data:` URIs) seeded into the tool execution context. |
| `task_profile` | `general` / `coding` / `reasoning`. Defaults to `coding` when a `developer` message is present. |
| `chat_template_kwargs` | Backend flags. Set `{"enable_thinking": false}` to turn off the Qwen `<think>` preamble (recommended with `response_format` or a tight `max_tokens`); thinking is on by default but caller-controllable. |
| `token_type` | `spark` / `sogni` / `auto` — see [Billing & Cost Control](https://docs.sogni.ai/sogni-intelligence/billing-and-cost-control/). |
| `response_format` | OpenAI-compatible structured outputs — `{"type":"json_object"}` or `{"type":"json_schema", ...}`. Honored natively by the worker. Pair with `chat_template_kwargs: {"enable_thinking": false}`. |
| `app_source` | Optional client/source label (≤128 chars) for attribution; also settable via the `X-App-Source` header. |

```
// TypeScript — pass extras at the top level, cast if your version of the SDK types rejects them
const completion = await client.chat.completions.create({
  model: "qwen3.6-35b-a3b-gguf-iq4xs",
  messages: [{ role: "user", content: "Create a cinematic image of a neon Tokyo alley in the rain." }],
  // @ts-expect-error — Sogni-only extras
  sogni_tools: "creative-tools",
  token_type: "spark",
});
```

```
# Python — use extra_body
completion = client.chat.completions.create(
    model="qwen3.6-35b-a3b-gguf-iq4xs",
    messages=[{"role": "user", "content": "Create a cinematic image of a neon Tokyo alley in the rain."}],
    extra_body={
        "sogni_tools": "creative-tools",
        "token_type": "spark",
    },
)
```

* * *

## [#](https://docs.sogni.ai/sogni-intelligence/openai-sdk-compatibility/#what-carries-over-from-openai)What carries over from OpenAI

-   Streaming (`stream: true`) — Server-Sent Events ending with `[DONE]`.
-   Tool calling — `tools[]`, `tool_choice`, `finish_reason: "tool_calls"`, `role: "tool"` messages.
-   Vision input — inline base64 PNG/JPEG `data:` URIs on `image_url.url`.
-   `system`, `developer`, `user`, `assistant`, `tool` roles.
-   Sampling fields: `max_tokens`, `temperature`, `top_p`, `frequency_penalty`, `presence_penalty`, `stop`.
-   Standard error envelope: `{ "error": { "message", "type", "code" } }`.
-   Response shape: `id`, `object`, `created`, `model`, `choices`, `usage`.

* * *

## [#](https://docs.sogni.ai/sogni-intelligence/openai-sdk-compatibility/#whats-sogni-specific-to-know)What's Sogni-specific to know

1.  **Media tools execute server-side by default.** With API-key auth, the LLM-selected Sogni tool runs on the API and returns the final assistant message with generated media URLs. Set `sogni_tool_execution: false` if you want raw `tool_calls` to drive your own loop. See [Chat Completions → Tool Execution Modes](https://docs.sogni.ai/sogni-intelligence/chat-completions/#tool-execution-modes).
2.  **Vendor models must be named explicitly.** GPT Image 2/2.5, Seedance 2.0/2.5 / Fast / Mini, and HappyHorse 1.1 require Spark and are never selected by the router on your behalf — your request has to pass the model id. See [Billing & Cost Control](https://docs.sogni.ai/sogni-intelligence/billing-and-cost-control/#vendor-model-gating).
3.  **Durable runs use a different endpoint.** If you need persisted progress, replayable events, or recovery across disconnects, switch from `/v1/chat/completions` to [`/v1/chat/runs`](https://docs.sogni.ai/sogni-intelligence/durable-chat-runs/). The OpenAI SDK only speaks the synchronous endpoint.
4.  **`Authorization` header on streams from browsers.** `EventSource` cannot set headers; use `fetch` + `ReadableStream` (or any HTTP client that supports headers) when streaming from a browser.

* * *

## [#](https://docs.sogni.ai/sogni-intelligence/openai-sdk-compatibility/#already-integrated-clients)Already-integrated clients

If you'd rather configure an existing tool than write code, see the dedicated guides:

[🌎Open WebUI Integration— self-hosted chat UI with OpenAI-compatible provider support.](https://docs.sogni.ai/sogni-intelligence/integration-open-webui/)[⚡OpenClaw Integration— coding-agent gateway.](https://docs.sogni.ai/sogni-intelligence/integration-openclaw/)[🪽Hermes Agent Integration— Nous Research agent runtime.](https://docs.sogni.ai/sogni-intelligence/integration-hermes-agent/)

For agent runtimes (Claude Code, OpenClaw, Manus, etc.) that want a higher-level wrapper, install the [Sogni Creative Agent Skill](https://docs.sogni.ai/sogni-intelligence/creative-agent-skill/).