Chat Completions

OpenAI-compatible chat with optional server-side Sogni creative tools. Drop-in for any client that speaks the OpenAI chat shape. Supports streaming via SSE, vision input (inline data URIs), custom function tools, and the Sogni tool families.

POST /v1/chat/completions Auth required

Create a chat completion. Drop-in OpenAI-compatible. Returns a single JSON response, or a stream of OpenAI-style SSE events when stream: true.

#Body

Name	Type	In	Description
messages*	array	body	Non-empty OpenAI-style message array. The `developer` role is normalized to `system`. User messages may carry mixed `text` + `image_url` parts (vision).
model	string	body	LLM model id. Defaults to `qwen3.6-35b-a3b-gguf-iq4xs`. Vendor models (e.g. `gpt-image-2`) require explicit naming and Premium Spark.
stream	boolean	body	When `true`, returns OpenAI-style SSE chunks.
max_tokens	integer	body	Maximum output tokens. `max_completion_tokens` is accepted as an OpenAI-SDK alias.
temperature	number	body	Sampling temperature. Forwarded to the LLM worker.
top_p	number	body	Nucleus sampling. Forwarded to the LLM worker.
tools	array	body	Standard OpenAI function-tool array. Merged with the auto-injected Sogni tool family unless `sogni_tools` is `"none"`.
tool_choice	string\|object	body	OpenAI tool-choice. Defaults to `"auto"` when Sogni tools are injected.
sogni_tools	string\|boolean	body	Sogni tool family. `"creative-tools"` (default) — image/video/music + composition. `"creative-agent"` — adds workflow planners and asset-manifest tools. `false` or `"none"` — text-only.
sogni_tool_execution	boolean	body	When `true` (default), the API executes Sogni tool calls server-side and returns the final assistant message with media URLs. Set `false` to receive raw `tool_calls` and run the loop yourself. Only takes effect with API-key auth.
task_profile	string	body	Optional task profile. `general`, `coding`, or `reasoning`. Defaults to `coding` when any message uses the `developer` role.
token_type	string	body	`spark`, `sogni`, or `auto` (default). `X-Token-Type` header accepted; body wins.
media_references	array	body	Optional uploaded/request media metadata available to hosted creative tools.
chat_template_kwargs	object	body	Forwarded to the worker. Thinking-mode controls and similar template kwargs go here. An explicit `enable_thinking` boolean wins; otherwise `reasoning_effort: "minimal"` disables thinking and all other efforts use the served model default.
reasoning_effort	string	body	Optional reasoning hint: `minimal`, `low`, `medium`, `high`. Also accepts `reasoning.effort`.
response_format	object	body	OpenAI structured-output / JSON-mode hint. Forwarded.
app_source	string	body	Optional caller label (max 128 chars). `X-App-Source` header accepted.

Vision limits. Up to 20 images per request; each image ≤ 10 MB and ≤ 1024 px on its longest side; PNG or JPEG only; must be an inline base64 data: URI.

#Tool families

Value	What's injected
"creative-tools"	Default. Image/video/music generation + editing + analysis, plus synchronous composition tools (`enhance_prompt`, `compose_script`, `compose_lyrics`, `compose_instrumental`).
"creative-agent"	Everything in `creative-tools` plus workflow control, asset-manifest tools, and the workflow planners `compose_workflow` and `compose_workflow_template`.
false / "none"	No Sogni tools injected. Text-only or your own custom `tools`.

$ 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."}
    ],
    "sogni_tools": "creative-tools"
  }'

import { SogniClient } from '@sogni-ai/sogni-client';

const sogni = await SogniClient.createInstance({
  appId: 'your-app',
  apiKey: process.env.SOGNI_API_KEY,
});

const result = await sogni.chat.hosted.create({
  messages: [
    { role: 'user', content: 'Generate a cinematic image of a neon alley in Tokyo during rain.' },
  ],
  sogni_tools: 'creative-tools',
});

console.log(result.choices[0].message);

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="qwen3.6-35b-a3b-gguf-iq4xs",
    messages=[
        {"role": "user", "content": "Generate a cinematic image of a neon alley in Tokyo during rain."},
    ],
    extra_body={"sogni_tools": "creative-tools"},
)

print(response.choices[0].message)

#Response (synchronous)

{
  "id": "chatcmpl-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "object": "chat.completion",
  "created": 1731950400,
  "model": "qwen3.6-35b-a3b-gguf-iq4xs",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Here's your image:\n\n![Generated image](https://…/image.png)"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 18,
    "total_tokens": 60,
    "prompt_tokens_details": { "cached_tokens": 0 }
  }
}

Media URLs. When the API executes Sogni tools server-side, generated media URLs are injected into the assistant message as Markdown — ![alt](url) for images, [▶ Generated video](url) for video, [▶ Generated music](url) for audio. Set sogni_tool_execution: false to receive raw tool_calls and run the loop yourself.

Streaming. Set stream: true and consume text/event-stream chunks. Each chunk is an OpenAI-compatible delta. Sogni tool progress is injected as content deltas in the same stream when sogni_tool_execution is enabled.