Cloud API

Ollama provides cloud capabilities including web search, web fetch, cloud models, and a hosted API. This guide covers all cloud features.

API Key Setup

Cloud features require an Ollama API key:

1. Create an account at https://ollama.com
2. Generate a key at https://ollama.com/settings/keys
3. Export the key:

export OLLAMA_API_KEY="your_api_key_here"

The client automatically uses OLLAMA_API_KEY when set.

Web Search

Search the web and get structured results:

{:ok, response} = Ollixir.web_search(client, query: "Elixir programming language")

for result <- response.results do
  IO.puts("#{result.title}")
  IO.puts("  #{result.url}")
  IO.puts("  #{result.content}")
end

Parameters

Response Structure

%Ollixir.Web.SearchResponse{
  results: [
    %Ollixir.Web.SearchResult{
      title: "Elixir Programming Language",
      url: "https://elixir-lang.org",
      content: "Elixir is a dynamic, functional language..."
    }
  ]
}

Web Fetch

Fetch and extract content from a URL:

{:ok, response} = Ollixir.web_fetch(client, url: "https://elixir-lang.org")

IO.puts("Title: #{response.title}")
IO.puts("Content: #{response.content}")
IO.inspect(response.links, label: "Links")

Response Structure

%Ollixir.Web.FetchResponse{
  title: "The Elixir programming language",
  content: "Elixir is a dynamic, functional language...",
  links: ["https://...", "https://..."]
}

Web Tools for Agents

Use web capabilities as tools in agentic workflows.

See examples/mcp/mcp_server.exs for an MCP stdio server that exposes web_search and web_fetch to MCP clients (Cursor, Cline, Open WebUI, etc.).

# Get predefined web tool definitions
tools = Ollixir.Web.Tools.all()

{:ok, response} = Ollixir.chat(client,
  model: "llama3.2",
  messages: [
    %{role: "user", content: "Search for the latest Elixir news"}
  ],
  tools: tools
)

# Handle tool calls
case get_in(response, ["message", "tool_calls"]) do
  [%{"function" => %{"name" => "web_search", "arguments" => args}}] ->
    query = args["query"]
    {:ok, results} = Ollixir.web_search(client, query: query)
    # Continue conversation with results...

  _ ->
    response["message"]["content"]
end

Cloud Models

Cloud models run on Ollama's infrastructure while using your local client.

Setup

1. Sign in (one-time):

ollama signin

2. Pull a cloud model:

ollama pull gpt-oss:120b-cloud

3. Use it like any local model:

client = Ollixir.init()

{:ok, response} = Ollixir.chat(client,
  model: "gpt-oss:120b-cloud",
  messages: [%{role: "user", content: "Explain quantum computing."}]
)

Available Cloud Models

See https://ollama.com/search?c=cloud for the latest list.

Cloud Models with Streaming

{:ok, stream} = Ollixir.chat(client,
  model: "gpt-oss:120b-cloud",
  messages: [%{role: "user", content: "Write a haiku about Elixir."}],
  stream: true
)

stream
|> Stream.each(fn chunk ->
  IO.write(get_in(chunk, ["message", "content"]) || "")
end)
|> Stream.run()

Hosted API (ollama.com)

Use the Ollama-hosted API directly instead of a local server:

# Point client at hosted API
client = Ollixir.init("https://ollama.com")

{:ok, response} = Ollixir.chat(client,
  model: "gpt-oss:120b",  # Note: no :cloud suffix for hosted API
  messages: [%{role: "user", content: "Hello!"}]
)

List Available Models

curl -H "Authorization: Bearer $OLLAMA_API_KEY" https://ollama.com/api/tags

Custom Headers

Override the default authorization:

client = Ollixir.init("https://ollama.com",
  headers: [{"authorization", "Bearer your_api_key_here"}]
)

Cloud vs Local Comparison

Error Handling

Missing API Key

case Ollixir.web_search(client, query: "test") do
  {:ok, response} ->
    response

  {:error, %Ollixir.ResponseError{status: 401}} ->
    IO.puts("Missing or invalid API key. Set OLLAMA_API_KEY.")

  {:error, %Ollixir.ResponseError{status: 403}} ->
    IO.puts("API key lacks permission for this operation.")

  {:error, error} ->
    IO.puts("Request failed: #{inspect(error)}")
end

Validate API Key

curl -H "Authorization: Bearer $OLLAMA_API_KEY" https://ollama.com/api/tags

Rate Limiting

Cloud APIs may have rate limits. Implement backoff:

defmodule CloudClient do
  def search_with_retry(client, query, retries \\ 3) do
    case Ollixir.web_search(client, query: query) do
      {:ok, response} ->
        {:ok, response}

      {:error, %Ollixir.ResponseError{status: 429}} when retries > 0 ->
        Process.sleep(1000 * (4 - retries))
        search_with_retry(client, query, retries - 1)

      {:error, error} ->
        {:error, error}
    end
  end
end

Environment Variables

Testing Cloud Features

Cloud tests are tagged and excluded by default:

# Run cloud tests after setting API key
mix test --include cloud_api

See Also

• Getting Started - Basic setup
• Tools Guide - Using web tools in agents
• Ollama Server Setup - Local and cloud setup