Connect your AI

Open Historia supports five types of AI providers from a single settings panel. You can switch between them at any time:

• Gemini — Google's native API, with a generous free tier
• OpenAI — official GPT-4o, GPT-4.1, and o-series models
• Anthropic — Claude via the Messages API
• OpenAI Compatible — any API that speaks the /v1/chat/completions protocol (Ollama, LM Studio, llama.cpp, DeepSeek, Groq, Together.ai, OpenRouter, and more)
• Anthropic Compatible — any self-hosted proxy that speaks the Anthropic Messages API

For providers that don't send CORS headers from the browser (OpenAI, OpenAI Compatible, Anthropic Compatible), the game's Express server includes a /api/ai/relay endpoint that proxies requests securely. Gemini and Anthropic's native APIs support direct browser access and don't use the relay.

Gemini is the default provider and the easiest way to get started. Google offers a free tier on Google AI Studio that's more than enough for solo play.

Use OpenAI's official API for GPT-4o, GPT-4.1, or o-series reasoning models. Requires a paid API account with pre-loaded credits.

Use Anthropic's Claude via the Messages API. Known for nuanced writing and strong instruction-following — excellent for immersive diplomacy and rich event generation.

DeepSeek offers powerful models at very low cost. Their API is OpenAI-compatible, so it works through the "OpenAI Compatible" provider option.

Run models entirely on your own hardware. No API keys, no internet required after download, completely private. Use the OpenAI Compatible provider in settings.

Ollama is the simplest way to run LLMs locally. Works on Windows, macOS, and Linux.

LM Studio provides a graphical interface for downloading and running models. Great for Windows and macOS users who prefer a GUI.

llama.cpp is the most performant option for technical users. Runs GGUF-format models with minimal overhead.

Any cloud service that speaks the OpenAI chat completions protocol works through the OpenAI Compatible provider. Popular options:

For any of these, select OpenAI Compatible, paste the endpoint URL and your API key from that service, and set the model name. The relay handles CORS automatically.

For local models: smaller models respond faster and use less RAM. Larger models generate richer events and better strategic advice. For cloud models: Gemini's free tier is the best starting point; DeepSeek offers the best quality-per-dollar.

AI features are greyed out or unresponsive

Make sure your provider is configured correctly. For cloud APIs, verify your API key is valid and has credits. For local backends, check that the server is running and the endpoint URL matches. The game checks connectivity on load — if the backend isn't reachable, AI features won't activate.

API key not working

Double-check you've selected the correct provider in settings. A Gemini key won't work with the OpenAI provider, and vice versa. For OpenAI Compatible providers, ensure the endpoint URL includes the full base path (e.g., https://api.deepseek.com/v1, not just https://api.deepseek.com).

AI responses are slow

For local models: try a smaller model (3B parameters) or enable GPU acceleration. Ollama and LM Studio both support GPU offloading. For cloud APIs: slower models like GPT-4.1 or Claude Sonnet produce higher quality but take longer — try a faster model if latency is an issue. Groq is particularly fast for cloud inference.

CORS errors when using a remote backend

The game handles CORS automatically for OpenAI, OpenAI Compatible, and Anthropic Compatible providers via the relay endpoint. If you're seeing CORS errors, make sure you're using the correct provider type — Gemini and Anthropic work direct from the browser, everything else routes through /api/ai/relay.

DeepSeek / OpenRouter returns errors

These services use the OpenAI Compatible provider. Ensure the endpoint URL is correct and includes /v1. The model name must match exactly what the service expects (e.g., deepseek-chat for DeepSeek, or the full OpenRouter model slug like openai/gpt-4.1).