PhoenixKit.Modules.AI.OpenRouterClient (phoenix_kit v1.7.71)

Copy Markdown View Source

OpenRouter API client for PhoenixKit AI system.

Provides functions for interacting with the OpenRouter API, including:

  • API key validation
  • Model discovery (fetching available models)
  • Building request headers

OpenRouter API Reference

  • Base URL: https://openrouter.ai/api/v1
  • Authentication: Bearer token in Authorization header
  • Optional headers: HTTP-Referer, X-Title (for rankings)

Usage Examples

# Validate an API key
case PhoenixKit.Modules.AI.OpenRouterClient.validate_api_key("sk-or-v1-...") do
  {:ok, %{credits: credits}} -> IO.puts("Valid! Credits: #{credits}")
  {:error, reason} -> IO.puts("Invalid: #{reason}")
end

# Fetch available models
{:ok, models} = PhoenixKit.Modules.AI.OpenRouterClient.fetch_models("sk-or-v1-...")

Summary

Functions

base_url()

Returns the base URL for OpenRouter API.

build_headers(api_key, opts \\ [])

Builds HTTP headers for OpenRouter API requests.

build_headers_from_account(map)

Builds headers from an Account struct's settings.

build_headers_from_endpoint(map)

Builds headers from an Endpoint struct's provider_settings.

extract_model_name(model_id)

Extracts the model name without provider prefix.

extract_provider(model_id)

Extracts the provider name from a model ID.

fetch_embedding_models(api_key, opts \\ [])

Fetches embedding models from OpenRouter.

fetch_embedding_models_grouped(api_key, opts \\ [])

Fetches embedding models grouped by provider.

fetch_model(api_key, model_id, opts \\ [])

Fetches details for a specific model by ID.

fetch_models(api_key, opts \\ [])

Fetches available models from OpenRouter.

fetch_models_by_type(api_key, model_type, opts \\ [])

Fetches models by type and groups them by provider.

fetch_models_grouped(api_key, opts \\ [])

Fetches models and groups them by provider.

get_model_max_tokens(model)

Gets the effective max tokens for a model.

humanize_provider(provider)

Converts a provider slug to a human-friendly name.

model_option(model)

Formats a model for display in a select dropdown.

model_supports_parameter?(model, param)

Checks if a model supports a specific parameter.

validate_api_key(api_key)

Validates an OpenRouter API key by making a request to the /models endpoint.

Functions

base_url()

Returns the base URL for OpenRouter API.

build_headers(api_key, opts \\ [])

Builds HTTP headers for OpenRouter API requests.

Options

  • :http_referer - Site URL for rankings
  • :x_title - Site title for rankings
  • :include_usage - Include detailed usage/cost info (default: true for completions)

build_headers_from_account(map)

Builds headers from an Account struct's settings.

build_headers_from_endpoint(map)

Builds headers from an Endpoint struct's provider_settings.

extract_model_name(model_id)

Extracts the model name without provider prefix.

extract_provider(model_id)

Extracts the provider name from a model ID.

Examples

iex> extract_provider("anthropic/claude-3-opus")
"Anthropic"

iex> extract_provider("openai/gpt-4")
"OpenAI"

fetch_embedding_models(api_key, opts \\ [])

Fetches embedding models from OpenRouter.

Note: Embedding models are fetched from a hardcoded list as OpenRouter doesn't return them from the /models endpoint. The actual embedding request goes to /api/v1/embeddings.

Returns {:ok, models} with a list of known embedding models.

fetch_embedding_models_grouped(api_key, opts \\ [])

Fetches embedding models grouped by provider.

fetch_model(api_key, model_id, opts \\ [])

Fetches details for a specific model by ID.

Returns {:ok, model} or {:error, reason}.

fetch_models(api_key, opts \\ [])

Fetches available models from OpenRouter.

Returns {:ok, models} where models is a list of model objects, or {:error, reason} on failure.

Options

  • :model_type - Filter by model type: :text, :vision, :image_gen, :all (default: :all)
  • :http_referer - Site URL for rankings
  • :x_title - Site title for rankings

Model Object Structure

Each model has:

  • id - Model identifier (e.g., "anthropic/claude-3-opus")
  • name - Display name
  • description - Model description
  • pricing - Pricing information (prompt/completion costs)
  • context_length - Maximum context window
  • architecture - Model architecture details

fetch_models_by_type(api_key, model_type, opts \\ [])

Fetches models by type and groups them by provider.

Model Types

  • :text - Text/chat completion models (text->text)
  • :vision - Vision/multimodal models (text+image->text)
  • :image_gen - Image generation models (text+image->text+image)
  • :all - All models without filtering

Examples

{:ok, grouped} = fetch_models_by_type(api_key, :vision)

fetch_models_grouped(api_key, opts \\ [])

Fetches models and groups them by provider.

Options

  • :model_type - Filter by model type: :text, :vision, :image_gen, :all (default: :text)

Returns a map where keys are provider names and values are lists of models.

get_model_max_tokens(model)

Gets the effective max tokens for a model.

Returns the model's max_completion_tokens if available, otherwise falls back to a percentage of context_length.

humanize_provider(provider)

Converts a provider slug to a human-friendly name.

OpenRouter model IDs use slugs like "arcee-ai/model-name". This function converts the slug portion to a human-readable provider name.

Examples

iex> humanize_provider("openai")
"OpenAI"

iex> humanize_provider("meta-llama")
"Meta Llama"

iex> humanize_provider("arcee-ai")
"Arcee AI"

model_option(model)

Formats a model for display in a select dropdown.

Returns {label, value} tuple.

model_supports_parameter?(model, param)

Checks if a model supports a specific parameter.

Examples

iex> model_supports_parameter?(model, "temperature")
true

iex> model_supports_parameter?(model, "tools")
false

validate_api_key(api_key)

Validates an OpenRouter API key by making a request to the /models endpoint.

Returns {:ok, %{valid: true}} on success, {:error, reason} on failure.