API compatível com OpenAI do Ollama: acesso, preços, integração e guia de produção

API compatível com OpenAI do Ollama: acesso, preços, integração e guia de produção

A API compatível com OpenAI do Ollama permite que uma aplicação mantenha a estrutura familiar do SDK da OpenAI enquanto envia solicitações para um servidor Ollama local ou diretamente para o Ollama Cloud. Isso é útil, mas não é uma promessa de paridade de recursos um a um: o Ollama documenta suporte para um subconjunto da API da OpenAI, e alguns recursos dependem do endpoint e do modelo escolhidos.

Este guia mostra como acessar essa interface, configurá-la em uma aplicação Python ou JavaScript existente, entender os custos de nuvem em comparação com os locais e estabelecer limites reais de produção ao seu redor.

Resposta rápida: use http://localhost:11434/v1/ para um servidor Ollama local e uma chave de API de espaço reservado exigida pelo SDK, mas ignorada pelo Ollama. Use https://ollama.com/v1 mais OLLAMA_API_KEY para acesso direto à nuvem. Valide o endpoint e o modelo exatos antes de depender de streaming, visão, ferramentas, saída estruturada ou do comportamento da API Responses.

O que “compatível com OpenAI” significa para o Ollama?

Trata-se de uma superfície de integração para clientes OpenAI, não de uma API hospedada pela OpenAI. Ela permite apontar clientes compatíveis para URLs-base do Ollama e usar rotas compatíveis, como conclusões de chat, embeddings, descoberta de modelos e solicitações Responses sem estado.

A referência de compatibilidade do Ollama é a fonte de verdade para o subconjunto compatível. Em particular:

• /v1/chat/completions oferece suporte a recursos como streaming, modo JSON, visão, ferramentas, saídas reproduzíveis, logprobs e controles que se aplicam apenas a modelos compatíveis.
• /v1/embeddings oferece suporte a entradas de string e de array.
• /v1/models e /v1/models/{model} oferecem suporte à descoberta de modelos, mas alguns campos retornados têm significados específicos do Ollama.
• POST /v1/responses está disponível, mas é sem estado: não dependa de previous_response_id nem de conversation.

Consulte a referência de compatibilidade com OpenAI do Ollama atual antes de habilitar um recurso em produção. “Compatível” deve ser tratado como um motivo para reutilizar seu cliente e o formato das solicitações — não como um motivo para pular os testes de recursos.

Acesse a API compatível com OpenAI do Ollama: local versus nuvem

A escolha de implementação mais simples é se a inferência é executada na sua própria máquina ou alcança o endpoint de nuvem do Ollama.

Essa divisão está documentada na introdução à API e no guia de autenticação do Ollama. Chamadas diretas à nuvem exigem uma chave de API. Chamadas locais não.

Configuração local

Instale o Ollama e, em seguida, baixe o modelo que pretende usar. A documentação do Ollama mostra o padrão geral:

ollama pull gpt-oss:20b
ollama serve

Agora valide que o endpoint local pode listar modelos:

curl http://localhost:11434/v1/models

Se essa conexão falhar, resolva o problema do servidor local antes de alterar o código da aplicação. É muito mais fácil depurar uma migração de cliente quando a URL-base da API e o inventário de modelos já funcionam de forma independente.

Configuração de nuvem direta

Para uso direto da nuvem, crie uma chave de API na sua conta Ollama e coloque-a em uma variável de ambiente:

export OLLAMA_API_KEY="replace-with-your-key"

A URL-base da nuvem é https://ollama.com/v1. O Ollama documenta que sua API hospedada usa Authorization: Bearer; não coloque uma chave de longa duração em código de navegador, em um repositório ou em um arquivo de configuração do lado do cliente.

Integre a API compatível com OpenAI do Ollama ao SDK da OpenAI

O ponto de migração é a configuração do cliente. Mantenha as mensagens da aplicação e o tratamento de erros atrás da sua própria interface e, então, troque apenas a URL-base, a chave e a configuração do modelo.

Python: servidor local

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1/",
    api_key="ollama",  # required by the SDK; ignored by the local server
)

response = client.chat.completions.create(
    model="gpt-oss:20b",
    messages=[
        {"role": "user", "content": "Summarize the production risks of exposing a local API."}
    ],
)

print(response.choices[0].message.content)

O endpoint local não autentica solicitações. A chave de preenchimento existe apenas porque o cliente OpenAI espera um valor; ela não protege o servidor local.

Python: nuvem direta

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://ollama.com/v1",
    api_key=os.environ["OLLAMA_API_KEY"],
)

response = client.chat.completions.create(
    model="gemma4:31b",
    messages=[
        {"role": "user", "content": "Give one sentence on safe API key storage."}
    ],
)

print(response.choices[0].message.content)

A estrutura do código é deliberadamente semelhante. A diferença operacional não é: chamadas diretas à nuvem dependem de uma chave de API e do modelo de nuvem escolhido; chamadas locais dependem de um modelo baixado e dos recursos disponíveis no host.

JavaScript: mantenha o endpoint configurável

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.OLLAMA_BASE_URL ?? "http://localhost:11434/v1/",
  apiKey: process.env.OLLAMA_API_KEY ?? "ollama",
});

const completion = await client.chat.completions.create({
  model: process.env.OLLAMA_MODEL ?? "gpt-oss:20b",
  messages: [{ role: "user", content: "Return a concise health-check message." }],
});

console.log(completion.choices[0].message.content);

Defina variáveis de ambiente para cada implantação:

# Local
OLLAMA_BASE_URL=http://localhost:11434/v1/
OLLAMA_API_KEY=ollama
OLLAMA_MODEL=gpt-oss:20b

# Direct cloud
OLLAMA_BASE_URL=https://ollama.com/v1
OLLAMA_API_KEY=replace-with-your-key
OLLAMA_MODEL=gemma4:31b

Essa configuração torna explícita e revisável uma alteração posterior de rota ou modelo. Ela também evita que uma URL base específica do ambiente se torne um comportamento oculto da aplicação.

Matriz de compatibilidade: o que testar antes do lançamento

A API compatível com OpenAI do Ollama é mais útil quando você transforma a compatibilidade em um plano de testes, e não em uma suposição.

Dois detalhes frequentemente surpreendem as equipes:

1. O estado pertence à sua aplicação. Seu aplicativo deve armazenar as mensagens ou o estado da conversa de que precisa, em vez de esperar um comportamento de Responses com estado do Ollama.
2. Um nome de modelo não é uma garantia de capacidade. Uma solicitação pode usar um endpoint compatível e ainda assim não fornecer a qualidade ou o comportamento de ferramentas de que um fluxo de trabalho precisa. Teste o modelo, o tamanho do prompt, os limites de saída e as ferramentas em conjunto.

Se uma integração existente codifica um nome de modelo OpenAI padrão, o Ollama documenta ollama cp como uma forma de criar um alias temporário de modelo local. Use isso apenas como uma camada de compatibilidade deliberada, documente o alias e remova-o quando sua configuração estiver explícita.

Preços do Ollama: TCO local versus tarifas de tokens na nuvem

Os preços da API compatível com OpenAI do Ollama dependem da rota.

A inferência local não é uma cobrança por token — mas não é gratuita

Executar um modelo local não gera uma fatura da nuvem do Ollama por token. No entanto, isso cria um perfil de custos operacionais:

• Capacidade de GPU ou CPU, RAM/VRAM, armazenamento e depreciação das máquinas
• Eletricidade e refrigeração
• Tempo de download do modelo e armazenamento de imagens
• Planejamento de capacidade, monitoramento, aplicação de patches e resposta a incidentes
• O custo de oportunidade de manter um modelo pronto para solicitações de baixa latência

Para um único desenvolvedor, isso pode ser uma excelente troca. Para um produto com tráfego em picos ou vários modelos, calcule a utilização do hardware e o trabalho de confiabilidade juntamente com o custo bruto de inferência.

Os preços diretos da nuvem são publicados por milhão de tokens

A página de preços em tempo real do Ollama lista as tarifas de nuvem por um milhão de tokens, incluindo preços separados para entrada, entrada em cache e saída. Os exemplos abaixo foram verificados em 22 de outubro de 2026; use a lista de preços em tempo real para decisões de aquisição e implantação.

A página de preços do Ollama também descreve preços fora do horário de pico para itens elegíveis. Não crie um orçamento com base apenas no rótulo de um modelo: use a linha de preço aplicável à rota, ao modelo e ao horário reais.

Uma estimativa mensal prática é:

monthly_cloud_cost =
  (input_tokens / 1,000,000 × input_rate)
+ (cached_input_tokens / 1,000,000 × cached_input_rate)
+ (output_tokens / 1,000,000 × output_rate)

Por exemplo, com as tarifas publicadas acima para gpt-oss:20b, 1 milhão de tokens de entrada sem cache mais 250.000 tokens de saída resultam em uma estimativa de $0.145 antes de quaisquer alterações de preços ou créditos específicos da conta. Use telemetria de tokens observada, e não uma estimativa do tamanho do chat, para uma previsão de produção.

Guia de produção: proteja o servidor local antes de expô-lo

A regra de produção mais importante para a API compatível com OpenAI do Ollama é simples: um servidor Ollama local não tem autenticação por padrão.

O Ollama é associado a 127.0.0.1:11434 por padrão. A documentação mostra que OLLAMA_HOST pode alterar o endereço de associação e que um proxy como o Nginx pode encaminhar tráfego ao servidor. Essas são opções de implementação — não de autenticação. Se você levar o serviço além do localhost, implemente controles deliberados ao seu redor.

Checklist de produção

1. Mantenha a associação de loopback padrão, a menos que você tenha um caminho de acesso definido. Não exponha a porta 11434 diretamente à internet.
2. Coloque TLS e autenticação na borda. Use um proxy reverso, rede privada, identidade de serviço e autorização por cliente adequados ao seu ambiente. Uma chave fictícia do SDK da OpenAI não é um controle de acesso.
3. Permita origens de navegador de forma restrita. O Ollama documenta OLLAMA_ORIGINS para origens adicionais permitidas. Adicione apenas as origens exatas do aplicativo web ou da extensão que precisam de acesso; não transforme isso em uma liberação geral de acesso entre origens.
4. Use uma lista de modelos permitidos. Trate o model solicitado como uma entrada que você valida. Chamadores de produção não devem poder baixar modelos arbitrários nem selecionar modelos não revisados.
5. Defina uma política de fila e lide com sobrecargas. O Ollama documenta que um servidor sobrecarregado pode retornar HTTP 503 e expõe OLLAMA_MAX_QUEUE. Use novas tentativas limitadas com recuo exponencial e jitter; em seguida, apresente uma falha controlada ao chamador.
6. Planeje a capacidade de VRAM e a simultaneidade em conjunto. OLLAMA_NUM_PARALLEL aumenta o paralelismo por modelo, mas os requisitos de memória crescem com ele. OLLAMA_MAX_LOADED_MODELS e OLLAMA_KEEP_ALIVE determinam com que agressividade os modelos ocupam memória.
7. Instrumente os caminhos que importam. Acompanhe latência, tempo de fila, HTTP 503, inventário de modelos ativos, tamanho da solicitação, desconexões de stream, erros de chamadas de ferramentas e pressão de memória de GPU/CPU. ollama ps ajuda a verificar onde os modelos carregados estão em execução.
8. Teste reinicializações e partidas a frio. Um modelo local pode precisar de tempo de carregamento após a implantação ou remoção da memória. Execute testes de carga, reversão e tempo limite antes que a API dê suporte a um fluxo de trabalho voltado ao cliente.
9. Mantenha segredos fora dos clientes. Para o modo de nuvem, armazene OLLAMA_API_KEY em um gerenciador de segredos do lado do servidor ou em um ambiente de execução protegido — não em um bundle de frontend.
10. Fixe a suíte de aceitação, não apenas a versão da dependência. Execute novamente testes de chat, streaming, ferramentas, JSON, visão e estado de resposta sempre que atualizar o Ollama, alterar um modelo ou modificar a camada de roteamento.

As perguntas frequentes do Ollama documentam o endereço de associação, a configuração de CORS, o comportamento da fila, as configurações de simultaneidade e os controles local/nuvem por trás dessas recomendações.

Um caminho de implantação mais seguro

Use esta sequência para um aplicativo que começa localmente e pode usar modelos hospedados mais tarde:

1. Teste o endpoint local. Baixe um modelo, liste os modelos e envie uma conclusão de chat sem streaming.
2. Estabilize a configuração do cliente OpenAI. Use variáveis de ambiente para a URL base, a chave de API e o modelo — não literais espalhados pela base de código.
3. Crie uma suíte de compatibilidade. Inclua saída JSON, streaming, cada esquema de ferramenta, entradas de visão quando relevante, comportamento de timeout e solicitações malformadas.
4. Faça testes de carga no host. Registre a latência, a profundidade da fila, a VRAM/RAM e o ponto em que os erros 503 começam.
5. Adicione uma camada de borda autenticada antes do acesso remoto. Mantenha o Ollama privado atrás do serviço de aplicação ou de um proxy confiável.
6. Avalie o modo de nuvem separadamente. Use uma chave de nuvem dedicada, modelos em lista de permissão, alertas de orçamento e casos de teste que cubram as limitações específicas de Responses na nuvem.
7. Desacople a escolha do provedor da lógica de negócios. Se um produto precisar comparar modelos hospedados ou adicionar uma rota de fallback, mantenha o contrato do cliente OpenAI atrás de um pequeno adaptador.

Para a última etapa, uma checklist de migração para gateway de API compatível com OpenAI pode ajudar você a separar a integração do cliente da seleção do provedor de modelos. Se quiser avaliar vários provedores hospedados sem adicionar um novo padrão de cliente para cada um, consulte o guia de início rápido da API Flatkey e o guia para decidir quando um gateway de API de IA é útil.

Erros comuns com a API compatível com OpenAI do Ollama

Tratar um servidor localhost como um serviço protegido

Uma solicitação local pode funcionar porque o processo está na mesma máquina, e não porque o acesso está autenticado. No momento em que um endereço de bind, túnel, proxy ou porta de contêiner mudar, revise a identidade, a política de rede, o TLS e o registro de auditoria.

Pressupor paridade de recursos com a OpenAI

O Ollama oferece suporte explícito a um subconjunto da API da OpenAI. Inclua uma verificação de capacidades na CI e teste a semântica — não apenas uma resposta 200. Uma definição de ferramenta que é analisada localmente pode se comportar de forma diferente após a troca de modelo.

Usar os rótulos de preço da nuvem como orçamento

As tarifas de entrada, entrada em cache e saída podem diferir substancialmente. Registre os campos de tokens, calcule o custo efetivo por tarefa concluída com sucesso e verifique novamente a página de preços antes de assumir um orçamento fixo.

Aumentar o paralelismo sem um modelo de memória

Mais solicitações paralelas podem aumentar os requisitos de contexto e memória. Observe a pressão real no host com prompts representativos antes de alterar as configurações de simultaneidade.

Fornecer uma chave de nuvem ao navegador

Uma chamada direta do navegador para a nuvem torna a rotação de chaves, o controle de orçamento e a prevenção de abuso muito mais difíceis. Mantenha a chave de nuvem em um backend confiável e exponha apenas a operação de que sua aplicação precisa.

Perguntas frequentes

A API compatível com OpenAI do Ollama é igual à API da OpenAI?

Não. A camada de compatibilidade do Ollama oferece suporte a um subconjunto documentado da API da OpenAI para que clientes compatíveis possam se conectar ao Ollama. Confirme endpoints e campos individuais na referência de compatibilidade do Ollama antes de considerar um recurso como portável.

A API local do Ollama precisa de uma chave de API?

Não. O Ollama informa que a API local não exige autenticação. O valor api_key="ollama" nos exemplos de SDK é um requisito não vazio do cliente, e não uma credencial. Mantenha o servidor local em localhost ou adicione controles reais antes da exposição remota.

O Ollama Cloud precisa de uma chave de API?

Sim. O acesso direto à nuvem em https://ollama.com/v1 exige uma chave de API transmitida como token Bearer. Armazene-a no lado do servidor.

Posso usar /v1/responses?

Sim, para solicitações Responses sem estado. Não dependa de previous_response_id nem de conversation. A documentação da nuvem também destaca limitações relacionadas à pesquisa web integrada e à reprodução de chamadas de ferramentas personalizadas/freeform.

A API compatível com OpenAI do Ollama é gratuita?

A inferência local não tem uma cobrança do Ollama Cloud por token, mas você ainda paga pelo hardware e pelas operações que executa. A inferência direta na nuvem usa preços publicados por token e créditos de conta.

Quando devo usar um gateway em vez disso?

Use o Ollama diretamente quando a rota local/em nuvem atender às necessidades de modelo, privacidade e operação da carga de trabalho. Considere um gateway quando seu produto precisar de uma integração consistente entre vários provedores hospedados, de um fluxo de trabalho de avaliação de modelos ou de um caminho de fallback separado. Comece com uma decisão clara sobre uma API de IA unificada e, em seguida, preserve o mesmo adaptador de cliente no nível da aplicação.

Conclusão

A API compatível com OpenAI do Ollama oferece aos desenvolvedores uma forma prática de reutilizar um SDK da OpenAI com modelos locais ou servidos na nuvem. A implementação segura não é apenas uma alteração na URL base: é uma matriz de capacidades testada, um modelo de custos claro entre local e nuvem, um limite de implantação local privado e um plano testado sob carga para filas e memória dos modelos.

Comece localmente se precisar de controle e puder operar o hardware. Use a nuvem direta quando quiser inferência hospedada por meio da mesma interface de cliente. Em ambos os casos, mantenha a escolha do endpoint configurável e faça com que cada recurso compatível justifique seu lugar no seu conjunto de testes de produção.