Chat Completions

POST/api/v1/chat/completions

Generate chat completions using any supported model. This endpoint is fully compatible with the OpenAI Chat Completions API format, regardless of which provider handles the request.

Authentication

Pass your Meridian proxy key as a Bearer token in the Authorization header:

Header

Authorization: Bearer sk-mrd-your-proxy-key

Request body

Parameter	Type	Required	Description
`model`	string	Yes	Model identifier (e.g., `gpt-4.1`, `claude-sonnet-4-20250514`)
`messages`	array	Yes	Array of message objects with `role` and `content`
`temperature`	number	No	Sampling temperature (0–2). Default varies by model.
`max_tokens`	integer	No	Maximum tokens to generate
`stream`	boolean	No	Enable server-sent events streaming. Default: `false`

Message object

Field	Type	Description
`role`	string	`system`, `user`, or `assistant`
`content`	string	The message content

Response

200 OK

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1709836800,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 9,
    "total_tokens": 21
  }
}

Error responses

Status	Code	Description
401	`INVALID_KEY`	Proxy key is invalid or revoked
400	`MISSING_PROVIDER`	No provider key configured for the requested model
400	`UNSUPPORTED_MODEL`	Model name not recognized
502	`PROVIDER_ERROR`	Upstream provider returned an error

Examples

curl

curl -X POST https://your-meridian.vercel.app/api/v1/chat/completions \
  -H "Authorization: Bearer sk-mrd-your-proxy-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "What is the capital of France?" }
    ],
    "temperature": 0.7,
    "max_tokens": 150
  }'

JavaScript

JavaScript (fetch)

const response = await fetch(
  "https://your-meridian.vercel.app/api/v1/chat/completions",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sk-mrd-your-proxy-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "claude-sonnet-4-20250514",
      messages: [
        { role: "system", content: "You are a helpful assistant." },
        { role: "user", content: "What is the capital of France?" },
      ],
      temperature: 0.7,
      max_tokens: 150,
    }),
  }
);

const data = await response.json();
console.log(data.choices[0].message.content);

Python

Python (requests)

import requests

response = requests.post(
    "https://your-meridian.vercel.app/api/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-mrd-your-proxy-key",
        "Content-Type": "application/json",
    },
    json={
        "model": "gemini-2.5-pro",
        "messages": [
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "What is the capital of France?"},
        ],
        "temperature": 0.7,
        "max_tokens": 150,
    },
)

data = response.json()
print(data["choices"][0]["message"]["content"])

Streaming

Set stream: true to receive server-sent events. Meridian proxies the SSE stream from the upstream provider as-is.

Streaming example (curl)

curl -N -X POST https://your-meridian.vercel.app/api/v1/chat/completions \
  -H "Authorization: Bearer sk-mrd-your-proxy-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{ "role": "user", "content": "Tell me a joke." }],
    "stream": true
  }'

Each SSE event follows the format: data: {...}, with a final data: [DONE] sentinel.