Guia de APIs compatíveis com OpenAI — do endpoint local do Ollama aos modelos de ponta hospedados

"Compatível com OpenAI" significa que uma API fala o mesmo formato de rede que /v1/chat/completions da OpenAI — portanto, qualquer SDK ou ferramenta da OpenAI funciona com ela alterando apenas base_url. O Ollama expõe um endpoint compatível com OpenAI para modelos executados localmente na sua máquina. O Kunavo expõe um para modelos de fronteira hospedados — Claude, GPT e modelos de imagem, vídeo e áudio — por trás de um único bearer token. Este guia mostra o padrão e como alternar entre eles sem reescrever o código.

O que significa “compatível com OpenAI”

O formato Chat Completions da OpenAI tornou-se o padrão de fato: um array messages na entrada, um choices[].message na saída, Server-Sent Events para streaming e tools para chamadas de função. Qualquer endpoint que respeite esse contrato é “compatível com OpenAI”, e os SDKs oficiais openai (Python, Node e todas as implementações da comunidade) apontam para ele definindo base_url.

O padrão do Ollama (local)

O Ollama executa modelos abertos localmente e os disponibiliza em 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)

Mesmo código, modelos de fronteira hospedados (Kunavo)

Aponte o mesmo SDK para o Kunavo e escolha um modelo de fronteira. Apenas base_url, api_key e model mudam — a chamada é exatamente igual byte a byte:

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-5",  # or claude-haiku-4-5, gpt-5-5, gpt-5-6-terra...
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)
print(resp.choices[0].message.content)

Obtenha uma chave em /app/keys; o quickstart inclui exemplos com Node e curl.

Local versus hospedado — quando usar cada um

Uma configuração comum: Ollama em localhost para desenvolvimento offline, Kunavo para qualidade hospedada em produção — uma variável de ambiente alterna entre eles. Para o contrato campo a campo implementado por ambas as pontas — parâmetros, deltas de streaming, tool_calls, o objeto usage e a tabela de paridade com a superfície v1 do Ollama — consulte a referência de /v1/chat/completions e sua seção de compatibilidade OpenAI do Ollama.

Descobrir modelos em tempo de execução

Assim como o /api/tags do Ollama, o Kunavo expõe um catálogo no formato da OpenAI. Resolva os slugs em tempo de execução em vez de fixá-los no código:

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

Além do chat

A mesma chave alcança endpoints de imagem (/v1/images/generations), vídeo (/v1/video/generations) e áudio — todos no formato da OpenAI. Consulte o guia de IA multimodal e a comparação com o OpenRouter para saber como o Kunavo difere de outros gateways.

Uma superfície vai além da definição usual de “compatível” e vale a pena conhecer: POST /v1/responses. A CLI do Codex aceita um provedor personalizado apenas pela Responses API, motivo pelo qual a maioria dos gateways compatíveis com OpenAI não consegue operá-la — quanto custa o Codex por token resolve isso com um bloco de configuração funcional. Para calcular o preço de um workload GPT incluindo entrada em cache, a calculadora de preços da API da OpenAI usa suas próprias contagens de tokens.

Perguntas frequentes