Meridian — One Key. Every Frontier Model.

Quick Start

Install Pydantic-AI and configure the model with Meridian's base URL.

pip install pydantic-ai

# Set your Meridian API key
export MERIDIAN_API_KEY="mk_live_..."

Override base_url

The key integration point: pass Meridian's gateway URL as base_url when constructing OpenAIModel. All chat completions, embeddings, and structured output calls flow through Meridian automatically.

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel
from pydantic import BaseModel
import os

class CityInfo(BaseModel):
    name: str
    population: int
    country: str

# Override base_url to route through Meridian
model = OpenAIModel(
    "gpt-4o",
    base_url="https://api.getnimbus.net/v1",
    api_key=os.environ["MERIDIAN_API_KEY"],
)

agent = Agent(model, result_type=CityInfo)

async def main():
    result = await agent.run("Tell me about Tokyo")
    print(result.data)
    # CityInfo(name='Tokyo', population=13960000,
    #          country='Japan')

Structured Output with Pydantic

Pydantic-AI uses Pydantic models for type-safe agent responses. Meridian proxies the underlying JSON schema mode transparently — no changes to your agent code.

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel
from pydantic import BaseModel
from typing import List

class Analysis(BaseModel):
    sentiment: str
    key_topics: List[str]
    confidence: float

model = OpenAIModel(
    "gpt-4o",
    base_url="https://api.getnimbus.net/v1",
    api_key=os.environ["MERIDIAN_API_KEY"],
)

analyzer = Agent(model, result_type=Analysis)

async def analyze(text: str) -> Analysis:
    result = await analyzer.run(
        f"Analyze sentiment: {text}"
    )
    return result.data

Streaming Responses

Meridian supports SSE streaming. Pydantic-AI's streaming API works without modification.

model = OpenAIModel(
    "gpt-4o",
    base_url="https://api.getnimbus.net/v1",
    api_key=os.environ["MERIDIAN_API_KEY"],
)

agent = Agent(model)

async def stream_example():
    async with agent.run_stream(
        "Write a haiku about coding"
    ) as stream:
        async for chunk in stream:
            print(chunk, end="", flush=True)

What Meridian Adds

Load Balancing

Distribute across multiple providers and models automatically.

Caching

Identical requests served from cache — lower latency, lower cost.

Logging & Observability

Every request logged with latency, tokens, and status.

Rate Limiting

Per-key rate limits protect your upstream quotas.

Fallback Chains

If primary model fails, Meridian retries with alternates.