💬Chat Completions

POST /v1/chat/completions is Sogni Intelligence's OpenAI-compatible chat endpoint. Use it for text chat, streaming, vision input, custom function tools, and model-selected Sogni media generation.

curl https://api.sogni.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.6-35b-a3b-gguf-iq4xs",
    "messages": [
      {"role": "user", "content": "Create a cinematic image of a neon alley in Tokyo during rain."}
    ]
  }'

#Request Fields

Field	Type	Notes
`messages`	array	Required. Supports `system`, `developer`, `user`, `assistant`, and `tool` roles.
`model`	string	Optional. Defaults to `qwen3.6-35b-a3b-gguf-iq4xs`. Use `/v1/models` for the live list.
`stream`	boolean	Optional. Streams response chunks as Server-Sent Events.
`max_tokens`, `temperature`, `top_p`, `top_k`, `min_p`, `repetition_penalty`, `frequency_penalty`, `presence_penalty`, `stop`	mixed	Standard sampling/runtime controls. Values are clamped to the selected model tier.
`tools`	array	Optional custom OpenAI-style function tools. Custom tools are merged with Sogni tools unless `sogni_tools` is `false`.
`tool_choice`	string or object	Optional. Defaults to `auto` when Sogni tools are injected. Can force a function by name.
`sogni_tools`	boolean or string	`true` injects the default hosted tools. `"creative-agent"` or `"rich"` injects the richer creative-agent family. `false` disables Sogni tool injection.
`sogni_tool_execution`	boolean	With API-key auth, defaults to `true`. Set `false` to receive raw `tool_calls`.
`task_profile`	string	Optional hint: `general`, `coding`, or `reasoning`. Developer messages default to `coding` when no profile is set.
`chat_template_kwargs`	object	Optional backend flags such as `{"enable_thinking": true}`.
`token_type`	string	Optional billing preference: `spark`, `sogni`, or `auto`. Can also be sent as `X-Token-Type`; the body field wins.

#Vision Input

Vision input uses OpenAI-style content parts on user messages:

[
  { "type": "text", "text": "What is in this image?" },
  { "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,...", "detail": "auto" } }
]

Vision image_url.url values must be inline PNG or JPEG data: URIs. A request can include up to 20 vision images, each up to 10 MB, with longest side up to 1024 px.

#Tool Execution Modes

Mode	Request	Result
Automatic execution	API-key auth, default `sogni_tool_execution`	The model chooses a Sogni tool, the API executes it, follow-up LLM rounds run automatically, and the final response returns assistant content with generated media links.
Manual tool loop	`sogni_tool_execution: false`	The response can finish with `finish_reason: "tool_calls"` and OpenAI-style `message.tool_calls`. Your app executes the tools and sends the results back as `role: "tool"` messages.
Text only	`sogni_tools: false`	No Sogni tools are injected. Use this for plain chat or when you want to provide only your own custom tools.
Rich creative agent	`sogni_tools: "creative-agent"` or `"rich"`	The default hosted tools are replaced by the richer creative-agent family used by Sogni Chat.

When API-key authenticated server-side Sogni tool execution runs, /v1/chat/completions creates a durable hosted_tool_sequence workflow record. Non-streaming responses can include a creative_workflows reference with URLs for the workflow snapshot, event log, and SSE stream.

#Default Hosted Tools

Unless sogni_tools is disabled or switched to rich mode, POST /v1/chat/completions injects these six hosted Sogni tools:

Tool	Use when the user asks to...
`sogni_generate_image`	Generate a new image from text.
`sogni_edit_image`	Edit an image, preserve likeness, combine references, or guide generation with one or more source images.
`sogni_generate_video`	Generate text-to-video or image-to-video clips.
`sogni_sound_to_video`	Generate audio-synchronized video, music videos, lip-sync style clips, or audio-reactive visuals.
`sogni_video_to_video`	Restyle, enhance, transform, or motion-transfer an existing video.
`sogni_generate_music`	Generate instrumentals, songs, beats, ambience, jingles, or lyric-based music.

Manual-mode tool-call responses follow the OpenAI function-calling shape:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "",
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "sogni_generate_image",
              "arguments": "{\"prompt\":\"A square product render of translucent headphones on a white background\",\"width\":1024,\"height\":1024}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

#Rich Creative-Agent Tools

Set sogni_tools to "creative-agent" or "rich" when you want the broader tool family used by Sogni Chat.

Tool	Use
`generate_image`	Text-only image generation.
`edit_image`	Reference-guided image generation or editing with 1-6 source images.
`restore_photo`	Restore or transform an original uploaded photo.
`apply_style`	Apply an artistic style, era, or creative visual treatment to an image.
`refine_result`	Modify or build on an existing generated result.
`change_angle`	Create a new camera angle or perspective of an image subject.
`generate_video`	Text-to-video without a source image.
`animate_photo`	Animate a still image into video.
`sound_to_video`	Generate video synchronized to uploaded or previously generated audio.
`video_to_video`	Transform an uploaded or generated source video.
`generate_music`	Generate music or songs from text.
`stitch_video`	Combine previously generated videos into one MP4, optionally with audio.
`orbit_video`	Create a 360-degree orbit/turntable video around a subject.
`dance_montage`	Create dance videos from a photo using choreography reference workflows.

Rich tools track generated images, videos, and audio across tool rounds. Tool results include indices so later tools can target earlier results without copying media URLs back into the prompt.

#Media Input Rules

For /v1/chat/completions, media-bearing tool arguments such as source_image_url, reference_image_url, reference_audio_url, and reference_video_url must be inline base64 data: URIs. This keeps chat tool calling OpenAI-compatible and prevents arbitrary remote fetches from model-generated arguments.

Use Creative-Agent Workflows when you want exact backend execution using Sogni artifact URLs, including presigned HTTPS download URLs returned by Sogni upload endpoints.

#Choosing Chat Completions

Use /v1/chat/completions when:

You need OpenAI-compatible chat or streaming.
An LLM should decide which media tool to call.
You want custom function tools alongside Sogni tools.
You want raw OpenAI-style tool_calls for your own tool runner.
You are integrating with OpenAI-compatible clients such as Open WebUI, OpenClaw, Hermes Agent, or OpenAI SDKs.

Use Creative-Agent Workflows instead when your app already knows the exact media steps or needs workflow event replay, SSE progress, or cancellation.