Create your first OpenRouter API request with a simple example. Use when learning OpenRouter or testing your setup. Trigger with phrases like 'openrouter hello world', 'openrouter first request', 'openrouter quickstart', 'test openrouter'.
npxskills add jeremylongshore/claude-code-plugins-plus-skills--skill openrouter-hello-worldLoading…
Send a minimal chat completion request through OpenRouter, understand the response format, try different models, and verify the full round-trip works. All requests go to the single endpoint POST https://openrouter.ai/api/v1/chat/completions.
sk-or-v1-...) exported as OPENROUTER_API_KEY — see the openrouter-install-auth skill for setupcurl and jq for the command-line request, or Python 3.8+ / Node.js 18+ with the OpenAI SDK (pip install openai / npm install openai):free models)export OPENROUTER_API_KEY="sk-or-v1-...".choices[0].message.content back.id, model, usage, finish_reason).GET /api/v1/generation?id=gen-... per Check Generation Cost to verify cost tracking on the request you just sent.curl -s https://openrouter.ai/api/v1/chat/completions \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "google/gemma-2-9b-it:free",
"messages": [{"role": "user", "content": "Say hello in three languages"}],
"max_tokens": 100
}' | jq .
{
"id": "gen-abc123xyz",
"model": "google/gemma-2-9b-it:free",
"object": "chat.completion",
"created": 1711234567,
"choices": [{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! Bonjour! Hola!"
},
"finish_reason": "stop"
}],
"usage": {
"prompt_tokens": 12,
"completion_tokens": 8,
"total_tokens": 20
}
}
Key fields:
id (gen-...) -- use this to query generation stats via GET /api/v1/generation?id=gen-abc123xyzmodel -- confirms which model actually served the requestusage -- token counts for cost calculationfinish_reason -- stop (complete), length (hit max_tokens), tool_calls (function call)from openai import OpenAI
import os
client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=os.environ["OPENROUTER_API_KEY"],
default_headers={"HTTP-Referer": "https://your-app.com", "X-Title": "My App"},
)
# Basic completion
response = client.chat.completions.create(
model="google/gemma-2-9b-it:free",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "What is OpenRouter in one sentence?"},
],
max_tokens=100,
)
print(response.choices[0].message.content)
print(f"Model: {response.model}")
print(f"Tokens: {response.usage.prompt_tokens} prompt + {response.usage.completion_tokens} completion")
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://openrouter.ai/api/v1",
apiKey: process.env.OPENROUTER_API_KEY,
defaultHeaders: { "HTTP-Referer": "https://your-app.com", "X-Title": "My App" },
});
const res = await client.chat.completions.create({
model: "google/gemma-2-9b-it:free",
messages: [{ role: "user", content: "What is OpenRouter in one sentence?" }],
max_tokens: 100,
});
console.log(res.choices[0].message.content);
console.log(`Model: ${res.model} | Tokens: ${res.usage?.total_tokens}`);
# Swap model ID to access any of 400+ models
models_to_try = [
"google/gemma-2-9b-it:free", # Free tier
"meta-llama/llama-3.1-8b-instruct", # Open-source
"anthropic/claude-3.5-sonnet", # Anthropic
"openai/gpt-4o", # OpenAI
"openrouter/auto", # Auto-router (picks best model)
]
for model_id in models_to_try:
try:
r = client.chat.completions.create(
model=model_id,
messages=[{"role": "user", "content": "Hi"}],
max_tokens=10,
)
print(f"{model_id}: {r.choices[0].message.content}")
except Exception as e:
print(f"{model_id}: {e}")
# After a request, query the generation endpoint for cost details
curl -s "https://openrouter.ai/api/v1/generation?id=gen-abc123xyz" \
-H "Authorization: Bearer $OPENROUTER_API_KEY" | jq '{
model: .data.model,
tokens_prompt: .data.tokens_prompt,
tokens_completion: .data.tokens_completion,
total_cost: .data.total_cost
}'
A successful round-trip produces:
choices[0].message.content holding the model's reply, a gen-... request id, the model that actually served the request, and usage token countstokens_prompt, tokens_completion, and total_cost for the requestEnd-to-end run with the minimal cURL request:
$ curl -s https://openrouter.ai/api/v1/chat/completions ... | jq .choices[0].message.content
"Hello! Bonjour! Hola!"
The Python and TypeScript sections above are the same request in SDK form; expected console output:
OpenRouter is a unified API gateway that routes requests to 400+ LLMs.
Model: google/gemma-2-9b-it:free
Tokens: 21 prompt + 17 completion
More worked examples (cURL with full expected response, SDK variants): references/examples.md.
| HTTP | Cause | Fix |
|---|---|---|
| 401 | Invalid or missing API key | Verify sk-or-v1-... key is exported |
| 402 | Insufficient credits for paid model | Add credits or use a :free model |
| 404 | Wrong base URL or invalid model ID | Use https://openrouter.ai/api/v1; check model ID at /api/v1/models |
| 400 | Malformed JSON or missing messages | Ensure messages array has objects with role and content |
max_tokens to prevent unbounded completionsHTTP-Referer and X-Title headers for usage attribution in dashboards/api/v1/generation?id= for async cost auditing
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).