openrouter

package
v1.0.21 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 3, 2025 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package openrouter provides an OpenRouter AI provider implementation. It includes support for model selection, API key management, OAuth authentication, and specialized features for the OpenRouter platform.

Package openrouter provides an OpenRouter AI provider implementation. It includes support for model selection, API key management, OAuth authentication, and specialized features for the OpenRouter platform.

Package openrouter provides an OpenRouter AI provider implementation. It includes support for model selection, API key management, OAuth authentication, and specialized features for the OpenRouter platform.

Package openrouter provides an OpenRouter AI provider implementation. It includes support for model selection, API key management, OAuth authentication, and specialized features for the OpenRouter platform.

Package openrouter provides an OpenRouter AI provider implementation. It includes support for model selection, API key management, OAuth authentication, and specialized features for the OpenRouter platform.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIKeyManager 

type APIKeyManager struct {
	// contains filtered or unexported fields
}

APIKeyManager manages multiple API keys with load balancing and failover

func NewAPIKeyManager 

func NewAPIKeyManager(providerName string, keys []string) *APIKeyManager

NewAPIKeyManager creates a new API key manager

func (*APIKeyManager) ExecuteWithFailover 

func (m *APIKeyManager) ExecuteWithFailover(operation func(apiKey string) (string, *types.Usage, error)) (string, *types.Usage, error)

ExecuteWithFailover attempts an operation with automatic failover to next key on failure The operation function should accept an API key and return (result, usage, error)

func (*APIKeyManager) GetCurrentKey 

func (m *APIKeyManager) GetCurrentKey() string

GetCurrentKey returns the first available API key without advancing the round-robin counter

func (*APIKeyManager) GetNextKey 

func (m *APIKeyManager) GetNextKey() (string, error)

GetNextKey returns the next available API key using round-robin load balancing

func (*APIKeyManager) GetStatus 

func (m *APIKeyManager) GetStatus() map[string]interface{}

GetStatus returns the current health status of all keys

func (*APIKeyManager) ReportFailure 

func (m *APIKeyManager) ReportFailure(key string, err error)

ReportFailure reports that an API call failed with this key

func (*APIKeyManager) ReportSuccess 

func (m *APIKeyManager) ReportSuccess(key string)

ReportSuccess reports that an API call succeeded with this key

type MockStream 

type MockStream struct {
	// contains filtered or unexported fields
}

MockStream implements ChatCompletionStream for testing

func (*MockStream) Close 

func (ms *MockStream) Close() error

func (*MockStream) Next 

func (ms *MockStream) Next() (types.ChatCompletionChunk, error)

type ModelSelector 

type ModelSelector struct {
	// contains filtered or unexported fields
}

ModelSelector implements different strategies for selecting models

func NewModelSelector 

func NewModelSelector(models []string, strategy string) *ModelSelector

NewModelSelector creates a new ModelSelector with the given models and strategy

func (*ModelSelector) RecordFailure 

func (ms *ModelSelector) RecordFailure(model string)

RecordFailure marks a model as failed for the failover strategy

func (*ModelSelector) Reset 

func (ms *ModelSelector) Reset()

Reset clears the failed models map

func (*ModelSelector) SelectModel 

func (ms *ModelSelector) SelectModel() (string, error)

SelectModel selects a model based on the configured strategy

type OAuthFlowState 

type OAuthFlowState struct {
	CodeVerifier string    `json:"code_verifier"`
	CallbackURL  string    `json:"callback_url"`
	CreatedAt    time.Time `json:"created_at"`
	ExpiresAt    time.Time `json:"expires_at"`
}

OAuthFlowState tracks the state of an OAuth flow in progress This should be stored temporarily during the OAuth flow

func NewOAuthFlowState 

func NewOAuthFlowState(codeVerifier, callbackURL string) *OAuthFlowState

NewOAuthFlowState creates a new OAuth flow state

func (*OAuthFlowState) IsExpired 

func (s *OAuthFlowState) IsExpired() bool

IsExpired checks if the OAuth flow state has expired

func (*OAuthFlowState) Validate 

func (s *OAuthFlowState) Validate() error

Validate validates the OAuth flow state

type OAuthHelper 

type OAuthHelper struct {
	// contains filtered or unexported fields
}

OAuthHelper provides OAuth flow utilities for OpenRouter OpenRouter's OAuth is unique: it provisions permanent API keys rather than temporary tokens

func NewOAuthHelper 

func NewOAuthHelper(baseURL string) *OAuthHelper

NewOAuthHelper creates a new OAuth helper for OpenRouter

func (*OAuthHelper) BuildAuthURL 

func (h *OAuthHelper) BuildAuthURL(callbackURL string, pkceParams *PKCEParams) (string, error)

BuildAuthURL constructs the OAuth authorization URL for OpenRouter OpenRouter's OAuth flow is simpler: no client_id/client_secret needed

func (*OAuthHelper) ExchangeCodeForAPIKey 

func (h *OAuthHelper) ExchangeCodeForAPIKey(ctx context.Context, authCode string, codeVerifier string) (string, error)

ExchangeCodeForAPIKey exchanges the authorization code for an OpenRouter API key This is the final step of the OAuth flow Returns the permanent API key that can be added to the APIKeyManager pool

func (*OAuthHelper) GeneratePKCEParams 

func (h *OAuthHelper) GeneratePKCEParams() (*PKCEParams, error)

GeneratePKCEParams generates PKCE parameters for OAuth flow OpenRouter requires S256 code challenge method

func (*OAuthHelper) ValidateCallback 

func (h *OAuthHelper) ValidateCallback(code, errorParam string) error

ValidateCallback validates the OAuth callback parameters

type OpenRouterArchitecture 

type OpenRouterArchitecture struct {
	Modality     string `json:"modality"`
	TokenizerID  string `json:"tokenizer"`
	InstructType string `json:"instruct_type"`
}

OpenRouterArchitecture represents model architecture info

type OpenRouterChoice 

type OpenRouterChoice struct {
	Index        int               `json:"index"`
	Message      OpenRouterMessage `json:"message"`
	FinishReason string            `json:"finish_reason"`
}

OpenRouterChoice represents a choice in the response

type OpenRouterError 

type OpenRouterError struct {
	Message string `json:"message"`
	Type    string `json:"type"`
	Code    int    `json:"code"`
}

OpenRouterError represents an error in the response

type OpenRouterErrorResponse 

type OpenRouterErrorResponse struct {
	Error OpenRouterError `json:"error"`
}

OpenRouterErrorResponse represents an error response

type OpenRouterExtension 

type OpenRouterExtension struct {
	*types.BaseExtension
}

OpenRouterExtension implements CoreProviderExtension for OpenRouter

func NewOpenRouterExtension 

func NewOpenRouterExtension() *OpenRouterExtension

NewOpenRouterExtension creates a new OpenRouter extension

func (*OpenRouterExtension) ProviderToStandard 

func (e *OpenRouterExtension) ProviderToStandard(response interface{}) (*types.StandardResponse, error)

ProviderToStandard converts an OpenRouter response to standard format

func (*OpenRouterExtension) ProviderToStandardChunk 

func (e *OpenRouterExtension) ProviderToStandardChunk(chunk interface{}) (*types.StandardStreamChunk, error)

ProviderToStandardChunk converts an OpenRouter stream chunk to standard format

func (*OpenRouterExtension) StandardToProvider 

func (e *OpenRouterExtension) StandardToProvider(request types.StandardRequest) (interface{}, error)

StandardToProvider converts a standard request to OpenRouter format

func (*OpenRouterExtension) ValidateOptions 

func (e *OpenRouterExtension) ValidateOptions(options map[string]interface{}) error

ValidateOptions validates OpenRouter-specific options

type OpenRouterFunctionDef 

type OpenRouterFunctionDef struct {
	Name        string                 `json:"name"`
	Description string                 `json:"description"`
	Parameters  map[string]interface{} `json:"parameters"` // JSON Schema
}

OpenRouterFunctionDef represents a function definition in the OpenRouter API

type OpenRouterMessage 

type OpenRouterMessage struct {
	Role       string               `json:"role"`
	Content    string               `json:"content"`
	ToolCalls  []OpenRouterToolCall `json:"tool_calls,omitempty"`
	ToolCallID string               `json:"tool_call_id,omitempty"`
}

OpenRouterMessage represents a message in the conversation

type OpenRouterModelData 

type OpenRouterModelData struct {
	ID            string                 `json:"id"`
	Name          string                 `json:"name"`
	Description   string                 `json:"description"`
	Pricing       OpenRouterPricing      `json:"pricing"`
	ContextLength int                    `json:"context_length"`
	Architecture  OpenRouterArchitecture `json:"architecture"`
	TopProvider   OpenRouterTopProvider  `json:"top_provider"`
}

OpenRouterModelData represents a model in the models list

type OpenRouterModelsResponse 

type OpenRouterModelsResponse struct {
	Data []OpenRouterModelData `json:"data"`
}

OpenRouterModelsResponse represents the response from /api/v1/models endpoint

type OpenRouterPricing 

type OpenRouterPricing struct {
	Prompt     string `json:"prompt"`
	Completion string `json:"completion"`
	Request    string `json:"request"`
	Image      string `json:"image"`
}

OpenRouterPricing represents pricing information

type OpenRouterProvider 

type OpenRouterProvider struct {
	*base.BaseProvider
	// contains filtered or unexported fields
}

OpenRouterProvider implements the Provider interface for OpenRouter

func NewOpenRouterProvider 

func NewOpenRouterProvider(config types.ProviderConfig) *OpenRouterProvider

NewOpenRouterProvider creates a new OpenRouter provider

func (*OpenRouterProvider) AddAPIKey 

func (p *OpenRouterProvider) AddAPIKey(apiKey string) error

AddAPIKey adds a new API key to the auth helper pool This can be used to add OAuth-obtained keys or manually configured keys

func (*OpenRouterProvider) Authenticate 

func (p *OpenRouterProvider) Authenticate(ctx context.Context, authConfig types.AuthConfig) error

func (*OpenRouterProvider) Configure 

func (p *OpenRouterProvider) Configure(config types.ProviderConfig) error

func (*OpenRouterProvider) Description 

func (p *OpenRouterProvider) Description() string

func (*OpenRouterProvider) GenerateChatCompletion 

func (p *OpenRouterProvider) GenerateChatCompletion(
	ctx context.Context,
	options types.GenerateOptions,
) (types.ChatCompletionStream, error)

func (*OpenRouterProvider) GetAPIKeys 

func (p *OpenRouterProvider) GetAPIKeys() []string

GetAPIKeys returns a masked list of all API keys in the auth helper

func (*OpenRouterProvider) GetCombinedRateLimits 

func (p *OpenRouterProvider) GetCombinedRateLimits(ctx context.Context, model string) (*OpenRouterRateLimits, *ratelimit.Info, error)

GetCombinedRateLimits provides unified rate limit information by combining: 1. API endpoint data (/api/v1/key) - provides account-level credit information 2. Header-based tracking - provides per-model request/token limits This method returns the most comprehensive and up-to-date rate limit information.

func (*OpenRouterProvider) GetDefaultModel 

func (p *OpenRouterProvider) GetDefaultModel() string

func (*OpenRouterProvider) GetLastUsedModel 

func (p *OpenRouterProvider) GetLastUsedModel() string

GetLastUsedModel returns the model name that was used in the last API call

func (*OpenRouterProvider) GetMetrics 

func (p *OpenRouterProvider) GetMetrics() types.ProviderMetrics

func (*OpenRouterProvider) GetModels 

func (p *OpenRouterProvider) GetModels(ctx context.Context) ([]types.Model, error)

func (*OpenRouterProvider) GetRateLimits 

func (p *OpenRouterProvider) GetRateLimits(ctx context.Context) (*OpenRouterRateLimits, error)

GetRateLimits queries the OpenRouter API for current rate limit information via /api/v1/key endpoint. This is the existing approach that makes a dedicated API call to check rate limits.

func (*OpenRouterProvider) GetToolFormat 

func (p *OpenRouterProvider) GetToolFormat() types.ToolFormat

func (*OpenRouterProvider) GetTrackedRateLimits 

func (p *OpenRouterProvider) GetTrackedRateLimits(model string) *ratelimit.Info

GetTrackedRateLimits returns the rate limit information tracked from response headers. This provides the most up-to-date rate limit information for a specific model without making an additional API call. Returns nil if no rate limit data has been tracked for the given model yet.

func (*OpenRouterProvider) HandleOAuthCallback 

func (p *OpenRouterProvider) HandleOAuthCallback(ctx context.Context, authCode string, flowState *OAuthFlowState) (apiKey string, err error)

HandleOAuthCallback processes the OAuth callback and exchanges the code for an API key The obtained API key is automatically added to the APIKeyManager pool

func (*OpenRouterProvider) HealthCheck 

func (p *OpenRouterProvider) HealthCheck(ctx context.Context) error

func (*OpenRouterProvider) InvokeServerTool 

func (p *OpenRouterProvider) InvokeServerTool(
	ctx context.Context,
	toolName string,
	params interface{},
) (interface{}, error)

func (*OpenRouterProvider) IsAPIKeyConfigured added in v1.0.17 

func (p *OpenRouterProvider) IsAPIKeyConfigured() bool

IsAPIKeyConfigured checks if API key authentication is properly configured

func (*OpenRouterProvider) IsAuthenticated 

func (p *OpenRouterProvider) IsAuthenticated() bool

func (*OpenRouterProvider) IsOAuthConfigured added in v1.0.17 

func (p *OpenRouterProvider) IsOAuthConfigured() bool

IsOAuthConfigured checks if OAuth authentication is properly configured OpenRouter supports OAuth flow which provisions permanent API keys

func (*OpenRouterProvider) Logout 

func (p *OpenRouterProvider) Logout(ctx context.Context) error

func (*OpenRouterProvider) Name 

func (p *OpenRouterProvider) Name() string

func (*OpenRouterProvider) RemoveAPIKey 

func (p *OpenRouterProvider) RemoveAPIKey(apiKey string) error

RemoveAPIKey removes an API key from the auth helper pool

func (*OpenRouterProvider) StartOAuthFlow 

func (p *OpenRouterProvider) StartOAuthFlow(ctx context.Context, callbackURL string) (authURL string, flowState *OAuthFlowState, err error)

StartOAuthFlow initiates the OAuth flow and returns the authorization URL OpenRouter OAuth provisions permanent API keys, not temporary tokens

func (*OpenRouterProvider) SupportsResponsesAPI 

func (p *OpenRouterProvider) SupportsResponsesAPI() bool

func (*OpenRouterProvider) SupportsStreaming 

func (p *OpenRouterProvider) SupportsStreaming() bool

func (*OpenRouterProvider) SupportsToolCalling 

func (p *OpenRouterProvider) SupportsToolCalling() bool

func (*OpenRouterProvider) TestConnectivity added in v1.0.14 

func (p *OpenRouterProvider) TestConnectivity(ctx context.Context) error

TestConnectivity performs a lightweight connectivity test using the /v1/models endpoint Results are cached for 30 seconds by default to prevent hammering the API during rapid health checks To bypass the cache and force a fresh check, use TestConnectivityWithOptions with bypassCache=true

func (*OpenRouterProvider) TestConnectivityWithOptions added in v1.0.17 

func (p *OpenRouterProvider) TestConnectivityWithOptions(ctx context.Context, bypassCache bool) error

TestConnectivityWithOptions performs a connectivity test with optional cache bypass If bypassCache is true, the cache is bypassed and a fresh connectivity check is performed

func (*OpenRouterProvider) Type 

func (p *OpenRouterProvider) Type() types.ProviderType

type OpenRouterRateLimits 

type OpenRouterRateLimits struct {
	Limit          *float64 `json:"limit"`           // Credit limit (can be null)
	LimitReset     string   `json:"limit_reset"`     // Reset type for credits
	LimitRemaining *float64 `json:"limit_remaining"` // Remaining credits
	Usage          float64  `json:"usage"`           // Total credits used
	IsFreeTier     bool     `json:"is_free_tier"`    // Whether account is on free tier
	RateLimit      struct {
		RequestsPerMinute int `json:"requests_per_minute"`
		RequestsPerDay    int `json:"requests_per_day"`
	} `json:"rate_limit,omitempty"` // Rate limit information
}

OpenRouterRateLimits represents rate limit information from the /api/v1/key endpoint

type OpenRouterRequest 

type OpenRouterRequest struct {
	Model         string              `json:"model"`
	Messages      []OpenRouterMessage `json:"messages"`
	Stream        bool                `json:"stream"`
	HTTPReferer   string              `json:"http_referer,omitempty"`
	HTTPUserAgent string              `json:"x-title,omitempty"`
	Temperature   float64             `json:"temperature,omitempty"`
	MaxTokens     int                 `json:"max_tokens,omitempty"`
	Tools         []OpenRouterTool    `json:"tools,omitempty"`
	ToolChoice    interface{}         `json:"tool_choice,omitempty"`
}

OpenRouterRequest represents the request payload for OpenRouter API

type OpenRouterResponse 

type OpenRouterResponse struct {
	ID      string             `json:"id"`
	Object  string             `json:"object"`
	Created int64              `json:"created"`
	Model   string             `json:"model"`
	Choices []OpenRouterChoice `json:"choices"`
	Usage   OpenRouterUsage    `json:"usage"`
}

OpenRouterResponse represents the response from OpenRouter API

type OpenRouterStream 

type OpenRouterStream struct {
	// contains filtered or unexported fields
}

OpenRouterStream implements ChatCompletionStream for real streaming responses

func (*OpenRouterStream) Close 

func (s *OpenRouterStream) Close() error

func (*OpenRouterStream) Next 

func (s *OpenRouterStream) Next() (types.ChatCompletionChunk, error)

type OpenRouterTool 

type OpenRouterTool struct {
	Type     string                `json:"type"` // Always "function"
	Function OpenRouterFunctionDef `json:"function"`
}

OpenRouterTool represents a tool in the OpenRouter API (OpenAI-compatible format)

type OpenRouterToolCall 

type OpenRouterToolCall struct {
	ID       string                     `json:"id"`
	Type     string                     `json:"type"` // "function"
	Function OpenRouterToolCallFunction `json:"function"`
}

OpenRouterToolCall represents a tool call in the OpenRouter API

type OpenRouterToolCallFunction 

type OpenRouterToolCallFunction struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"` // JSON string
}

OpenRouterToolCallFunction represents a function call in a tool call

type OpenRouterTopProvider 

type OpenRouterTopProvider struct {
	ContextLength       int  `json:"context_length"`
	MaxCompletionTokens int  `json:"max_completion_tokens"`
	IsModerated         bool `json:"is_moderated"`
}

OpenRouterTopProvider represents top provider info

type OpenRouterUsage 

type OpenRouterUsage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
}

OpenRouterUsage represents token usage information

type PKCEParams 

type PKCEParams struct {
	CodeVerifier  string
	CodeChallenge string
	Method        string // Always "S256" for OpenRouter
}

PKCEParams holds PKCE flow parameters

type ProviderConfig 

type ProviderConfig struct {
	APIKey        string   `json:"api_key"`
	APIKeys       []string `json:"api_keys,omitempty"`
	Model         string   `json:"model,omitempty"`
	Models        []string `json:"models,omitempty"`
	ModelStrategy string   `json:"model_strategy,omitempty"`
	FreeOnly      bool     `json:"free_only,omitempty"`
	SiteURL       string   `json:"site_url,omitempty"`
	SiteName      string   `json:"site_name,omitempty"`
	BaseURL       string   `json:"base_url,omitempty"`

	// OAuth configuration
	OAuthCallbackURL string `json:"oauth_callback_url,omitempty"`
}

ProviderConfig holds OpenRouter-specific configuration

type TokenExchangeRequest 

type TokenExchangeRequest struct {
	Code                string `json:"code"`
	CodeVerifier        string `json:"code_verifier"`
	CodeChallengeMethod string `json:"code_challenge_method"`
}

TokenExchangeRequest represents the request to exchange authorization code for API key

type TokenExchangeResponse 

type TokenExchangeResponse struct {
	Key   string `json:"key"` // The API key (format: sk-or-v1-xxxxx)
	Error string `json:"error,omitempty"`
}

TokenExchangeResponse represents the response from token exchange OpenRouter returns a permanent API key, not a temporary OAuth token

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.