Chat Completions API

Generate conversational responses using Sawalni's chat models.

Endpoint

text

POST https://api.sawalni.com/v1/chat/completions

Request Body

Parameter	Type	Required	Description
`model`	string	Yes	`sawalni-beta` or `sawalni-mini`
`messages`	array	Yes	Array of message objects
`temperature`	number	No	Sampling temperature 0–2. Default: 1
`max_tokens`	number	No	Maximum tokens to generate
`stream`	boolean	No	Enable SSE streaming. Default: false
`modalities`	array	No	Output modes. Use `["text", "audio"]` for synchronized text and voice
`audio`	object	With audio	Voice output settings: `voice` and `format`
`tools`	array	No	Function calling tool definitions
`tool_choice`	string	No	`auto`, `none`, or specific tool
`response_format`	object	No	`{"type": "json_object"}` for JSON mode

Message Format

json

{
  "role": "system" | "user" | "assistant",
  "content": "message text"
}

Example — JavaScript

javascript

const response = await fetch('https://api.sawalni.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'sawalni-beta',
    messages: [
      { role: 'system', content: 'You are a helpful assistant.' },
      { role: 'user', content: 'ما هي عاصمة المغرب؟' }
    ],
    temperature: 0.7,
    max_tokens: 150
  })
});

const data = await response.json();
console.log(data.choices[0].message.content);

Example — Python

python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.sawalni.com/v1"
)

response = client.chat.completions.create(
    model="sawalni-beta",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "ما هي عاصمة المغرب؟"}
    ],
    temperature=0.7,
    max_tokens=150
)

print(response.choices[0].message.content)

Image input

Send an image as an image_url content part. This example reads a local PNG and sends it as a base64 data URL. Use image/jpeg for a JPEG file.

python

import base64
from pathlib import Path
from openai import OpenAI

image = base64.b64encode(Path("photo.png").read_bytes()).decode("ascii")
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.sawalni.com/v1")
response = client.chat.completions.create(
    model="sawalni-beta",
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "Describe this image in Arabic."},
        {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{image}"}},
    ]}],
)
print(response.choices[0].message.content)

Audio input

Send a WAV recording as an input_audio content part. This example asks the chat model to answer a spoken question. For a transcript only, use the Speech Transcription API.

python

import base64
from pathlib import Path
from openai import OpenAI

audio = base64.b64encode(Path("question.wav").read_bytes()).decode("ascii")
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.sawalni.com/v1")
response = client.chat.completions.create(
    model="sawalni-beta",
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "Answer the question in this recording."},
        {"type": "input_audio", "input_audio": {"data": audio, "format": "wav"}},
    ]}],
)
print(response.choices[0].message.content)

Voice responses

Sawalni follows the OpenAI chat audio shape. Add audio to modalities. Then set a provisioned voice and output format. ASAT v2 accepts pcm16 and wav. Use pcm16 for low-latency streaming.

json

{
  "model": "sawalni-beta",
  "messages": [{"role": "user", "content": "شرح ليا هاد الفكرة باختصار."}],
  "modalities": ["text", "audio"],
  "audio": {"voice": "male-1", "format": "pcm16"},
  "stream": true
}

The stream keeps one speech session for the full assistant reply. Text and audio arrive in normal chat-completion chunks. Audio bytes are base64-encoded in choices[0].delta.audio.data. The last audio delta includes the complete assistant transcript and spoken_text.

spoken_text is the text used for speech generation after numbers and symbols are expanded and silent punctuation is removed. Use this value, not the visual transcript, with the Word Alignment API when you need playback-synchronized word highlighting. For example, a transcript of 25 × 4 = 100 can have a spoken form such as خمسة وعشرين مضروبة ف ربعة كتساوي مية.

json

{
  "choices": [{
    "index": 0,
    "delta": {
      "audio": {
        "transcript": "25 × 4 = 100",
        "spoken_text": "خمسة وعشرين مضروبة ف ربعة كتساوي مية"
      }
    },
    "finish_reason": "stop"
  }]
}

For a non-streaming request, choices[0].message.audio contains id, data, expires_at, and transcript. If you request only ["audio"], the message content is null.

Response

json

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1709000000,
  "model": "sawalni-beta",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "عاصمة المغرب هي الرباط."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 12,
    "total_tokens": 37
  }
}

Models

Model	Context	Best For
`sawalni-beta`	24K tokens	High-quality reasoning, Arabic-first
`sawalni-mini`	262K tokens	Native long context and efficient responses

Chat Completions API

Generate conversational responses using Sawalni's chat models.

Endpoint

text

POST https://api.sawalni.com/v1/chat/completions

Request Body

Parameter	Type	Required	Description
`model`	string	Yes	`sawalni-beta` or `sawalni-mini`
`messages`	array	Yes	Array of message objects
`temperature`	number	No	Sampling temperature 0–2. Default: 1
`max_tokens`	number	No	Maximum tokens to generate
`stream`	boolean	No	Enable SSE streaming. Default: false
`modalities`	array	No	Output modes. Use `["text", "audio"]` for synchronized text and voice
`audio`	object	With audio	Voice output settings: `voice` and `format`
`tools`	array	No	Function calling tool definitions
`tool_choice`	string	No	`auto`, `none`, or specific tool
`response_format`	object	No	`{"type": "json_object"}` for JSON mode

Message Format

json

{
  "role": "system" | "user" | "assistant",
  "content": "message text"
}

Example — JavaScript

javascript

const response = await fetch('https://api.sawalni.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'sawalni-beta',
    messages: [
      { role: 'system', content: 'You are a helpful assistant.' },
      { role: 'user', content: 'ما هي عاصمة المغرب؟' }
    ],
    temperature: 0.7,
    max_tokens: 150
  })
});

const data = await response.json();
console.log(data.choices[0].message.content);

Example — Python

python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.sawalni.com/v1"
)

response = client.chat.completions.create(
    model="sawalni-beta",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "ما هي عاصمة المغرب؟"}
    ],
    temperature=0.7,
    max_tokens=150
)

print(response.choices[0].message.content)

Image input

Send an image as an image_url content part. This example reads a local PNG and sends it as a base64 data URL. Use image/jpeg for a JPEG file.

python

import base64
from pathlib import Path
from openai import OpenAI

image = base64.b64encode(Path("photo.png").read_bytes()).decode("ascii")
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.sawalni.com/v1")
response = client.chat.completions.create(
    model="sawalni-beta",
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "Describe this image in Arabic."},
        {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{image}"}},
    ]}],
)
print(response.choices[0].message.content)

Audio input

Send a WAV recording as an input_audio content part. This example asks the chat model to answer a spoken question. For a transcript only, use the Speech Transcription API.

python

import base64
from pathlib import Path
from openai import OpenAI

audio = base64.b64encode(Path("question.wav").read_bytes()).decode("ascii")
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.sawalni.com/v1")
response = client.chat.completions.create(
    model="sawalni-beta",
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "Answer the question in this recording."},
        {"type": "input_audio", "input_audio": {"data": audio, "format": "wav"}},
    ]}],
)
print(response.choices[0].message.content)

Voice responses

Sawalni follows the OpenAI chat audio shape. Add audio to modalities. Then set a provisioned voice and output format. ASAT v2 accepts pcm16 and wav. Use pcm16 for low-latency streaming.

json

{
  "model": "sawalni-beta",
  "messages": [{"role": "user", "content": "شرح ليا هاد الفكرة باختصار."}],
  "modalities": ["text", "audio"],
  "audio": {"voice": "male-1", "format": "pcm16"},
  "stream": true
}

json

{
  "choices": [{
    "index": 0,
    "delta": {
      "audio": {
        "transcript": "25 × 4 = 100",
        "spoken_text": "خمسة وعشرين مضروبة ف ربعة كتساوي مية"
      }
    },
    "finish_reason": "stop"
  }]
}

For a non-streaming request, choices[0].message.audio contains id, data, expires_at, and transcript. If you request only ["audio"], the message content is null.

Response

json

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1709000000,
  "model": "sawalni-beta",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "عاصمة المغرب هي الرباط."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 12,
    "total_tokens": 37
  }
}

Models

Model	Context	Best For
`sawalni-beta`	24K tokens	High-quality reasoning, Arabic-first
`sawalni-mini`	262K tokens	Native long context and efficient responses