Getting Started

Use the API portal for developer access. Sawalni.com is the consumer search product.

1. Create your API account

Create an API account with Omneity ID. The sign-in flow returns to this portal. If you already have an account, sign in.

2. Check available access

Open Models. Models marked Request access need approval. Speech access does not imply chat access. Sawalni, Sawalni Mini, and Tarjamli share the Sawalni model access grant. Madmon has its own grant. Pending requests are not approvals. Keep using available APIs while a request is reviewed.

3. Create an API key

Open API Keys and select Create New Key. Copy the key when it is shown. A key cannot grant model access that your account does not have. Check its scopes too.

4. Run a first example

This language-identification example does not require the restricted chat-model grant. It still requires a valid key and available credit. Replace YOUR_API_KEY with your server-side key.

bash

curl https://api.sawalni.com/v1/language/identify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gherbal-v4","input":"Bonjour tout le monde"}'

A successful request returns HTTP 200 with language predictions. Then try the language playground, or use the example for a model enabled on your account. Chat examples require chat access first.

If a request fails

401: check the key and Authorization header. Sign in again if the portal session expired.
403: read the response detail. Check account model approval and key scopes on Models and API Keys. Creating another key does not bypass a missing model grant.
402: check the available balance on Billing.
429: respect Retry-After and try again after the stated delay.

If access is approved but the same request still returns 403, contact [email protected] with the model, endpoint, time, and request ID when supplied. Never send your API key.

Available Models

Model	Type	Context Window	Description
`sawalni-beta`	Chat	24,000 tokens	Flagship Arabic-first chat model
`sawalni-mini-beta`	Chat	262,144 tokens	Efficient long-context chat model
`tarjamli-nano-v3`	Translation	8,192 tokens	Darija in Arabic or Latin script to English, French, or Modern Standard Arabic
`tarjamli-mini-v4`	Translation	131,072 tokens	Multilingual translation with optional instructions, glossaries and examples
`madmon-beta`	Embeddings	8,000 tokens	High-quality text embeddings
`gherbal-v4`	Language ID	—	Latest FastText language identification
`rescript-v1`	Transliteration	—	Writing-system transliteration with Sawtoken v3 and Sawtone reranking
`sawtone-v4`	Word Encoder	—	Multichannel word encoder with 544d composite embeddings
`sawalni-atlas-gps`	Geographic API	—	Moroccan cross-script place search and real routing powered by Sawtone v4
`ziryab-v1`	Rhymes & Lyrics	—	Rhyme scoring and lyric analysis built on Sawtone
`daktilo`	Transcription	—	Speech transcription powered by Daktilo v3
`asat`	Speech Synthesis	—	ASAT Speaks Any Text text-to-speech

Base URL

All API requests use the following base URL:

text

https://api.sawalni.com/v1

Chat completions and embeddings are OpenAI-compatible. Specialized language, speech, alignment, lyrics, and Atlas operations use their documented REST endpoints under the same base URL and bearer key.

Using the OpenAI SDK

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": "user", "content": "مرحبا! كيف حالك؟"}]
)

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

4. Run a first example

This language-identification example does not require the restricted chat-model grant. It still requires a valid key and available credit. Replace YOUR_API_KEY with your server-side key.

bash

curl https://api.sawalni.com/v1/language/identify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gherbal-v4","input":"Bonjour tout le monde"}'

A successful request returns HTTP 200 with language predictions. Then try the language playground, or use the example for a model enabled on your account. Chat examples require chat access first.

If a request fails

401: check the key and Authorization header. Sign in again if the portal session expired.

403: read the response detail. Check account model approval and key scopes on Models and API Keys. Creating another key does not bypass a missing model grant.

402: check the available balance on Billing.

429: respect Retry-After and try again after the stated delay.

If access is approved but the same request still returns 403, contact [email protected] with the model, endpoint, time, and request ID when supplied. Never send your API key.

Available Models

Model	Type	Context Window	Description
`sawalni-beta`	Chat	24,000 tokens	Flagship Arabic-first chat model
`sawalni-mini-beta`	Chat	262,144 tokens	Efficient long-context chat model
`tarjamli-nano-v3`	Translation	8,192 tokens	Darija in Arabic or Latin script to English, French, or Modern Standard Arabic
`tarjamli-mini-v4`	Translation	131,072 tokens	Multilingual translation with optional instructions, glossaries and examples
`madmon-beta`	Embeddings	8,000 tokens	High-quality text embeddings
`gherbal-v4`	Language ID	—	Latest FastText language identification
`rescript-v1`	Transliteration	—	Writing-system transliteration with Sawtoken v3 and Sawtone reranking
`sawtone-v4`	Word Encoder	—	Multichannel word encoder with 544d composite embeddings
`sawalni-atlas-gps`	Geographic API	—	Moroccan cross-script place search and real routing powered by Sawtone v4
`ziryab-v1`	Rhymes & Lyrics	—	Rhyme scoring and lyric analysis built on Sawtone
`daktilo`	Transcription	—	Speech transcription powered by Daktilo v3
`asat`	Speech Synthesis	—	ASAT Speaks Any Text text-to-speech

Using the OpenAI SDK

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": "user", "content": "مرحبا! كيف حالك؟"}]
)

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