OpenAI-compatible API guide — from Ollama's local endpoint to hosted frontier models

"OpenAI-compatible" means an API speaks the same wire format as OpenAI's /v1/chat/completions — so any OpenAI SDK or tool works against it by changing only the base_url. Ollama exposes an OpenAI-compatible endpoint for models running locally on your machine. Kunavo exposes one for hosted frontier models — Claude, Gemini, GPT plus image, video and audio models — behind one bearer token. This guide shows the pattern and how to move between them without rewriting code.

What "OpenAI-compatible" means

The OpenAI Chat Completions format became the de-facto standard: a messages array in, a choices[].message out, Server-Sent Events for streaming, tools for function calling. Any endpoint that honours that contract is "OpenAI-compatible," and the official openai SDKs (Python, Node, and every community port) point at it by setting base_url.

The Ollama pattern (local)

Ollama runs open models locally and serves them at http://localhost:11434/v1:

from openai import OpenAI

# Ollama exposes an OpenAI-compatible endpoint on localhost
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

resp = client.chat.completions.create(
    model="llama3.1",
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)
print(resp.choices[0].message.content)

Same code, hosted frontier models (Kunavo)

Point the exact same SDK at Kunavo and pick a frontier model. Only base_url, api_key and model change — the call is byte-for-byte the same:

import os
from openai import OpenAI

# Same SDK, same call shape — only base_url, api_key and model change
client = OpenAI(
    base_url="https://api.kunavo.com/v1",
    api_key=os.environ["KUNAVO_API_KEY"],
)

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",  # or gemini-2-5-flash, gpt-5-5, gemini-2-5-pro...
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)
print(resp.choices[0].message.content)

Get a key at /app/keys; the quickstart has Node and curl forms.

Local vs hosted — when to use which

A common setup: Ollama on localhost for offline dev, Kunavo for hosted quality in production — one env var swaps them. For the field-by-field contract both ends implement — parameters, streaming deltas, tool_calls, the usage object and the parity table against Ollama's v1 surface — see the /v1/chat/completions reference and its Ollama OpenAI-compatibility section.

Discover models at runtime

Like Ollama's /api/tags, Kunavo exposes an OpenAI-shaped catalog. Resolve slugs at runtime instead of hardcoding:

# Discover every enabled model (OpenAI-shaped, like Ollama's /api/tags)
curl https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer $KUNAVO_API_KEY"

Beyond chat

The same key reaches image (/v1/images/generations), video (/v1/video/generations) and audio endpoints — all OpenAI-shaped. See the multimodal AI guide and the OpenRouter comparison for how Kunavo differs from other gateways.

One surface goes beyond the usual definition of “compatible” and is worth knowing about: POST /v1/responses. Codex CLI accepts a custom provider only over the Responses API, which is why most OpenAI-compatible gateways cannot drive it at all — what Codex costs per token works that through with a config block that runs. To price a GPT workload including cached input, the OpenAI API pricing calculator takes your own token counts.

FAQ