OpenRouter Research

Research current OpenRouter API specifications and Grok model availability for SFUMATO.

Context

All text LLM calls in SFUMATO go through app/tools/openrouter_tool.py:

• prompt_service.generate_prompt() — Grok, text-only input
• prompt_service.revise_prompt() — Grok, text-only input
• judge_service.evaluate() — Grok with vision (must analyze generated image)

ENV vars: OPENROUTER_API_KEY, OPENROUTER_BASE_URL=https://openrouter.ai/api/v1 Client: httpx.AsyncClient — OpenAI-compatible API

Read existing file first if it exists:

• app/tools/openrouter_tool.py
• config.py

Step 1: OpenRouter API Fundamentals

1. Fetch: https://openrouter.ai/docs/api-reference/overview
2. Fetch: https://openrouter.ai/docs/requests
3. Search: OpenRouter API python httpx async chat completions 2025

Capture:

• Base URL: https://openrouter.ai/api/v1
• Auth header format (Authorization: Bearer vs API-Key)
• Required request headers: HTTP-Referer, X-Title
• Chat completions endpoint: POST /v1/chat/completions
• Request body schema: model, messages, temperature, max_tokens, stream
• Response schema: choices[0].message.content
• Error response format and status codes (429, 402, 503, 500)

Step 2: Available Grok Models

1. Fetch: https://openrouter.ai/models?q=grok
2. Search: OpenRouter xAI Grok models list 2025
3. Fetch: https://openrouter.ai/x-ai if available

For each available Grok model, capture:

• Full model ID string (e.g. x-ai/grok-beta, x-ai/grok-vision-beta)
• Context window size (tokens)
• Supports image input (vision)? — critical for judge_service
• Cost per 1M input/output tokens

Determine the best model for each use case:

• prompt_gen: text-only, large context
• prompt_revise: text-only
• judge: MUST support vision/image input

Step 3: Image Input Format for Vision Models

Since judge_service.py sends a generated image to Grok for evaluation:

1. Search: OpenRouter vision model image input base64 format 2025
2. Fetch: https://openrouter.ai/docs/features/vision
3. Search: OpenAI-compatible vision API image_url content type format

Capture:

• Message content format for image:

  json
  1{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}

  vs URL-based image reference
• Max image size limits
• Supported formats (JPEG, PNG, WebP)
• Whether OpenRouter passes base64 to xAI directly or requires URL

Step 4: Error Handling and Retry Strategy

1. Search: OpenRouter API error handling retry 429 503 2025
2. Fetch: https://openrouter.ai/docs/api-reference/errors if available

Capture:

• 429 rate limit: retry-after header? fixed backoff interval?
• 402 payment/balance: raise immediately, no retry
• 503 model unavailable: retry with backoff
• Recommended timeout values for text calls vs vision calls
• Max retries pattern

Output Format

Section 1: openrouter_tool.py Implementation Blueprint

python
1# Async httpx client structure
2BASE_URL = "https://openrouter.ai/api/v1"
3
4# Required headers
5headers = {
6    "Authorization": f"Bearer {api_key}",
7    "HTTP-Referer": "...",
8    "X-Title": "SFUMATO",
9    "Content-Type": "application/json",
10}
11
12# chat_completion(model, messages, temperature, max_tokens) -> str
13# vision_completion(model, text_messages_plus_image_message) -> str
14# Retry pattern for 429/503 (show how many retries, backoff)
15# Error handling: which codes to retry vs raise immediately

Section 2: Model Selection Table

Section 3: Image Message Format

Exact Python dict structure to use when sending image to judge:

python
1{
2    "role": "user",
3    "content": [
4        {"type": "text", "text": "...judge prompt..."},
5        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}
6    ]
7}

Section 4: Recommended Constants for config.py

python
1OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
2OPENROUTER_MODEL_PROMPT_GEN = "x-ai/grok-..."
3OPENROUTER_MODEL_PROMPT_REVISE = "x-ai/grok-..."
4OPENROUTER_MODEL_JUDGE = "x-ai/grok-vision-..."  # must support vision
5OPENROUTER_TIMEOUT_TEXT = 30
6OPENROUTER_TIMEOUT_VISION = 45
7OPENROUTER_MAX_RETRIES = 2

Notes

• Never log API key, response.text for large vision calls, or base64 image data
• Image for judge: read from data/sessions/<id>/iter_<n>.jpg, encode as base64
• The judge call is the only one that uses vision; wrap it separately in vision_completion()
• HTTP-Referer should be "http://localhost:5000" for local dev