AI Gateway: Chat Completions
OpenAI-compatible chat completions endpoint backed by Mersal's multi-provider AI Pool.
The AI Gateway is a front door to Mersal's internal AI Pool — a multi-provider AI router with automatic failover. Instead of integrating against a single AI provider and hardcoding it into your app, you send requests to Mersal's OpenAI-compatible endpoint, and the AI Pool routes the request to a healthy underlying provider. If one provider is degraded or down, the pool fails over automatically, so you still get a working completion.
The request and response shapes follow the OpenAI chat completions convention, so existing OpenAI-compatible tooling generally works with minimal changes — just point it at Mersal's base URL and use your AI Pool key.
Endpoint
Authentication
This endpoint uses a different authentication mechanism from the channel-sending endpoints: a Bearer token, not the Api-key header.
Authorization: Bearer <ai-pool-key>AI Pool keys are created specifically for AI Gateway access, separate from your channel API key. See Authentication for details on where to generate one.
Request parameters
| Name | Type | Required | Description |
|---|---|---|---|
messages | array | Yes | Array of chat messages, each with role (e.g. user, assistant, system) and content. |
temperature | number | No | Sampling temperature controlling response randomness. |
max_tokens | number | No | Maximum number of tokens to generate in the completion. |
Example request
curl -X POST https://mersal.it/api/ai/v1/chat/completions \
-H "Authorization: Bearer YOUR_AI_POOL_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{ "role": "user", "content": "Hello" }
],
"temperature": 0.5,
"max_tokens": 600
}'<?php
$response = Http::withHeaders([
'Authorization' => 'Bearer YOUR_AI_POOL_KEY',
'Content-Type' => 'application/json',
])->post('https://mersal.it/api/ai/v1/chat/completions', [
'messages' => [
['role' => 'user', 'content' => 'Hello'],
],
'temperature' => 0.5,
'max_tokens' => 600,
]);
$data = $response->json();
$reply = $data['choices'][0]['message']['content'];<?php
$payload = [
'messages' => [
['role' => 'user', 'content' => 'Hello'],
],
'temperature' => 0.5,
'max_tokens' => 600,
];
$ch = curl_init('https://mersal.it/api/ai/v1/chat/completions');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_AI_POOL_KEY',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);// Works with the official openai library — just change the baseURL and key
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://mersal.it/api/ai/v1",
apiKey: process.env.MERSAL_AI_POOL_KEY,
});
const completion = await client.chat.completions.create({
messages: [{ role: "user", content: "Hello" }],
temperature: 0.5,
max_tokens: 600,
});
console.log(completion.choices[0].message.content);# Works with the official openai library — just change the base_url and key
import os
from openai import OpenAI
client = OpenAI(
base_url="https://mersal.it/api/ai/v1",
api_key=os.environ["MERSAL_AI_POOL_KEY"],
)
completion = client.chat.completions.create(
model="mersal-pool",
messages=[{"role": "user", "content": "Hello"}],
temperature=0.5,
max_tokens=600,
)
print(completion.choices[0].message.content)Example response
{
"id": "chatcmpl-xxxxxxx",
"object": "chat.completion",
"created": 1730000000,
"model": "mersal-pool",
"choices": [
{
"index": 0,
"message": { "role": "assistant", "content": "Hi there!" },
"finish_reason": "stop"
}
],
"usage": { "prompt_tokens": 12, "completion_tokens": 8, "total_tokens": 20 },
"mersal_pool": { "provider": "...", "model": "...", "latency_ms": 420, "attempts": 1 }
}The mersal_pool object reports which underlying provider actually served the request, how long it took, and how many attempts the pool made (relevant if the first provider it tried failed over to another).
Listing available models
Returns the models currently available through the AI Pool, using the same Bearer authentication.
Errors
Common failure modes are a missing/invalid Bearer token, or throttling if you exceed your key's configured request limits — see Rate Limits. For the general error format, see Errors and Status Codes.