Chat Completions | Sogni: Learn

OpenAI-compatible chat with optional server-side Sogni creative tools. Any client that speaks the OpenAI chat shape works as-is. Supports streaming over SSE, vision input as inline data URIs, custom function tools, and the Sogni tool families.

#Create a chat completion

POST /v1/chat/completions Auth required

Returns a single JSON response, or a stream of OpenAI-style SSE events when stream: true.

#Body

Name	Type	In	Description
messagesrequired	array	body	Non-empty OpenAI-style message array. The `developer` role is normalized to `system`. User messages may carry mixed `text` and `image_url` parts for vision.
model	string	body	LLM model id from `GET /v1/models`. Defaults to `qwen3.6-35b-a3b-gguf-iq4xs`. An unknown id returns `404` with `code: "model_not_found"`. Media models such as `gpt-image-2` are not valid here; name them in the prompt or in tool arguments.
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"` or `true` (default) covers media generation, editing, analysis, and composition. `"creative-agent"` adds workflow planners and asset-manifest tools. `false` or `"none"` is text-only. Unrecognized values are treated as `"creative-tools"`.
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. Media tools run server-side only with API-key auth; with a session token, only the synchronous composition tools run (non-streaming) and other tool calls are returned raw.
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). The `X-Token-Type` header is accepted; the body wins. Unrecognized values fall back to `auto`.
billing_mode	string	body	`auto` (default), `subscription`, or `tokens`. `subscription` bills eligible work against an active Unlimited plan; a request the plan can't cover fails with `code: "subscription_limit"`. Other values return `400`.
safe_content_filter	boolean	body	Sensitive Content Filter for the media tools this request runs. Defaults to `true`. `false` requires an eligible account and is checked again when each job renders; some models keep their own content policy. See Sensitive Content Filter.
media_references	array	body	Optional uploaded or request media metadata available to hosted creative tools.
chat_template_kwargs	object	body	Forwarded to the worker. An explicit `enable_thinking` boolean wins; otherwise thinking is on, and `reasoning_effort: "minimal"` turns it off. `<think>` blocks are removed from returned content.
reasoning_effort	string	body	Optional reasoning hint: `minimal`, `low`, `medium`, or `high`. Also accepts `reasoning.effort`.
response_format	object	body	OpenAI structured-output or JSON-mode hint. Forwarded.
app_source	string	body	Optional caller label. Values longer than 128 characters are truncated. The `X-App-Source` header is accepted; the body wins.

Vision limits. Up to 20 images per request, on user messages only; each image at most 10 MB and 1024 px on its longest side; PNG or JPEG only, as an inline base64 data: URI whose declared type matches the image data. Remote image URLs return 400.

#Tool families

Value	What's injected
"creative-tools"	Default. Image, video, speech, and music generation and editing; video upscaling, background removal, object selection, and image-to-3D (see Media Utilities, 3D and Speech); media analysis; plus the synchronous composition tools `enhance_prompt`, `compose_script`, `compose_lyrics`, and `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`.

#Request

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

{
  "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 (including speech), and [⬇ Generated 3D model](url) for 3D models. Set sogni_tool_execution: false to receive raw tool_calls and run the loop yourself.

Streaming. Set stream: true and consume OpenAI-compatible text/event-stream chunks until data: [DONE]. With API-key auth and server-side tool execution (the default), assistant text can arrive in larger chunks rather than token by token. When a Sogni tool runs, the stream adds a progress delta, a media Markdown chunk, and chunks carrying a top-level creative_workflows reference. Lines starting with : are keepalive comments. An error after the stream opens arrives as a data: {"error": {…}} chunk before [DONE]. For token-by-token output with your own tool loop, set sogni_tool_execution: false.

Differences from a plain OpenAI model. Unless you set sogni_tools: false or send your own non-empty system message, Sogni adds its creative-assistant system prompt. Server-side tool execution runs up to 5 model rounds per request. When tools run, the response includes a creative_workflows reference to the persisted media jobs. Send Sogni fields in snake_case; camelCase forms such as tokenType or mediaReferences return 400.