API reference

OpenAI-compatible. Drop in.

Authentication

ALL

Authorization: Bearer <key>

All requests require an API key passed in the Authorization header. Obtain your key from the dashboard.

curl https://api.meridian.so/v1/chat/completions \
  -H "Authorization: Bearer $MERIDIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

Chat completions

POST

/v1/chat/completions

Creates a model response for a given chat conversation. Streaming is supported via SSE when stream: true.

Name	Type	Required	Description
model	string	Yes	Model ID, e.g. meridian-1, meridian-1-turbo.
messages	array	Yes	List of message objects with role (system, user, assistant) and content.
stream	boolean	No	When true, responses are streamed as SSE events. Default false.
tools	array	No	List of tool definitions the model may call.
temperature	number	No	Sampling temperature 0–2. Higher = more random. Default 1.
top_p	number	No	Nucleus sampling probability mass. Default 1.
max_tokens	integer	No	Maximum tokens in the completion.
reasoning_effort	string	No	Constrains reasoning depth. Values: low, medium, high. Default medium.

curl https://api.meridian.so/v1/chat/completions \
  -H "Authorization: Bearer $MERIDIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meridian-1",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain quantum computing in one sentence."}
    ],
    "temperature": 0.7,
    "max_tokens": 256
  }'

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1717000000,
  "model": "meridian-1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Quantum computing uses qubits that can exist in superposition, enabling certain calculations to be performed exponentially faster than classical computers."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 24,
    "total_tokens": 52
  }
}

Embeddings

POST

/v1/embeddings

Creates an embedding vector representing the input text.

Name	Type	Required	Description
input	string \| array	Yes	Text to embed. Pass an array of strings for batch processing.
model	string	Yes	Embedding model ID, e.g. meridian-embed-3.
encoding_format	string	No	Format of the returned embedding. float (default) or base64.
dimensions	integer	No	Number of dimensions for the output embedding. Model default if omitted.

curl https://api.meridian.so/v1/embeddings \
  -H "Authorization: Bearer $MERIDIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meridian-embed-3",
    "input": "The quick brown fox jumps over the lazy dog."
  }'

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023, -0.0091, 0.0152, ...]
    }
  ],
  "model": "meridian-embed-3",
  "usage": {
    "prompt_tokens": 9,
    "total_tokens": 9
  }
}

Image generation

POST

/v1/images/generations

Generates images from a text prompt.

Name	Type	Required	Description
prompt	string	Yes	Text description of the desired image.
n	integer	No	Number of images to generate. Default 1.
size	string	No	Image size. One of 1024x1024, 1792x1024, 1024x1792. Default 1024x1024.
quality	string	No	Image quality. standard or hd. Default standard.

curl https://api.meridian.so/v1/images/generations \
  -H "Authorization: Bearer $MERIDIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A serene mountain lake at sunrise, digital art",
    "n": 1,
    "size": "1024x1024"
  }'

{
  "created": 1717000000,
  "data": [
    {
      "url": "https://cdn.meridian.so/gen/img_abc123.png",
      "revised_prompt": "A serene mountain lake at sunrise, digital art"
    }
  ]
}

Audio transcription

POST

/v1/audio/transcriptions

Transcribes audio into text. Submit audio as multipart/form-data.

Name	Type	Required	Description
file	file	Yes	Audio file. Supported formats: mp3, mp4, mpeg, mpga, m4a, wav, webm.
model	string	Yes	Model ID, e.g. meridian-whisper-1.
language	string	No	ISO-639-1 language code. Improves accuracy and latency when provided.

curl https://api.meridian.so/v1/audio/transcriptions \
  -H "Authorization: Bearer $MERIDIAN_API_KEY" \
  -F file="@audio.mp3" \
  -F model="meridian-whisper-1"

{
  "text": "Good morning. The time is 9:15 AM and the temperature is 72 degrees."
}

List models

GET

/v1/models

Lists all available models with ownership and capability metadata. No request body or query parameters required.

curl https://api.meridian.so/v1/models \
  -H "Authorization: Bearer $MERIDIAN_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "meridian-1",
      "object": "model",
      "created": 1717000000,
      "owned_by": "meridian"
    },
    {
      "id": "meridian-1-turbo",
      "object": "model",
      "created": 1717000000,
      "owned_by": "meridian"
    }
  ]
}

Usage

GET

/v1/usage

Retrieve token usage and cost metrics for your account.

Name	Type	Required	Description
from	string (ISO 8601)	Yes	Start of the query window, e.g. 2025-01-01T00:00:00Z.
to	string (ISO 8601)	Yes	End of the query window, e.g. 2025-01-31T23:59:59Z.
granularity	string	No	Bucket size. hour, day, or month. Default day.

curl "https://api.meridian.so/v1/usage?from=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z&granularity=day" \
  -H "Authorization: Bearer $MERIDIAN_API_KEY"

{
  "object": "list",
  "data": [
    {
      "timestamp": "2025-01-01T00:00:00Z",
      "prompt_tokens": 12000,
      "completion_tokens": 8400,
      "total_tokens": 20400,
      "cost_usd": 0.41
    }
  ],
  "aggregate": {
    "total_tokens": 612000,
    "total_cost_usd": 12.24
  }
}

Rate limits

ALL

Headers on every response

Rate limit status is returned in response headers on every API call. Limits vary by plan and endpoint.

x-ratelimit-limit-requests — max requests per window

x-ratelimit-remaining-requests — remaining in current window

x-ratelimit-reset-requests — window reset time (Unix seconds)

x-ratelimit-limit-tokens — max tokens per window

x-ratelimit-remaining-tokens — remaining tokens in current window

x-ratelimit-reset-tokens — token window reset time (Unix seconds)

When a limit is exceeded the API returns 429 Too Many Requests with a JSON body containing the retry-after field in seconds.