AI Services Gateway API

Quick start#

curl https://api.adelk.sa/llm/v1/models -H "Authorization: Bearer YOUR_API_KEY"

curl https://api.adelk.sa/llm/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "team-chat", "messages": [{"role": "user", "content": "Hello!"}]}'

Authentication#

Every request carries your key as a Bearer token:

Authorization: Bearer YOUR_API_KEY

• A key is granted one or more clusters; their models are the models you can use. Nothing else is listed or reachable.
• Ollama clients take the key in their connection settings (as a Bearer token / API key).
• The x-api-key and api-key headers are not accepted — use Authorization.
• Repeated invalid keys from one address are answered with 429 too_many_auth_failures for the rest of the minute. A valid key is never blocked.

Models#

curl https://api.adelk.sa/llm/v1/models -H "Authorization: Bearer YOUR_API_KEY"

{
  "object": "list",
  "data": [
    { "id": "team-chat",  "object": "model", "created": 1791309574, "owned_by": "gateway" },
    { "id": "team-embed", "object": "model", "created": 1791309574, "owned_by": "gateway" }
  ]
}

Model names

• Models are published under public names chosen by the administrator. Send the name exactly as listed; letter case does not matter and :latest is optional.
• Only public names are accepted. Any other name is treated as unknown: it goes to the default model, or 404 model_not_found if the administrator disabled that fallback. /models/{id} and /api/show always answer 404 for unknown names.
• Chat models work with chat / responses / completions / generate; embedding models with the embeddings endpoints.

What the gateway tells you about a model

• Capabilities (completion, tools, vision, thinking, insert, embedding) and the context length — from POST /api/show.
• The model's underlying identity (family, size, quantization, license, weights digest) is not disclosed; those fields are empty. Error messages from the model also use the public name.

Context window and output limit

• Each model runs with a fixed context window set by the administrator, so it stays loaded and answers fast. num_ctx from a client is ignored.
• A prompt that does not fit is rejected with 400 context_length_exceeded — never silently truncated. Coding tools use this code to compact their context.
• max_tokens is capped by the model's output limit, which is also the default when you omit it.

All endpoints#

All paths are relative to the base URL https://api.adelk.sa/llm/v1. For the OpenAI SDKs set it as base_url; for Ollama clients set it as the Ollama host.

Every endpoint answers CORS preflight requests, so browser apps can call it directly. The model listings and details (/models, /api/tags, /api/show, /api/ps) do not count against your rate limit or quota.

Chat#

The same conversation body works on both. OpenAI returns a chat.completion (SSE when streaming); Ollama returns its native object (NDJSON when streaming, which is its default).

{
  "model": "team-chat",
  "messages": [
    { "role": "system", "content": "You are concise." },
    { "role": "user", "content": "Capital of Saudi Arabia?" }
  ],
  "temperature": 0.7,
  "max_tokens": 1024
}

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1791309574,
  "model": "team-chat",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "Riyadh." },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 20, "completion_tokens": 3, "total_tokens": 23 }
}

{
  "model": "team-chat",
  "created_at": "2026-10-07T10:00:00Z",
  "message": { "role": "assistant", "content": "Riyadh." },
  "done": true,
  "done_reason": "stop",
  "prompt_eval_count": 20,
  "eval_count": 3,
  "total_duration": 123456789
}

• finish_reason is length when max_tokens was reached and tool_calls when the model called a tool.
• Reasoning models return their thinking in message.reasoning_content (OpenAI) or message.thinking (Ollama).
• /chat/completions with an empty messages list is a 400. On /api/chat it is a load request — see Ollama native.

Responses#

The OpenAI Responses API, used by Codex CLI and agent frameworks. The gateway is stateless: send the whole conversation in input on every turn.

{
  "model": "team-chat",
  "instructions": "You are a helpful assistant.",
  "input": [
    { "role": "user", "content": "What is 2 + 2?" }
  ],
  "max_output_tokens": 512
}

{
  "id": "resp_abc",
  "object": "response",
  "status": "completed",
  "model": "team-chat",
  "output": [{
    "type": "message", "role": "assistant",
    "content": [{ "type": "output_text", "text": "4" }]
  }],
  "usage": { "input_tokens": 18, "output_tokens": 1, "total_tokens": 19 },
  "store": false
}

With "stream": true the reply is named SSE events (response.created → response.output_text.delta… → response.completed), without [DONE]. See Streaming.

Completions & fill-in-the-middle#

Raw text completion without a chat template, and FIM (code completion in editors) when a suffix is sent. FIM needs a model with the insert capability; others answer 400 "does not support insert".

{
  "model": "team-coder",
  "prompt": "def add(a, b):\n    ",
  "suffix": "\n\nprint(add(1, 2))",
  "max_tokens": 64
}

{
  "id": "cmpl-abc",
  "object": "text_completion",
  "model": "team-coder",
  "choices": [{
    "text": "return a + b",
    "index": 0, "logprobs": null, "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 15, "completion_tokens": 5, "total_tokens": 20 }
}

• /completions: echo: true prepends the prompt. Without max_tokens the model's output limit applies (not 16). Several prompts, token ids, n/best_of > 1, logprobs and logit_bias are rejected with 400.
• /api/generate: prompt + optional system / images works as a one-turn chat; raw: true sends the text verbatim; format requests JSON. template, context and keep_alive are ignored.

Embeddings#

{
  "model": "team-embed",
  "input": ["first text", "second text"]
}

{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.012, -0.034, …] },
    { "object": "embedding", "index": 1, "embedding": [0.021, 0.008, …] }
  ],
  "model": "team-embed",
  "usage": { "prompt_tokens": 6, "total_tokens": 6 }
}

Only input tokens are metered. Token-id arrays and empty strings are rejected. Use an embedding model from your list; with none, the reply is 403 model_not_available.

Ollama native#

Besides chat, generate and embeddings above, Ollama clients use these endpoints to discover models and check the connection.

GET /api/tags

{
  "models": [{
    "name": "team-chat",
    "model": "team-chat",
    "modified_at": "2026-10-01T09:00:00+03:00",
    "size": 0,
    "digest": "5b1e…",
    "details": { "parent_model": "", "format": "", "family": "", "families": null, "parameter_size": "", "quantization_level": "" }
  }]
}

POST /api/show

{ "model": "team-chat" }

{
  "license": "",
  "modelfile": "",
  "parameters": "num_ctx                       32768",
  "template": "",
  "details": { "family": "", "parameter_size": "", … },
  "model_info": {
    "general.architecture": "gateway",
    "gateway.context_length": 32768
  },
  "capabilities": ["completion", "tools", "vision"],
  "modified_at": "2026-10-01T09:00:00+03:00"
}

gateway.context_length is the context window the model really runs with. A missing model shows the default chat model.

GET /api/ps · GET /api/version · GET /

/api/ps lists which of your models are loaded now, with expires_at. /api/version and / ("Adelk AI Gateway is running") are connection checks.

Load requests

Ollama clients "warm up" a model with an empty /api/generate prompt or an empty /api/chat messages list. The gateway answers these itself, after checking the key and the model — nothing is sent to the servers, and nothing is metered. Models are kept loaded by the administrator; a cold model loads with your first real request.

{ "model": "team-chat", "prompt": "" }

{ "model": "team-chat", "created_at": "2026-10-07T10:00:00Z", "response": "", "done": true, "done_reason": "load" }

Parameters#

Tools, vision, JSON, reasoning#

Each feature uses the protocol's own parameters. The model's capabilities decide: if the model does not support a feature, its error comes back as 400 upstream_invalid_request instead of being silently ignored. Check capabilities in /api/show.

• Tools
• Vision (OpenAI)
• Vision (Ollama)
• Structured output

{
  "model": "team-chat",
  "messages": [{ "role": "user", "content": "What is the weather in Riyadh?" }],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get the current weather for a city",
      "parameters": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"]
      }
    }
  }],
  "tool_choice": "auto"
}

{
  "model": "team-chat",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "What is in this image?" },
      { "type": "image_url", "image_url": { "url": "data:image/png;base64,iVBORw0KGgo..." } }
    ]
  }]
}

{
  "model": "team-chat",
  "messages": [
    { "role": "user", "content": "What is in this image?", "images": ["iVBORw0KGgo..."] }
  ],
  "stream": false
}

{
  "model": "team-chat",
  "messages": [{ "role": "user", "content": "Capital of Saudi Arabia?" }],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "answer",
      "schema": { "type": "object", "properties": { "city": { "type": "string" } }, "required": ["city"] }
    }
  }
}

Images must be inline base64. Remote image URLs are not fetched and are rejected with 400 invalid_image_url.

Streaming#

Set "stream": true (Ollama endpoints stream by default). Tokens are delivered as they are generated, in each protocol's own format.

• OpenAI · SSE
• Ollama · NDJSON
• Responses · events

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":9,"completion_tokens":3,"total_tokens":12}}

data: [DONE]

{"model":"team-chat","message":{"role":"assistant","content":"Hello"},"done":false}
{"model":"team-chat","message":{"role":"assistant","content":" there"},"done":false}
{"model":"team-chat","message":{"role":"assistant","content":""},"done":true,"done_reason":"stop","prompt_eval_count":9,"eval_count":3}

event: response.created
data: {"type":"response.created","sequence_number":0,"response":{…}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","sequence_number":4,"delta":"Hello"}

event: response.completed
data: {"type":"response.completed","sequence_number":9,"response":{…}}

If you put the gateway behind your own proxy, turn off response buffering and compression for these paths, or tokens arrive in bursts.

Integrations#

• cURL
• Python · OpenAI
• Node · OpenAI
• Python · Ollama
• JavaScript · fetch
• Python · requests

# OpenAI protocol
curl https://api.adelk.sa/llm/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "team-chat", "messages": [{"role": "user", "content": "Explain DNS in one sentence."}]}'

# Ollama protocol
curl https://api.adelk.sa/llm/v1/api/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"model": "team-chat", "messages": [{"role": "user", "content": "Why is the sky blue?"}], "stream": false}'

from openai import OpenAI

client = OpenAI(base_url="https://api.adelk.sa/llm/v1", api_key="YOUR_API_KEY")

print([m.id for m in client.models.list()])   # the models your key can use

resp = client.chat.completions.create(
    model="team-chat",
    messages=[{"role": "user", "content": "Write a haiku about code."}],
)
print(resp.choices[0].message.content)

# Streaming
for chunk in client.chat.completions.create(
    model="team-chat",
    messages=[{"role": "user", "content": "Count to five."}],
    stream=True,
):
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="", flush=True)

# Embeddings
vec = client.embeddings.create(model="team-embed", input="hello").data[0].embedding

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.adelk.sa/llm/v1", apiKey: process.env.GATEWAY_API_KEY });

const resp = await client.chat.completions.create({
  model: "team-chat",
  messages: [{ role: "user", content: "Tell me a joke." }],
});
console.log(resp.choices[0].message.content);

// Responses API
const r = await client.responses.create({ model: "team-chat", input: "Say hi" });
console.log(r.output_text);

from ollama import Client

client = Client(host="https://api.adelk.sa/llm/v1", headers={"Authorization": "Bearer YOUR_API_KEY"})

print([m.model for m in client.list().models])
resp = client.chat(model="team-chat", messages=[{"role": "user", "content": "Hello!"}])
print(resp.message.content)

const res = await fetch("https://api.adelk.sa/llm/v1/chat/completions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify({
    model: "team-chat",
    messages: [{ role: "user", content: "Tell me a joke." }],
  }),
});
const data = await res.json();
console.log(data.choices[0].message.content);

import requests

resp = requests.post(
    "https://api.adelk.sa/llm/v1/chat/completions",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"model": "team-chat", "messages": [{"role": "user", "content": "Hello!"}]},
    timeout=300,
)
resp.raise_for_status()
print(resp.json()["choices"][0]["message"]["content"])

Tools and apps

# ~/.codex/config.toml — Codex CLI over the Responses API
model = "team-coder"            # a name from GET /v1/models, strong at tool calling
model_provider = "gateway"

[model_providers.gateway]
name = "AI Gateway"
base_url = "https://api.adelk.sa/llm/v1"
env_key = "GATEWAY_API_KEY"     # environment variable holding your key
wire_api = "responses"

Codex sends a large context: use a model with a large context window, and ask your administrator to turn off prompt logging for coding keys.

Policies & limits#

Set by the administrator per key and enforced on every request. They are not part of the request body, but they shape the replies you get.

Long requests are bounded by a gateway-wide time limit (including retries on other servers); set your client timeout generously (minutes, not seconds) for long generations.

Errors#

Errors are JSON in each protocol's own shape:

{"error": {"message": "…", "type": "invalid_request_error", "param": "model", "code": "model_not_found"}}

{"error": "model 'x' not found"}

Not available#

Postman#

A ready collection covers every endpoint: chat (plain, streaming, vision, tools, JSON, reasoning), Responses, completions and FIM, embeddings, the Ollama native endpoints and load requests, plus examples of common errors.

1. Import both files into Postman.
2. Select the AI Gateway environment (top right).
3. Set base_url (e.g. https://api.adelk.sa/llm, without /v1) and api_key.
4. Run List models: when model is empty it is set to the first listed model (make sure it is a chat model). Set embed_model to an embedding model for the embeddings folder.