API Documentation

Complete reference for integrating with alAPI's LLM and OCR services

v1 Base URL: https://dev.alapi.deep.sa/v1

OpenAI Compatible Use the official OpenAI SDK with our base URL. Drop-in replacement for existing applications.

Quick Navigation

LLM API

OCR API

Error Handling

LLM API

OpenAI-compatible API for chat completions and embeddings. Use your favorite models through a unified interface.

Authentication

All API requests require authentication using a Bearer token in the Authorization header.

Request Header:

header

Authorization: Bearer YOUR_API_KEY

API Key: Generate API keys from your Dashboard.

SDK Setup Example:

main.py

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://dev.alapi.deep.sa/v1"
)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://dev.alapi.deep.sa/v1'
});

curl "https://dev.alapi.deep.sa/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Chat Completions

Create Chat Completion

Creates a model response for the given chat conversation

POST

Endpoint:

endpoint

https://dev.alapi.deep.sa/v1/chat/completions

Request Body:

request.json

{
  "model": "llama-3.3-70b-versatile",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "temperature": 0.7,
  "max_tokens": 1024,
  "stream": false
}

Parameters:

Name	Type	Required	Description
`model`	string	Yes	ID of the model to use
`messages`	array	Yes	Array of message objects with role and content
`temperature`	number	No	Sampling temperature (0-2). Default: 1
`max_tokens`	integer	No	Maximum tokens to generate
`stream`	boolean	No	If true, returns a stream of events
`top_p`	number	No	Nucleus sampling parameter. Default: 1

Response (200 OK):

response.json

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1706745000,
  "model": "llama-3.3-70b-versatile",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 10,
    "total_tokens": 30
  }
}

Code Examples:

main.py

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://dev.alapi.deep.sa/v1"
)

response = client.chat.completions.create(
    model="llama-3.3-70b-versatile",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of Saudi Arabia?"}
    ],
    temperature=0.7,
    max_tokens=1024
)

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

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://dev.alapi.deep.sa/v1'
});

async function main() {
  const response = await client.chat.completions.create({
    model: 'llama-3.3-70b-versatile',
    messages: [
      { role: 'system', content: 'You are a helpful assistant.' },
      { role: 'user', content: 'What is the capital of Saudi Arabia?' }
    ],
    temperature: 0.7,
    max_tokens: 1024
  });

  console.log(response.choices[0].message.content);
}

main();

curl -X POST "https://dev.alapi.deep.sa/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.3-70b-versatile",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of Saudi Arabia?"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024
  }'

Streaming Responses

Server-Sent Events (SSE)

Stream responses token by token for real-time output

SSE

How it works: Set stream: true in your request. The response will be sent as Server-Sent Events, with each chunk containing a delta of the response content.

Code Examples:

main.py

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://dev.alapi.deep.sa/v1"
)

stream = client.chat.completions.create(
    model="llama-3.3-70b-versatile",
    messages=[
        {"role": "user", "content": "Write a short poem about coding"}
    ],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://dev.alapi.deep.sa/v1'
});

async function main() {
  const stream = await client.chat.completions.create({
    model: 'llama-3.3-70b-versatile',
    messages: [{ role: 'user', content: 'Write a short poem about coding' }],
    stream: true,
  });

  for await (const chunk of stream) {
    const content = chunk.choices[0]?.delta?.content || '';
    process.stdout.write(content);
  }
}

main();

curl -X POST "https://dev.alapi.deep.sa/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "llama-3.3-70b-versatile",
    "messages": [{"role": "user", "content": "Write a short poem about coding"}],
    "stream": true
  }'

Embeddings

Create Embeddings

Creates an embedding vector representing the input text

POST

Endpoint:

endpoint

https://dev.alapi.deep.sa/v1/embeddings

Request Body:

request.json

{
  "model": "text-embedding-3-small",
  "input": "The quick brown fox jumps over the lazy dog"
}

Parameters:

Name	Type	Required	Description
`model`	string	Yes	ID of the embedding model to use
`input`	string \| array	Yes	Text to embed. Can be a string or array of strings
`encoding_format`	string	No	Format for the embeddings: 'float' or 'base64'. Default: float
`dimensions`	integer	No	Number of dimensions for the output embeddings (model-dependent)

Response (200 OK):

response.json

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023064255, -0.009327292, ...]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 9,
    "total_tokens": 9
  }
}

Code Examples:

main.py

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://dev.alapi.deep.sa/v1"
)

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="The quick brown fox jumps over the lazy dog"
)

embedding = response.data[0].embedding
print(f"Embedding dimension: {len(embedding)}")

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://dev.alapi.deep.sa/v1'
});

async function main() {
  const response = await client.embeddings.create({
    model: 'text-embedding-3-small',
    input: 'The quick brown fox jumps over the lazy dog'
  });

  const embedding = response.data[0].embedding;
  console.log(`Embedding dimension: ${embedding.length}`);
}

main();

curl -X POST "https://dev.alapi.deep.sa/v1/embeddings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "The quick brown fox jumps over the lazy dog"
  }'

Available Models

The following models are currently available through alAPI. Use the model name in your API requests.

Model Name	Provider	Avg Latency
`deep-sa/alEmbedding`	deepcloud	-
`deep-sa/alLLM`	deepcloud	~6710.25ms
`google/gemini-2.5-flash`	google_gemini	-
`google/gemini-2.5-flash-lite`	google_gemini	-
`google/gemini-3-flash`	google_gemini	~10707ms
`google/gemini-3-pro`	google_gemini	-
`gpt-oss-120b`	groq	-
`gpt-oss-20b`	groq	-
`llama-3.3-70b`	groq	-
`llama-4-maverick-17b`	groq	-
`opanai/gpt-5-mini`	openai	-
`qwen3-32b`	groq	-

OCR API

Extract text from documents with advanced Arabic and English OCR. Supports PDFs and images with automatic deskewing and layout detection.

Supported file formats

PDF

Supports Arabic and English text extraction with automatic language detection

Upload Document

Upload File for OCR

Upload a document and start OCR processing

POST

Endpoint:

endpoint

https://dev.alapi.deep.sa/v1/ocr/upload

Request Format:

Content-Type: multipart/form-data

Name	Type	Description
`file`	file	Document file (PDF)
`consent_research`	boolean	Consent to use data for research (default: false)

Response (200 OK):

response.json

{
  "token": "abc123xyz...",
  "status": "queued",
  "progress": 0,
  "upload_progress": 100,
  "queue_position": 1
}

Code Examples:

upload.py

import requests

url = "https://dev.alapi.deep.sa/v1/ocr/upload"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

with open("document.pdf", "rb") as f:
    files = {"file": f}
    data = {"consent_research": "false"}
    response = requests.post(url, headers=headers, files=files, data=data)

result = response.json()
token = result["token"]
print(f"Job started, token: {token}")

const fs = require('fs');
const FormData = require('form-data');

const form = new FormData();
form.append('file', fs.createReadStream('document.pdf'));
form.append('consent_research', 'false');

const response = await fetch('https://dev.alapi.deep.sa/v1/ocr/upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    ...form.getHeaders()
  },
  body: form
});

const { token } = await response.json();
console.log(`Job started, token: ${token}`);

curl -X POST "https://dev.alapi.deep.sa/v1/ocr/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "consent_research=false"

Job Status

Get Job Status

Retrieve the current status and results of an OCR job

GET

Endpoint:

endpoint

https://dev.alapi.deep.sa/v1/ocr/jobs/{token}

Status Values:

Status	Description
`queued`	Job is waiting in the processing queue
`processing`	Document is being processed
`done`	Processing complete. Results available in the pages array
`error`	Processing failed. Check the error field for details

Response (when status is done):

response.json

{
  "filename": "document.pdf",
  "status": "done",
  "progress": 100,
  "total_pages": 5,
  "pages": [
    {
      "page_num": 1,
      "text": "Extracted text from page 1...",
      "num_segments": 12,
      "elapsed": 2.45
    }
  ],
  "expires_at": "2026-02-05T18:30:00Z"
}

Complete OCR Flow:

ocr_process.py

import requests
import time

API_BASE = "https://dev.alapi.deep.sa/v1"
API_KEY = "YOUR_API_KEY"
headers = {"Authorization": f"Bearer {API_KEY}"}

# 1. Upload document
with open("document.pdf", "rb") as f:
    response = requests.post(
        f"{API_BASE}/ocr/upload",
        headers=headers,
        files={"file": f},
        data={"consent_research": "false"}
    )
result = response.json()
token = result["token"]

# 2. Poll for completion
while True:
    status_response = requests.get(
        f"{API_BASE}/ocr/jobs/{token}",
        headers=headers
    )
    job = status_response.json()
    
    print(f"Status: {job['status']}, Progress: {job.get('progress', 0)}%")
    
    if job["status"] == "done":
        # 3. Extract text from all pages
        full_text = "\n\n".join(page["text"] for page in job["pages"])
        print("Extracted text:", full_text)
        break
    elif job["status"] == "error":
        print("Error:", job.get("error"))
        break
    
    time.sleep(2)  # Poll every 2 seconds

const fs = require('fs');
const FormData = require('form-data');

const API_BASE = 'https://dev.alapi.deep.sa/v1';
const API_KEY = 'YOUR_API_KEY';
const headers = { 'Authorization': `Bearer ${API_KEY}` };

async function processDocument(filePath) {
  // 1. Upload document
  const form = new FormData();
  form.append('file', fs.createReadStream(filePath));
  form.append('consent_research', 'false');

  const uploadResponse = await fetch(`${API_BASE}/ocr/upload`, {
    method: 'POST',
    headers: { ...headers, ...form.getHeaders() },
    body: form
  });
  const { token } = await uploadResponse.json();

  // 2. Poll for completion
  while (true) {
    const statusResponse = await fetch(`${API_BASE}/ocr/jobs/${token}`, { headers });
    const job = await statusResponse.json();
    
    console.log(`Status: ${job.status}, Progress: ${job.progress || 0}%`);
    
    if (job.status === 'done') {
      const fullText = job.pages.map(p => p.text).join('\n\n');
      console.log('Extracted text:', fullText);
      return fullText;
    } else if (job.status === 'error') {
      throw new Error(job.error);
    }
    
    await new Promise(r => setTimeout(r, 2000));
  }
}

processDocument('document.pdf');

Get Single Page

Get Page by Number

Retrieve OCR text and thumbnail for a single page

GET

Endpoint:

endpoint

https://dev.alapi.deep.sa/v1/ocr/jobs/{token}/{page_num}

Request Format:

Name	Type	Description
`token`	String	Access token received from upload
`page_num`	Integer	Page number (1-indexed)

Response (200 OK):

response.json

{
  "page_num": 1,
  "text": "Extracted text from this page...",
  "thumbnail": {
    "url": "https://objectstorage.me-jeddah-1.oraclecloud.com/..."
  },
  "status": "done",
  "num_segments": 12,
  "elapsed": 2.34
}

Code Examples:

get_page.py

import requests

API_BASE = "https://dev.alapi.deep.sa/v1"
API_KEY = "YOUR_API_KEY"
headers = {"Authorization": f"Bearer {API_KEY}"}

token = "YOUR_TOKEN_HERE"
page_num = 3

response = requests.get(
    f"{API_BASE}/ocr/jobs/{token}/{page_num}",
    headers=headers
)

page = response.json()
print(f"Page {page['page_num']}: {page['status']}")
print(page["text"])

curl "https://dev.alapi.deep.sa/v1/ocr/jobs/YOUR_TOKEN_HERE/3" \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Handling:

Status	Description
`400`	page_num must be >= 1
`404`	Job or page not found
`410`	Job has expired

Thumbnails

Get Page Thumbnails

Retrieve page thumbnails with pagination

GET

Endpoint:

endpoint

https://dev.alapi.deep.sa/v1/ocr/thumbnails/{token}?start=0&limit=10

Response:

response.json

{
  "thumbnails": [
    {
      "page_num": 1,
      "data": "data:image/png;base64,iVBORw0KGgo..."
    }
  ],
  "start": 0,
  "end": 10,
  "total_pages": 25,
  "has_more": true
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure of requests.

Error Response Format:

error.json

{
  "error": {
    "message": "Error description",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

400 Bad Request - Invalid request parameters

401 Unauthorized - Missing or invalid API key

403 Forbidden - API key lacks required permissions

404 Not Found - Resource doesn't exist

429 Too Many Requests - Rate limit exceeded

500 Internal Server Error - Server-side error

Ready to Get Started?

Generate an API key from your dashboard and start building

Get API Key View Pricing