Models, API Keys, and Why We Use OpenRouter

If you have ever seen Claude Code, Codex, Aider, or Cursor edit code inside your terminal, it is natural to wonder: how does that magic work?.

The answer is: there is no magic. It is clean software engineering. A coding agent is simply a standard software application (written in TypeScript, Python, etc.) that talks to an AI model API over HTTP, provides a list of available tools, and executes the actions requested by the model against project files.

This is a conceptual reading stage. You do not need to run test commands for this step. Read through it carefully to build your mental model, and click Mark as read and continue when you are ready.

---

An LLM is not a conscious entity. It is a large mathematical prediction function trained on vast amounts of text and open-source code.

From a developer's perspective, an LLM is a web service over HTTP:

1. You send it a list of messages (a conversation formatted as JSON).
2. The model analyzes the input and computes the most coherent continuation.
3. It responds with either plain text or a structured request to invoke an external tool (Tool Call).

---

To ensure secure communication, a web service needs to authenticate requests.

An API Key is a private, secret token that acts as your application's digital passport:

• Authentication: Verifies that your account is valid and active.
• Billing and Quotas: Measures token consumption and applies rate or billing limits.
• Abuse Prevention: Enables rate-limiting against automated spam.

The Golden Rule of Security (Crucial for Juniors!)

[!CAUTION] NEVER commit an API Key to GitHub or hardcode it into source files. Automated bots continuously scan public repositories to steal credentials.

The professional approach:

1. Store keys in an environment variable or a local .env file.
2. Add .env to .gitignore so Git never tracks it.
3. Read it via process.env.OPENROUTER_API_KEY (Node/TypeScript) or os.environ["OPENROUTER_API_KEY"] (Python).

---

1. Navigate to OpenRouter.
2. Sign in with GitHub or Google.
3. Open your profile menu and select Keys (or visit openrouter.ai/keys).
4. Click Create Key.
5. Give it a descriptive label (e.g., my-coding-agent) and confirm.
6. Copy the key immediately (starts with sk-or-v1-...). For security reasons, it cannot be displayed again in full.
7. Save it securely in your local environment.

---

Imagine traveling internationally with dozens of appliances that each require different plug sockets. An adapter allows one device to connect anywhere.

A Model Router is the universal adapter for AI models:

The Problem with Single-Provider Lock-In

If you hardwire your agent directly to OpenAI:

• You rely exclusively on the OpenAI SDK and billing account.
• When Anthropic releases Claude 3.5 Sonnet and it outperforms existing models at coding, you have to create an Anthropic account, add another card, learn another SDK, and rewrite client code.
• If OpenAI experiences downtime, your agent halts completely.

The OpenRouter Advantage

OpenRouter acts as a unified gateway and switcher:

• One account and one API key: Access models from Anthropic (Claude), OpenAI (GPT-4o), DeepSeek (V3, R1), Meta (Llama 3), and Google (Gemini).
• Zero Vendor Lock-in: Changing the model behind your agent only requires updating a single string in configuration:
  • "anthropic/claude-3.5-sonnet"
  • "deepseek/deepseek-chat"
  • "openai/gpt-4o"
• Free tiers for learning: OpenRouter provides models with :free suffixes (such as meta-llama/llama-3.3-70b-instruct:free) for practice without cost.
• Automatic Fallbacks: If a provider suffers latency spikes or outages, OpenRouter can automatically route traffic to alternative providers.

---

You can communicate with OpenRouter in two ways:

Raw HTTP Requests (fetch or requests)

Perform a POST request to https://openrouter.ai/api/v1/chat/completions with an Authorization: Bearer <KEY> header and a JSON body.

Client SDKs

An SDK (Software Development Kit) is a library that wraps HTTP transport, handles JSON serialization, manages retries, and provides typed autocomplete in your editor.

Because OpenRouter adheres to the standard OpenAI Chat Completions specification, you can use the official openai client library simply by pointing its baseURL:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
});

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"]
)

---

Conversations consist of messages organized by four roles:

1. system: Persistent instructions establishing the agent's identity, capabilities, and constraints.
2. user: The developer prompt or task (e.g., "Fix the bug in math.py").
3. assistant: The AI model's response, containing thoughts or structured tool calls.
4. tool: The execution result or observation returned by our program after running the tool.

---

In the upcoming stages, you will construct each architectural piece:

1. Define tool schemas so models understand which actions they can request.
2. Build line-aware reading, writing, and surgical patching tools.
3. Design the tool dispatcher.
4. Wire everything together into an autonomous ReAct loop.