OpenAI Compatibility

Infravelle exposes an OpenAI-compatible API. If you already use the OpenAI SDK, change your client initialization to point at Infravelle and every call works the same way.

Update client initialization

Change the client initialization to point at Infravelle:

Python

# With OpenAI SDK
from openai import OpenAI
client = OpenAI(api_key="sk-...")

# With Infravelle — just change the init
import os
from openai import OpenAI
client = OpenAI(
    api_key=os.environ["INFRAVELLE_API_KEY"],
    base_url="https://api.infravelle.com/v1"
)

# Everything else stays the same
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)

TypeScript

// With OpenAI SDK
import OpenAI from "openai";
const client = new OpenAI({ apiKey: "sk-..." });

// With Infravelle — just change the init
import OpenAI from "openai";
const client = new OpenAI({
    apiKey: process.env.INFRAVELLE_API_KEY,
    baseURL: "https://api.infravelle.com/v1",
});

// Everything else stays the same
const response = await client.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello!" }],
});

Check compatibility

Standard OpenAI API features work through Infravelle, including chat completions, the Response API, streaming, tool calling, structured output (json_schema), error classes, async clients, and the models list endpoint. Some features have special handling:

Feature	Behavior
Response API	Preview. See Response API overview and API reference.
Legacy `functions`/`function_call`	Infravelle auto-converts to `tools`/`tool_choice`
Structured output (`json_object`)	Model-dependent. See Structured output.

Use additional features

Infravelle adds capabilities on top of the OpenAI-compatible interface:

Routing options: Optimize for cost, latency, or throughput across providers.
Cost optimization: Infravelle computes the expected cost of each request at every available provider and routes to the cheapest one.
Prompt caching: Infravelle optimizes prompt caching automatically, reducing cost and latency on repeated requests.
Budget management: Set spending limits per workspace, API key, or BYOK provider. See Error codes for the budget_exhausted code.
Response headers: Every response includes request_id, rate limit headers, and credit usage. See Python SDK or TypeScript SDK.

Use OpenAI SDK directly

You can use the OpenAI SDK with a base_url override instead of the Infravelle package:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["INFRAVELLE_API_KEY"],
    base_url="https://api.infravelle.com/v1"
)

response = client.chat.completions.create(
    model="claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": "Hello from Claude via Infravelle!"}]
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.INFRAVELLE_API_KEY,
    baseURL: "https://api.infravelle.com/v1",
});

const response = await client.chat.completions.create({
    model: "claude-sonnet-4-20250514",
    messages: [{ role: "user", content: "Hello from Claude via Infravelle!" }],
});
console.log(response.choices[0].message.content);

This gives you access to models from multiple providers (Anthropic, Google, Meta, and others) through the OpenAI client. For typed routing metadata and error mapping, use the Infravelle SDK (Python, TypeScript) instead.

Map errors

If you use the OpenAI SDK directly, Infravelle errors arrive as generic openai.APIStatusError. You can convert them to typed Infravelle errors with map_openai_error() to branch on specific error codes like budget_exhausted or rate_limit_error:

import os
import openai
from infravelle import map_openai_error, RateLimitError, PermissionDeniedError

client = openai.OpenAI(
    api_key=os.environ["INFRAVELLE_API_KEY"],
    base_url="https://api.infravelle.com/v1"
)

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}]
    )
except openai.APIStatusError as e:
    infravelle_error = map_openai_error(e)
    if isinstance(infravelle_error, RateLimitError):
        # budget_exhausted is a 429 rate_limit_error; branch on .code if needed
        if infravelle_error.code == "budget_exhausted":
            print(f"Budget exhausted: {infravelle_error.message}")
        else:
            print(f"Rate limited. Retry after: {infravelle_error.retry_after_seconds}s")
    elif isinstance(infravelle_error, PermissionDeniedError):
        print(f"Permission denied (code={infravelle_error.code}): {infravelle_error.message}")
    else:
        raise infravelle_error

map_openai_error() is Python-only. TypeScript users get typed errors automatically with the Infravelle SDK. See Error Handling for the full guide.

Access routing metadata

Every Infravelle response includes routing metadata: which provider handled the request, the cost, and latency. How you access it depends on which SDK you use.

With the Infravelle SDK

Both the Python and TypeScript SDKs expose routing_metadata as a typed property on each response:

from infravelle import Client

client = Client()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.routing_metadata.provider)

import { Client } from "@infravelle/sdk";

const client = new Client();
const response = await client.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello!" }],
});
console.log(response.routing_metadata?.provider);

See the Python SDK or TypeScript SDK for the full client reference.

With the OpenAI SDK

Infravelle includes routing metadata in every response. If you use the OpenAI SDK, the infravelle Python package provides two helpers to extract it with full typing: parse_routing_metadata() extracts routing metadata from an OpenAI SDK response:

from infravelle.route_types import parse_routing_metadata

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
metadata = parse_routing_metadata(response)
if metadata:
    print(f"Provider: {metadata.provider}")
    if metadata.cost:
        print(f"Cost: ${metadata.cost.usd}")

InfravelleAsyncOpenAI (experimental) is a drop-in AsyncOpenAI subclass that captures routing metadata on every response. Use it when a framework (OpenAI Agents SDK, LangChain, LlamaIndex) requires an AsyncOpenAI instance:

import asyncio
from infravelle import InfravelleAsyncOpenAI

async def main():
    client = InfravelleAsyncOpenAI()
    response = await client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}],
    )
    print(client.last_routing_metadata.provider)

asyncio.run(main())

Install with pip install "infravelle[openai-compat]". See InfravelleAsyncOpenAI for framework wiring details.

These helpers are Python-only. For typed routing metadata in TypeScript, use the Infravelle SDK or @infravelle/ai-sdk-provider with the Vercel AI SDK.

Resources

Python SDK — full native client reference
TypeScript SDK — TypeScript client reference
Error handling — complete error handling guide

Get Started

Guides

Response API

Frameworks

Integrations

Specifications

Platform

Changelog

OpenAI Compatibility

Update client initialization

Python

TypeScript

Check compatibility

Use additional features

Use OpenAI SDK directly

Map errors

Access routing metadata

With the Infravelle SDK

With the OpenAI SDK

Resources

​Update client initialization

​Python

​TypeScript

​Check compatibility

​Use additional features

​Use OpenAI SDK directly

​Map errors

​Access routing metadata

​With the Infravelle SDK

​With the OpenAI SDK

​Resources

Update client initialization

Python

TypeScript

Check compatibility

Use additional features

Use OpenAI SDK directly

Map errors

Access routing metadata

With the Infravelle SDK

With the OpenAI SDK

Resources