Tutorial da API do Ollama: chame /api/chat e /api/generate com curl

Ollama oferece uma API HTTP em segundo plano. O endereço padrão é http://localhost:11434. A CLI, o Open WebUI e várias bibliotecas se comunicam com os modelos por meio dessa API.

/api/chat: conversas

curl http://localhost:11434/api/chat -d '{
  "model": "qwen3:8b",
  "messages": [
    { "role": "system", "content": "Responda em português do Brasil." },
    { "role": "user", "content": "Por que o céu é azul? Explique em duas frases." }
  ],
  "stream": false
}'

O formato da resposta é o seguinte. Esta é uma resposta real a uma mensagem hi enviada para qwen3:0.6b (Ollama 0.40):

{
  "model": "qwen3:0.6b",
  "created_at": "2026-10-12T14:04:31.457272357Z",
  "message": {
    "role": "assistant",
    "content": "Hello! How can I assist you today? 😊 If you have any questions or need help, feel free to ask!",
    "thinking": "Okay, the user just said \"hi\" and I need to respond. ..."
  },
  "done": true,
  "done_reason": "stop",
  "total_duration": 10507470186,
  "load_duration": 26072287,
  "prompt_eval_count": 11,
  "prompt_eval_duration": 274566000,
  "eval_count": 112,
  "eval_duration": 10179865000
}

• message.content: a resposta do modelo.
• message.thinking: o processo de raciocínio de um modelo com capacidade de pensar. O Qwen3 pensa por padrão; para desativar esse recurso, adicione "think": false à solicitação.
• done_reason: stop indica que a resposta terminou normalmente; length indica que ela foi truncada ao atingir o limite de tamanho.
• Todas as unidades dos campos de tempo são nanossegundos (10507470186 ≈ 10,5 segundos). eval_count ÷ eval_duration indica quantos tokens são gerados por segundo.

Conversas com várias mensagens

A API não se lembra das conversas anteriores. Para continuar uma conversa, inclua todas as mensagens anteriores:

{
  "model": "qwen3:8b",
  "messages": [
    { "role": "user", "content": "Meu nome é João" },
    { "role": "assistant", "content": "Olá, João!" },
    { "role": "user", "content": "Qual é o meu nome?" }
  ]
}

role pode ser system, user, assistant ou tool (resultado de uma ferramenta; consulte Chamadas de ferramentas).

/api/generate: geração de texto em uma única chamada

Quando você não precisa da estrutura de conversa, pode usar /api/generate:

curl http://localhost:11434/api/generate -d '{
  "model": "qwen3:8b",
  "prompt": "Traduza esta frase para o inglês: Hoje o tempo está ótimo",
  "stream": false
}'

A resposta fica no campo response. Em geral, recomendamos priorizar /api/chat.

Respostas em streaming

O valor padrão de stream é true: o modelo retorna uma linha JSON cada vez que gera um pequeno trecho de texto. Na última linha, done é true.

curl http://localhost:11434/api/chat -d '{
  "model": "qwen3:8b",
  "messages": [{ "role": "user", "content": "Conte de 1 a 5" }]
}'

{"message":{"role":"assistant","content":"1"},"done":false}
{"message":{"role":"assistant","content":"、2"},"done":false}
...
{"message":{"role":"assistant","content":""},"done":true,"eval_count":12}

O streaming permite que as pessoas vejam a resposta imediatamente. Quase todas as interfaces de chat o utilizam.

options: ajuste os parâmetros

{
  "model": "qwen3:8b",
  "messages": [{ "role": "user", "content": "Escreva um slogan" }],
  "options": {
    "temperature": 0.9,
    "num_ctx": 8192,
    "num_predict": 100,
    "seed": 42
  },
  "stream": false
}

Os parâmetros disponíveis são os mesmos de PARAMETER no Modelfile. Consulte o tutorial do Modelfile.

keep_alive: mantenha o modelo carregado

{ "model": "qwen3:8b", "keep_alive": "1h" }

• Envie apenas model, sem mensagens, para carregar o modelo antecipadamente.
• "keep_alive": 0 descarrega o modelo imediatamente após a resposta.
• "keep_alive": -1 mantém o modelo carregado indefinidamente.

Entrada de imagem

Modelos de visão podem receber imagens codificadas em base64 nas mensagens:

IMG=$(base64 -w0 photo.jpg)   # no macOS, use base64 -i photo.jpg
curl http://localhost:11434/api/chat -d "{
  \"model\": \"gemma3\",
  \"messages\": [{
    \"role\": \"user\",
    \"content\": \"Descreva esta imagem\",
    \"images\": [\"$IMG\"]
  }],
  \"stream\": false
}"

Modo de pensamento

Modelos compatíveis com pensamento permitem controlá-lo com think:

{
  "model": "qwen3:8b",
  "messages": [{ "role": "user", "content": "Quantos r há em strawberry?" }],
  "think": true,
  "stream": false
}

O conteúdo do pensamento fica em message.thinking, e a resposta final, em message.content. think também pode ser false; alguns modelos aceitam níveis como "low", "medium" e "high".

Outros endpoints comuns

curl http://localhost:11434/api/tags
curl http://localhost:11434/api/show -d '{"model": "qwen3:8b"}'

API compatível com OpenAI

Ollama também oferece endpoints compatíveis com a API da OpenAI em /v1:

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3:8b",
    "messages": [{ "role": "user", "content": "Olá" }]
  }'

Para usar modelos locais com muitos programas e ferramentas criados originalmente para a OpenAI, basta mudar a URL base para http://localhost:11434/v1 e preencher a chave de API com qualquer valor. O exemplo em Python está na próxima seção.

Atualizado 12 de outubro de 2026