Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.1.0
# authorship: the provider published this document; retrieved unmodified into
# openapi/_original/ and re-serialised here with servers[], info.contact and
# info.termsOfService added. See x-provenance at the end of this file.
x-method: searched
x-source-url: https://api.fanar.qa/openapi.json
info:
title: Fanar API
description: |
You can interact with FanarAPI for seamless chat completion and text processing using Fanar.<br/><strong>Base URL:</strong> https://api.fanar.qa<br/><strong>Request API Access:</strong> <a href='https://api.fanar.qa/request'>https://api.fanar.qa/request</a><h2>Rate Limits</h2>
<p>To ensure fair usage and optimal performance for all users, our API has rate limits in place. When you exceed a rate limit, your request will typically receive a <code>429 Too Many Requests</code> HTTP status code.</p>
<details class="fnr-section" open>
<summary class="fnr-summary">Limits by model</summary>
<p>These are our default settings for all models. We understand that your needs may vary. If your application requires higher throughput or more tailored rate limits for specific models, please contact us:</p>
<table>
<thead>
<tr>
<th>Model</th>
<th>Rate Limit</th>
</tr>
</thead>
<tbody><tr>
<td><strong>Fanar</strong></td>
<td>50 requests/minute</td>
</tr>
<tr>
<td><strong>Fanar-S-1-7B</strong></td>
<td>50 requests/minute</td>
</tr>
<tr>
<td><strong>Fanar-C-1-8.7B</strong></td>
<td>50 requests/minute</td>
</tr>
<tr>
<td><strong>Fanar-C-2-27B</strong></td>
<td>50 requests/minute</td>
</tr>
<tr>
<td><strong>Fanar-Sadiq</strong></td>
<td>50 requests/minute</td>
</tr>
<tr>
<td><strong>Fanar-Sadiq-2</strong></td>
<td>50 requests/minute</td>
</tr>
<tr>
<td><strong>Fanar-Sadiq-TTS-1</strong></td>
<td>20 requests/day</td>
</tr>
<tr>
<td><strong>Fanar-Oryx-IVU-2</strong></td>
<td>20 requests/day</td>
</tr>
<tr>
<td><strong>Fanar-Aura-TTS-2</strong></td>
<td>20 requests/day</td>
</tr>
<tr>
<td><strong>Fanar-Aura-STT-1</strong></td>
<td>20 requests/day</td>
</tr>
<tr>
<td><strong>Fanar-Aura-STT-LF-1</strong></td>
<td>10 requests/day</td>
</tr>
<tr>
<td><strong>Fanar-Oryx-IG-2</strong></td>
<td>20 requests/day</td>
</tr>
<tr>
<td><strong>Fanar-Guard-2</strong></td>
<td>50 requests/minute</td>
</tr>
<tr>
<td><strong>Fanar-Shaheen-MT-1</strong></td>
<td>20 requests/day</td>
</tr>
<tr>
<td><strong>Fanar-Diwan</strong></td>
<td>50 requests/minute</td>
</tr>
</tbody>
</table>
</details>
<details class="fnr-section fnr-section-headers">
<summary class="fnr-summary">Response headers</summary>
<p>Every rate-limited response reports your current quota, so you can back off before being throttled:</p>
<table>
<thead>
<tr>
<th>Header</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr><td><code>x-ratelimit-limit</code></td><td>Requests allowed per window.</td></tr>
<tr><td><code>x-ratelimit-remaining</code></td><td>Requests still available in the current window.</td></tr>
<tr><td><code>x-ratelimit-reset</code></td><td>Seconds until a request slot frees up.</td></tr>
<tr><td><code>ratelimit-policy</code></td><td>The quota and its window in seconds, as <code>limit;w=seconds</code> — so <code>100;w=86400</code> means 100 requests per day.</td></tr>
<tr><td><code>retry-after</code></td><td>Seconds to wait before retrying, sent only on a <code>429</code>. When your own quota ran out it counts down to a free slot; when an upstream service throttled the request it carries that service's own hint instead.</td></tr>
</tbody>
</table>
<p class="fnr-note">Because <code>x-ratelimit-limit</code> alone cannot tell <code>3</code> per minute from <code>3</code> per day, read <code>ratelimit-policy</code> when you need the window. These headers are omitted for API keys with unlimited quota.</p>
</details>
termsOfService: https://fanar.qa/en/terms-of-services
contact:
name: Fanar Support — Qatar Computing Research Institute, Hamad Bin Khalifa University
email: support@fanar.qa
url: https://fanar.qa/en/about
version: 1.0.0
x-logo:
url: /static/white-logo.svg
alt: logo
paths:
/v1/chat/completions:
post:
tags:
- Chat
summary: Create Chat Completion
description: This endpoint is compatible with the OpenAI library. If certain parameters are not
supported by the OpenAI library, they can be provided in the `extra_body` field of the OpenAI
request.<br/>When creating the OpenAI object, set the `base_url` as the API domain followed by
`/v1`.
operationId: create_chat_completion_v1_chat_completions_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ChatCompletionRequest'
required: true
responses:
'200':
description: Chat completion response
content:
application/json:
schema:
$ref: '#/components/schemas/ChatCompletionResponse'
text/event-stream:
schema:
oneOf:
- $ref: '#/components/schemas/TokenChunk'
- $ref: '#/components/schemas/ToolCallChunk'
- $ref: '#/components/schemas/ToolResultChunk'
- $ref: '#/components/schemas/ProgressChunk'
- $ref: '#/components/schemas/DoneChunk'
- $ref: '#/components/schemas/ErrorChunk'
'400':
description: The content was filtered
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: content_filter
message: The content was filtered
status: 400
param: prompt
type: safety
'401':
description: Invalid authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: invalid_authentication
message: Invalid authentication
status: 401
'403':
description: Invalid authorization
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: invalid_authorization
message: Invalid authorization
status: 403
'429':
description: Rate limit reached or Exceeded quota
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: exceeded_quota
message: Exceeded quota
status: 429
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: internal_server_error
message: Internal server error
status: 500
'503':
description: Service overloaded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: overloaded
message: Service overloaded
status: 503
'504':
description: Request timed out
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: timeout
message: Request timed out
status: 504
'413':
description: Request entity too large
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: too_large
message: Request entity too large
status: 413
'422':
description: Unprocessable
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: unprocessable
message: Unprocessable
status: 422
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: conflict
message: Conflict
status: 409
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: Not found
message: Not found
status: 404
'410':
description: No longer supported
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: no_longer_supported
message: No longer supported
status: 410
'499':
description: Client closed request before completion
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: client_closed_request
message: Client closed request before completion
status: 499
security:
- Bearer: []
x-codeSamples:
- lang: Curl
label: cURL
source: |
curl -X POST "https://api.fanar.qa/v1/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY_HERE" \
-d '{
"model": "Fanar",
"messages": [
{
"role": "user",
"content": "Your message here"
}
]
}'
- lang: Python
label: Python - OpenAI
source: |
from openai import OpenAI
client = OpenAI(
base_url="https://api.fanar.qa/v1",
api_key="YOUR_API_KEY_HERE",
)
model_name = "Fanar"
messages = [
{"role": "user", "content": "Your message here"}
]
response = client.chat.completions.create(
model=model_name,
messages=messages,
)
print("Assistant Response:\n")
print(response.choices[0].message.content)
- lang: Python - OpenAI Stream
label: Python - OpenAI Stream
source: "from openai import AsyncOpenAI\n\nclient = AsyncOpenAI(\n base_url=\"https://api.fanar.qa/v1\"\
,\n api_key=\"YOUR_API_KEY_HERE\",\n)\n\nmessages = [\n {\"role\": \"user\", \"content\"\
: \"Your message here\"}\n]\n\nstream = await client.chat.completions.create(\n model=\"\
Fanar\",\n messages=messages,\n stream=True\n)\n\nprint(\"Assistant Response:\\n\")\n\n\
content = \"\"\nreferences = None\n\nasync for chunk in stream:\n if chunk.choices and chunk.choices[0].delta:\n\
\ delta = chunk.choices[0].delta\n \n # Capture references from the first\
\ chunk\n if hasattr(delta, 'references') and delta.references:\n references\
\ = delta.references\n \n # Stream content as it arrives\n if delta.content:\n\
\ content += delta.content\n print(delta.content, end=\"\", flush=True)\n\
\nprint(\"\\n\")\n\n# Print references if present\nif references:\n print(\"\\nReferences:\"\
)\n for ref in references:\n number = ref.get(\"number\", \"-\")\n source =\
\ ref.get(\"source\", \"Unknown source\")\n ref_content = ref.get(\"content\", \"\")\n\
\ print(f\"\\n[{number}] {source}\\n{ref_content}\")\n"
- lang: Python - Fanar-Sadiq
label: Python - Fanar-Sadiq
source: "import requests\n\ndef model_api(messages, model):\n headers = {\n \"Authorization\"\
: \"Bearer YOUR_API_KEY_HERE\",\n \"Content-Type\": \"application/json\",\n }\n\n\
\ payload = {\n \"model\": model,\n \"messages\": messages,\n \"max_tokens\"\
: 750,\n }\n\n response = requests.post(\n \"https://api.fanar.qa/v1/chat/completions\"\
, \n json=payload, \n headers=headers\n )\n return response.json()\n\nmodel\
\ = \"Fanar-Sadiq\"\n\nprompt = \"What are the Islamic values?\"\n\nmessages = [\n {\"role\"\
: \"user\", \"content\": prompt}\n]\n\nresponse = model_api(messages=messages, model=model)\n\
\n# Extract the assistant's answer\ncontent = response[\"choices\"][0][\"message\"][\"content\"\
]\nprint(\"Assistant Response:\\n\")\nprint(content)\n\n# Print reference sources if present\n\
references = response[\"choices\"][0][\"message\"].get(\"references\", [])\nif references:\n\
\ print(\"\\nReferences:\")\n for ref in references:\n number = ref.get(\"number\"\
, \"-\")\n source = ref.get(\"source\", \"Unknown source\")\n ref_content = ref.get(\"\
content\", \"\")\n print(f\"\\n[{number}] {source}\\n{ref_content}\")\nelse:\n print(\"\
\\nNo references returned.\")\n"
- lang: Python - Fanar-Sadiq with persona
label: Python - Fanar-Sadiq with persona
source: |
# The "persona" parameter controls the assistant's voice and identity.
# It is only supported for the Fanar-Sadiq model.
import requests
def model_api(messages, persona=None):
headers = {
"Authorization": "Bearer YOUR_API_KEY_HERE",
"Content-Type": "application/json",
}
payload = {
"model": "Fanar-Sadiq",
"messages": messages,
"max_tokens": 750,
}
if persona:
payload["persona"] = persona
response = requests.post(
"https://api.fanar.qa/v1/chat/completions",
json=payload,
headers=headers,
)
return response.json()
messages = [
{"role": "user", "content": "What are the Islamic values?"}
]
# Customize the assistant's voice/identity for this call.
persona = "You are a warm, patient teacher who explains concepts simply for young students."
response = model_api(messages=messages, persona=persona)
content = response["choices"][0]["message"]["content"]
print("Assistant Response:\n")
print(content)
# Print reference sources if present
references = response["choices"][0]["message"].get("references", [])
if references:
print("\nReferences:")
for ref in references:
number = ref.get("number", "-")
source = ref.get("source", "Unknown source")
ref_content = ref.get("content", "")
print(f"\n[{number}] {source}\n{ref_content}")
else:
print("\nNo references returned.")
- lang: Python - Fanar-Sadiq-2
label: Python - Fanar-Sadiq-2
source: |
# Fanar-Sadiq-2 requires additional authorization and is not allowed by default.
import requests
def model_api(messages, madhab=None):
headers = {
"Authorization": "Bearer YOUR_API_KEY_HERE",
"Content-Type": "application/json",
}
payload = {
"model": "Fanar-Sadiq-2",
"messages": messages,
}
if madhab:
payload["madhab"] = madhab
response = requests.post(
"https://api.fanar.qa/v1/chat/completions",
json=payload,
headers=headers,
)
return response.json()
messages = [
{"role": "user", "content": "What are the conditions for Zakat on gold according to the Hanafi school?"}
]
response = model_api(messages=messages, madhab=["hanafi"])
content = response["choices"][0]["message"]["content"]
print("Assistant Response:\n")
print(content)
# Print reference sources if present
references = response["choices"][0]["message"].get("references", [])
if references:
print("\nReferences:")
for ref in references:
number = ref.get("number", "-")
source = ref.get("source", "Unknown source")
ref_content = ref.get("content", "")
print(f"\n[{number}] {source}\n{ref_content}")
- lang: Python - Thinking mode (Fanar-C-1-8.7B)
label: Python - Thinking mode (Fanar-C-1-8.7B)
source: "# Thinking mode requires additional authorization and is not allowed by default.\n\n\
import requests\n\ndef model_api(messages, max_tokens=500):\n headers = {\n \"Authorization\"\
: \"Bearer YOUR_API_KEY_HERE\",\n \"Content-Type\": \"application/json\",\n }\n\n\
\ payload = {\n \"model\": \"Fanar-C-1-8.7B\",\n \"messages\": messages,\n\
\ \"max_tokens\": max_tokens,\n }\n\n response = requests.post(\n \"https://api.fanar.qa/v1/chat/completions\"\
, \n json=payload, \n headers=headers\n )\n return response.json()\n\n#\
\ Step 1: User message with \"thinking_user\" role\nmessages = [\n {\"role\": \"thinking_user\"\
, \"content\": user_input}\n]\n\n# Step 2: Send request to model with extended max tokens\n\
response = model_api(\n messages=messages,\n max_tokens=2000,\n)\n\noutput = response[\"\
choices\"][0][\"message\"][\"content\"]\nfinish_reason = response[\"choices\"][0][\"finish_reason\"\
]\n\n# Step 3: Check if thinking mode continuation is needed\nhas_think_tag = \"</think>\" in\
\ output\nhit_length_limit = finish_reason == \"length\"\n\nif has_think_tag or hit_length_limit:\n\
\ # Extract thinking output\n thinking_output = output.split(\"</think>\")[0] if has_think_tag\
\ else output\n\n # Modify the last \"thinking_user\" role message to \"user\"\n for msg\
\ in reversed(messages):\n if msg[\"role\"] == \"thinking_user\":\n msg[\"\
role\"] = \"user\"\n break\n\n # Add new \"thinking\" role message with extracted\
\ output\n messages.append({\"role\": \"thinking\", \"content\": thinking_output})\n\n \
\ # Re-run model with updated messages, shorter max tokens\n final_response = model_api(\n\
\ messages=messages,\n max_tokens=1000,\n )\n\n final_output = final_response[\"\
choices\"][0][\"message\"][\"content\"]\nelse:\n final_output = output\n\n# final_output\
\ now contains the full response after handling thinking mode\nprint(\"Assistant Response:\\\
n\")\nprint(final_output)\n"
- lang: Python - Thinking mode (Fanar-C-2-27B)
label: Python - Thinking mode (Fanar-C-2-27B)
source: "# Thinking mode requires additional authorization and is not allowed by default.\n\n\
import requests\n\ndef model_api(messages, max_tokens=4000):\n headers = {\n \"Authorization\"\
: \"Bearer YOUR_API_KEY_HERE\",\n \"Content-Type\": \"application/json\",\n }\n\n\
\ payload = {\n \"model\": \"Fanar-C-2-27B\",\n \"messages\": messages,\n \
\ \"max_tokens\": max_tokens,\n \"enable_thinking\": True\n }\n\n response\
\ = requests.post(\n \"https://api.fanar.qa/v1/chat/completions\", \n json=payload,\
\ \n headers=headers\n )\n return response.json()\n\nmessages = [\n {\"role\"\
: \"user\", \"content\": user_input}\n]\n\nresponse = model_api(\n messages=messages\n)\n\
\nprint(\"Assistant Response:\\n\")\nprint(response)\n"
- lang: Python - Image understanding
label: Python - Image understanding
source: |
# Image understanding requires additional authorization and is not allowed by default.
import requests
import base64
def model_api(messages):
headers = {
"Authorization": "Bearer YOUR_API_KEY_HERE",
"Content-Type": "application/json",
}
payload = {
"model": "Fanar-Oryx-IVU-2",
"messages": messages,
"max_tokens": 750,
}
response = requests.post("https://api.fanar.qa/v1/chat/completions", json=payload, headers=headers)
return response.json()
with open("path/to/image.jpg", "rb") as image_file:
raw_b64 = base64.b64encode(image_file.read()).decode("utf-8")
image_b64_url = f"data:image/jpeg;base64,{raw_b64}"
prompt = "Tell me about this image."
messages = [
{
"role": "user",
"content": [
{
"type": "text",
"text": prompt
},
{
"type": "image_url",
"image_url": {
"url": image_b64_url
}
}
]
}
]
response = model_api(messages=messages)
content = response["choices"][0]["message"]["content"]
print("Assistant Response:\n")
print(content)
/v1/audio/speech:
post:
tags:
- Audio
summary: Create Speech
description: This endpoint is compatible with the OpenAI library.<br/>Generates audio from the input
text.
operationId: create_speech_v1_audio_speech_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TextToSpeechRequest'
required: true
responses:
'200':
description: The audio file content or error details.
headers:
X-Id:
description: A unique identifier for the text-to-speech.
schema:
type: string
format: uuid
X-Revised-Input:
description: The processed input text after Quran validation and tagging. This header is
only present when using the Fanar-Sadiq-TTS model. The validator identifies Quranic verses
in the input and wraps them with XML-style tags (e.g., `<quran_start>`, `<quran_end>`)
for proper handling during text-to-speech processing. It may also apply corrections such
as diacritical marks normalization or verse formatting. If no Quranic content was detected
or no modifications were needed, this header will be absent.
schema:
type: string
content:
application/json:
schema: {}
audio/mpeg:
schema:
type: string
format: binary
audio/wav:
schema:
type: string
format: binary
'400':
description: The content was filtered
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: content_filter
message: The content was filtered
status: 400
param: prompt
type: safety
'401':
description: Invalid authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: invalid_authentication
message: Invalid authentication
status: 401
'403':
description: Invalid authorization
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: invalid_authorization
message: Invalid authorization
status: 403
'429':
description: Rate limit reached or Exceeded quota
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: exceeded_quota
message: Exceeded quota
status: 429
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: internal_server_error
message: Internal server error
status: 500
'503':
description: Service overloaded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: overloaded
message: Service overloaded
status: 503
'504':
description: Request timed out
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: timeout
message: Request timed out
status: 504
'413':
description: Request entity too large
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: too_large
message: Request entity too large
status: 413
'422':
description: Unprocessable
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: unprocessable
message: Unprocessable
status: 422
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: conflict
message: Conflict
status: 409
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: Not found
message: Not found
status: 404
'410':
description: No longer supported
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: no_longer_supported
message: No longer supported
status: 410
'499':
description: Client closed request before completion
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: client_closed_request
message: Client closed request before completion
status: 499
security:
- Bearer: []
x-codeSamples:
- lang: Curl
label: cURL
source: |
curl -X POST "https://api.fanar.qa/v1/audio/speech" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
--output greeting.mp3 \
-d '{
"model": "Fanar-Aura-TTS-2",
"input": "Hello! I hope you are having a wonderful day.",
"voice": "Amelia",
"response_format": "mp3"
}'
- lang: Python
label: Python - OpenAI
source: |
# Text-to-Speech requires additional authorization and is not allowed by default.
from openai import OpenAI
client = OpenAI(
base_url="https://api.fanar.qa/v1",
api_key="YOUR_API_KEY"
)
response = client.audio.speech.create(
model="Fanar-Aura-TTS-2",
input="Hello! I hope you are having a wonderful day.",
voice="Amelia",
response_format="mp3",
)
with open("greeting.mp3", "wb") as f:
f.write(response.read())
- lang: Python - requests
label: Python - requests
source: |
# Text-to-Speech requires additional authorization and is not allowed by default.
import requests
url = "https://api.fanar.qa/v1/audio/speech"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
data = {
"model": "Fanar-Aura-TTS-2",
"input": "Hello! I hope you are having a wonderful day.",
"voice": "Amelia",
"response_format": "mp3"
}
response = requests.post(url, headers=headers, json=data)
with open("greeting.mp3", "wb") as f:
f.write(response.content)
- lang: Python - requests for Quranic text
label: Python - requests for Quranic text
source: |
# Text-to-Speech requires additional authorization and is not allowed by default.
import requests
url = "https://api.fanar.qa/v1/audio/speech"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
data = {
"model": "Fanar-Sadiq-TTS-1",
"input": "Quranic text goes here",
"voice": "Amelia",
"quran_reciter": "abdul-basit",
"response_format": "mp3"
}
response = requests.post(url, headers=headers,
# --- truncated at 32 KB (196 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hbku/refs/heads/main/openapi/hbku-fanar-api-openapi.yml