openingrouter

package module
v1.1.4 Latest Latest
Warning

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

 Go to latest Published: Aug 24, 2026 License: MIT Imports: 17 Imported by: 0

README

openingrouter

Go client for the OpenRouter API.

Install

go get github.com/coalaura/openingrouter

Client

client := openingrouter.NewClient(
    os.Getenv("OPENROUTER_API_KEY"),
    openingrouter.WithTitle("my-app"),
    openingrouter.WithReferer("https://example.com"),
)

Options: WithClient, WithBase, WithTitle, WithReferer.

OpenAI-compatible endpoints

Point the same request/response types at any OpenAI-compatible API (OpenAI, Groq, Together, a local server, ...):

oa := client.ToOpenAI() // reuses the token + HTTP client

// or standalone; defaults to https://api.openai.com/v1/
oa := openingrouter.NewOpenAIClient(
    os.Getenv("OPENAI_API_KEY"),
    openingrouter.WithOpenAIBase("https://api.groq.com/openai/v1"),
)

resp, err := oa.CreateChatCompletion(ctx, openingrouter.ChatCompletionRequest{...})
models, err := oa.ListModels(ctx)

Supported: ListModels, GetModel, CreateChatCompletion/Stream, CreateEmbeddings. Non-2xx responses map to *OpenAIError.

Chat

resp, err := client.CreateChatCompletion(ctx, openingrouter.ChatCompletionRequest{
    Model: "openai/gpt-oss-20b",
    Messages: []openingrouter.ChatMessage{{
        Role:    openingrouter.ChatRoleUser,
        Content: openingrouter.ChatContent{Text: "Hello"},
    }},
})

Streaming responses:

stream, err := client.CreateChatCompletionStream(ctx, openingrouter.ChatCompletionRequest{
    Model: "openai/gpt-oss-20b",
    Messages: []openingrouter.ChatMessage{{
        Role:    openingrouter.ChatRoleUser,
        Content: openingrouter.ChatContent{Text: "Hello"},
    }},
})
if err != nil {
    return err
}

defer stream.Close()

for {
    chunk, err := stream.Recv()
    if errors.Is(err, io.EOF) {
        break
    }

    if err != nil {
        // *ChatStreamError when the stream fails after it started
        return err
    }

    // chunk.Choices[0].Delta.Content
}

Optional fields use pointers (new(true), new(0.7)). Zero values and nil pointers are omitted from the request body. Set MetadataLevel to receive routing metadata.

Embeddings

resp, err := client.CreateEmbeddings(ctx, openingrouter.EmbeddingRequest{
    Model: "openai/text-embedding-3-small",
    Input: openingrouter.EmbeddingInput{Text: "Hello"},
})

Input accepts a single text, a list of texts, token arrays or multimodal content.

Image generation

resp, err := client.GenerateImage(ctx, openingrouter.ImageGenerationRequest{
    Model:       "black-forest-labs/flux.2-klein-4b",
    Prompt:      "a cat in a banana costume",
    AspectRatio: openingrouter.ImageAspectRatio1x1,
})

// resp.Data[i].B64JSON, resp.Data[i].MediaType

Streaming via GenerateImageStream (mid-stream failures return *ImageStreamError from Recv). List models with ListImageModels.

Speech

Text-to-speech (caller owns and must close the body):

resp, err := client.CreateSpeech(ctx, openingrouter.SpeechRequest{
    Model:          "sesame/csm-1b",
    Input:          "hello world",
    Voice:          "...",
    ResponseFormat: openingrouter.SpeechResponseFormatMP3,
})

defer resp.Body.Close()

// resp.Body, resp.ContentType, resp.GenerationID

Speech-to-text:

resp, err := client.CreateTranscription(ctx, openingrouter.STTRequest{
    Model: "google/chirp-3",
    InputAudio: openingrouter.STTInputAudio{
        Data:   base64Audio,
        Format: "wav",
    },
})

// resp.Text

Models

models, err := client.ListModels(ctx, &openingrouter.ListModelsOptions{
    Limit: new(10),
})

model, err := client.GetModelBySlug(ctx, "deepseek/deepseek-v4-flash")

endpoints, err := client.GetModelEndpoints(ctx, "deepseek/deepseek-v4-flash")

// endpoints.Endpoints[i].Pricing, .ProviderName, .LatencyLast30m

userModels, err := client.ListUserModels(ctx, nil)
embeddingModels, err := client.ListEmbeddingModels(ctx, nil)

API key

info, err := client.GetCurrentApiKey(ctx)

Frontend catalog

Unauthenticated frontend route (not part of the public API, sometimes has more information):

models, err := openingrouter.ListFrontendModels(ctx)

providers, err := openingrouter.ListFrontendProviders(ctx)

Errors

Client.Do maps non-2xx responses to:

Type When
*OpenRouterError API error with numeric code
*ApiError Named API / validation error
*ProviderError Upstream provider error

Network failures are returned as-is.

Streaming endpoints that fail after the response has started surface the failure from Recv as a typed error (not as a field on the chunk):

Type Endpoint
*ChatStreamError CreateChatCompletionStream
*ImageStreamError GenerateImageStream

Their Error() strings match the same style as *OpenRouterError (openrouter code <code>: <message>, falling back to openrouter: <message> when no code is present). Nested provider JSON in the message is cleaned the same way as HTTP errors. Inspect fields with errors.As / errors.AsType:

chunk, err := stream.Recv()
if err != nil {
    if errors.Is(err, io.EOF) {
        break
    }

    if streamErr, ok := errors.AsType[*openingrouter.ChatStreamError](err); ok {
        // streamErr.Code, streamErr.Metadata
        return streamErr
    }

    return err
}

Streams

OpenrouterStream[T] is the common interface:

type OpenrouterStream[T any] interface {
    Recv() (T, error) // io.EOF when done; typed stream error on mid-stream failure
    Close()
}

Always defer stream.Close(). Chunk types that carry an in-band error implement it privately; Recv promotes that error so callers only need the usual err != nil path.

Layout

File prefix Endpoint
chat_ POST /chat/completions
embeddings_ POST /embeddings
embedding_models_ GET /embeddings/models
image_ POST /images
image_models_ GET /images/models
models_ GET /models, /models/user, /model/{slug}, /models/{slug}/endpoints
stt_ POST /audio/transcriptions
tts_ POST /audio/speech
api_key_ GET /key
frontend_ frontend catalog
common_types.go shared request/response types

Tests

Integration tests hit the live API. Set OPENROUTER_API_KEY or they skip:

OPENROUTER_API_KEY="sk-or-v1-46...2f" go test ./...

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalidRequest      = errors.New("invalid request")
	ErrUnauthorized        = errors.New("unauthorized")
	ErrInsufficientCredits = errors.New("insufficient credits")
	ErrForbidden           = errors.New("forbidden")
	ErrNotFound            = errors.New("not found")
	ErrContextLength       = errors.New("context length exceeded")
	ErrModerated           = errors.New("moderated")
	ErrRateLimited         = errors.New("rate limited")
	ErrProviderUnavailable = errors.New("provider unavailable")
	ErrTimeout             = errors.New("timeout")
	ErrServer              = errors.New("server error")
)

Functions

func AsOpenAIError added in v1.1.0 

func AsOpenAIError(resp *http.Response, err error) error

AsOpenAIError converts an HTTP response status or error into a structured OpenAI compatible error.

func AsOpenRouterError added in v1.0.0 

func AsOpenRouterError(resp *http.Response, err error) error

AsOpenRouterError converts an HTTP response status or error into a structured OpenRouter error.

func IsResponseServerSentEventsStream added in v1.0.0 

func IsResponseServerSentEventsStream(response *http.Response) bool

IsResponseServerSentEventsStream reports whether the HTTP response is a Server-Sent Events stream.

Types

type AnthropicCacheControl added in v1.0.0 

type AnthropicCacheControl struct {
	Type AnthropicCacheControlType `json:"type"`
	TTL  AnthropicCacheTTL         `json:"ttl,omitempty"`
}

AnthropicCacheControl enables automatic prompt caching. At the top level of a request the last cacheable block is used as the breakpoint, on a content block it marks an explicit breakpoint.

type AnthropicCacheControlType added in v1.0.0 

type AnthropicCacheControlType string

AnthropicCacheControlType is the type of a cache control directive. 

const (
	AnthropicCacheControlTypeEphemeral AnthropicCacheControlType = "ephemeral"
)

type AnthropicCacheCreation added in v1.0.0 

type AnthropicCacheCreation struct {
	Ephemeral5MInputTokens int `json:"ephemeral_5m_input_tokens"`
	Ephemeral1HInputTokens int `json:"ephemeral_1h_input_tokens"`
}

AnthropicCacheCreation represents the cache write tokens of a request, split by cache ttl.

type AnthropicCacheTTL added in v1.0.0 

type AnthropicCacheTTL string

AnthropicCacheTTL is the lifetime of a cache breakpoint. 

const (
	AnthropicCacheTTL5M AnthropicCacheTTL = "5m"
	AnthropicCacheTTL1H AnthropicCacheTTL = "1h"
)

type AnthropicIterationCacheCreation added in v1.0.0 

type AnthropicIterationCacheCreation struct {
	Ephemeral5MInputTokens int `json:"ephemeral_5m_input_tokens"`
	Ephemeral1HInputTokens int `json:"ephemeral_1h_input_tokens"`
}

AnthropicIterationCacheCreation represents the cache write tokens of a single usage iteration, split by cache ttl.

type AnthropicSpeed added in v1.0.0 

type AnthropicSpeed string

AnthropicSpeed is the speed tier a request was served with. 

const (
	AnthropicSpeedFast     AnthropicSpeed = "fast"
	AnthropicSpeedStandard AnthropicSpeed = "standard"
)

type AnthropicUsageIteration added in v1.0.0 

type AnthropicUsageIteration struct {
	Type                     AnthropicUsageIterationType      `json:"type"`
	Model                    string                           `json:"model,omitempty"`
	InputTokens              int                              `json:"input_tokens"`
	OutputTokens             int                              `json:"output_tokens"`
	CacheCreationInputTokens int                              `json:"cache_creation_input_tokens"`
	CacheReadInputTokens     int                              `json:"cache_read_input_tokens"`
	CacheCreation            *AnthropicIterationCacheCreation `json:"cache_creation"`
}

AnthropicUsageIteration represents the usage of a single iteration of a request. Model is only populated for message and advisor message iterations, unknown iteration types are passed through as-is.

type AnthropicUsageIterationType added in v1.0.0 

type AnthropicUsageIterationType string

AnthropicUsageIterationType is the type of a single usage iteration. 

const (
	AnthropicUsageIterationTypeCompaction     AnthropicUsageIterationType = "compaction"
	AnthropicUsageIterationTypeMessage        AnthropicUsageIterationType = "message"
	AnthropicUsageIterationTypeAdvisorMessage AnthropicUsageIterationType = "advisor_message"
)

type ApiError added in v1.0.0 

type ApiError struct {
	ErrorStatus

	Name    string
	Message string
}

ApiError represents a general API error returned by OpenRouter.

func (*ApiError) Error added in v1.0.0 

func (a *ApiError) Error() string

Error returns the formatted string representation of the API error.

type ApiKeyInfo added in v1.0.0 

type ApiKeyInfo struct {
	Label              string            `json:"label"`
	Usage              float64           `json:"usage"`
	UsageDaily         float64           `json:"usage_daily"`
	UsageWeekly        float64           `json:"usage_weekly"`
	UsageMonthly       float64           `json:"usage_monthly"`
	BYOKUsage          float64           `json:"byok_usage"`
	BYOKUsageDaily     float64           `json:"byok_usage_daily"`
	BYOKUsageWeekly    float64           `json:"byok_usage_weekly"`
	BYOKUsageMonthly   float64           `json:"byok_usage_monthly"`
	Limit              *float64          `json:"limit"`
	LimitRemaining     *float64          `json:"limit_remaining"`
	LimitReset         *ApiKeyLimitReset `json:"limit_reset"`
	IncludeBYOKInLimit bool              `json:"include_byok_in_limit"`
	IsFreeTier         bool              `json:"is_free_tier"`
	IsManagementKey    bool              `json:"is_management_key"`
	IsProvisioningKey  bool              `json:"is_provisioning_key"`
	CreatorUserID      *string           `json:"creator_user_id"`
	ExpiresAt          *FlexibleTime     `json:"expires_at"`
	RateLimit          ApiKeyRateLimit   `json:"rate_limit"`
}

ApiKeyInfo represents information on the API key associated with the current authentication session.

type ApiKeyLimitReset added in v1.0.0 

type ApiKeyLimitReset string

ApiKeyLimitReset is the type of limit reset schedule for an API key. 

const (
	ApiKeyLimitResetDaily   ApiKeyLimitReset = "daily"
	ApiKeyLimitResetWeekly  ApiKeyLimitReset = "weekly"
	ApiKeyLimitResetMonthly ApiKeyLimitReset = "monthly"
)

type ApiKeyRateLimit added in v1.0.0 

type ApiKeyRateLimit struct {
	Requests int    `json:"requests"`
	Interval string `json:"interval"`
	Note     string `json:"note"`
}

ApiKeyRateLimit represents legacy rate limit information about an API key. Deprecated: this field is safe to ignore.

type ArtificialAnalysisBenchmark added in v1.0.0 

type ArtificialAnalysisBenchmark struct {
	IntelligenceIndex *float64 `json:"intelligence_index"`
	CodingIndex       *float64 `json:"coding_index"`
	AgenticIndex      *float64 `json:"agentic_index"`
}

ArtificialAnalysisBenchmark represents the Artificial Analysis index scores.

type ChatAdvisorTool added in v1.0.0 

type ChatAdvisorTool struct {
	Type       ChatToolType           `json:"type"`
	Parameters *ChatAdvisorToolConfig `json:"parameters,omitempty"`
}

ChatAdvisorTool represents the built-in advisor server tool, consulting a higher-intelligence advisor model mid-generation. Include multiple entries to offer several named advisors, at most one may omit its name.

type ChatAdvisorToolConfig added in v1.0.0 

type ChatAdvisorToolConfig struct {
	ForwardTranscript   *bool              `json:"forward_transcript,omitempty"`
	Instructions        string             `json:"instructions,omitempty"`
	MaxCompletionTokens *int               `json:"max_completion_tokens,omitempty"`
	MaxToolCalls        *int               `json:"max_tool_calls,omitempty"`
	Model               string             `json:"model,omitempty"`
	Name                string             `json:"name,omitempty"`
	Reasoning           *ChatToolReasoning `json:"reasoning,omitempty"`
	Stream              *bool              `json:"stream,omitempty"`
	Temperature         *float64           `json:"temperature,omitempty"`
	Tools               []ChatNestedTool   `json:"tools,omitempty"`
}

ChatAdvisorToolConfig holds the configuration of a single advisor server tool entry.

type ChatAssistantImage added in v1.0.0 

type ChatAssistantImage struct {
	ImageURL ContentPartImageURL `json:"image_url"`
}

ChatAssistantImage represents a single image generated by an image generation model.

type ChatAudioOutput added in v1.0.0 

type ChatAudioOutput struct {
	ID         string `json:"id,omitempty"`
	Data       string `json:"data,omitempty"`
	Transcript string `json:"transcript,omitempty"`
	ExpiresAt  int64  `json:"expires_at,omitempty"`
}

ChatAudioOutput represents the audio output of an assistant message.

type ChatAutoBetaRouterPlugin added in v1.0.0 

type ChatAutoBetaRouterPlugin struct {
	ID            ChatPluginID `json:"id"`
	AllowedModels []string     `json:"allowed_models,omitempty"`
	CostTier      ChatCostTier `json:"cost_tier,omitempty"`
	Enabled       *bool        `json:"enabled,omitempty"`

	// Deprecated: use CostTier instead. Takes precedence when both are set.
	CostQualityTradeoff *int `json:"cost_quality_tradeoff,omitempty"`
}

ChatAutoBetaRouterPlugin represents the auto-beta-router plugin, ranking models for the classified task type by community spend share.

type ChatAutoRouterPlugin added in v1.0.0 

type ChatAutoRouterPlugin struct {
	ID            ChatPluginID `json:"id"`
	AllowedModels []string     `json:"allowed_models,omitempty"`
	CostTier      ChatCostTier `json:"cost_tier,omitempty"`
	Enabled       *bool        `json:"enabled,omitempty"`
	PinModel      *bool        `json:"pin_model,omitempty"`

	// Deprecated: use CostTier instead. Takes precedence when both are set.
	CostQualityTradeoff *int `json:"cost_quality_tradeoff,omitempty"`
}

ChatAutoRouterPlugin represents the auto-router plugin, routing between models by a cost and quality tradeoff.

type ChatBashEngine added in v1.0.0 

type ChatBashEngine string

ChatBashEngine is the engine backing the bash server tool. Auto and native return the tool call to the caller, openrouter executes it server-side. 

const (
	ChatBashEngineAuto       ChatBashEngine = "auto"
	ChatBashEngineNative     ChatBashEngine = "native"
	ChatBashEngineOpenRouter ChatBashEngine = "openrouter"
)

type ChatBashEnvironment added in v1.0.0 

type ChatBashEnvironment struct {
	Type        ChatBashEnvironmentType `json:"type"`
	ContainerID string                  `json:"container_id,omitempty"`
}

ChatBashEnvironment represents the execution environment of the bash server tool. ContainerID is only used for container references.

type ChatBashEnvironmentType added in v1.0.0 

type ChatBashEnvironmentType string

ChatBashEnvironmentType is the kind of execution environment of the bash server tool. 

const (
	ChatBashEnvironmentTypeContainerAuto      ChatBashEnvironmentType = "container_auto"
	ChatBashEnvironmentTypeContainerReference ChatBashEnvironmentType = "container_reference"
)

type ChatBashTool added in v1.0.0 

type ChatBashTool struct {
	Type       ChatToolType        `json:"type"`
	Parameters *ChatBashToolConfig `json:"parameters,omitempty"`
}

ChatBashTool represents the built-in bash server tool, running shell commands in a sandboxed container.

type ChatBashToolConfig added in v1.0.0 

type ChatBashToolConfig struct {
	Engine            ChatBashEngine       `json:"engine,omitempty"`
	Environment       *ChatBashEnvironment `json:"environment,omitempty"`
	SleepAfterSeconds *int                 `json:"sleep_after_seconds,omitempty"`
}

ChatBashToolConfig holds the configuration of the bash server tool. SleepAfterSeconds is idle based, defaults to 900 and is capped at 2592000.

type ChatChoice added in v1.0.0 

type ChatChoice struct {
	Index        int              `json:"index"`
	FinishReason ChatFinishReason `json:"finish_reason"`
	Message      ChatMessage      `json:"message"`
	Logprobs     *ChatLogprobs    `json:"logprobs,omitempty"`
}

ChatChoice represents a single completion choice.

type ChatCompletionRequest added in v1.0.0 

type ChatCompletionRequest struct {
	Model    string        `json:"model,omitempty"`
	Messages []ChatMessage `json:"messages"`

	CacheControl        *AnthropicCacheControl  `json:"cache_control,omitempty"`
	Debug               *ChatDebugOptions       `json:"debug,omitempty"`
	FrequencyPenalty    *float64                `json:"frequency_penalty,omitempty"`
	ImageConfig         ChatImageConfig         `json:"image_config,omitempty"`
	LogitBias           map[string]float64      `json:"logit_bias,omitempty"`
	Logprobs            *bool                   `json:"logprobs,omitempty"`
	MaxCompletionTokens *int                    `json:"max_completion_tokens,omitempty"`
	MaxTokens           *int                    `json:"max_tokens,omitempty"`
	Metadata            map[string]string       `json:"metadata,omitempty"`
	MinP                *float64                `json:"min_p,omitempty"`
	Modalities          []OutputModality        `json:"modalities,omitempty"`
	Models              []string                `json:"models,omitempty"`
	ParallelToolCalls   *bool                   `json:"parallel_tool_calls,omitempty"`
	Plugins             []ChatPlugin            `json:"plugins,omitempty"`
	Prediction          *ChatPrediction         `json:"prediction,omitempty"`
	PresencePenalty     *float64                `json:"presence_penalty,omitempty"`
	PromptCacheKey      string                  `json:"prompt_cache_key,omitempty"`
	PromptCacheOptions  *ChatPromptCacheOptions `json:"prompt_cache_options,omitempty"`
	Provider            *ProviderPreferences    `json:"provider,omitempty"`
	Reasoning           *ChatReasoningConfig    `json:"reasoning,omitempty"`
	ReasoningEffort     ReasoningEffort         `json:"reasoning_effort,omitempty"`
	RepetitionPenalty   *float64                `json:"repetition_penalty,omitempty"`
	ResponseFormat      *ChatResponseFormat     `json:"response_format,omitempty"`
	Route               ChatRoute               `json:"route,omitempty"`
	Seed                *int                    `json:"seed,omitempty"`
	ServiceTier         ChatServiceTier         `json:"service_tier,omitempty"`
	SessionID           string                  `json:"session_id,omitempty"`
	Stop                []string                `json:"stop,omitempty"`
	StopServerToolsWhen []ChatStopCondition     `json:"stop_server_tools_when,omitempty"`
	Stream              *bool                   `json:"stream,omitempty"`
	StreamOptions       *ChatStreamOptions      `json:"stream_options,omitempty"`
	Temperature         *float64                `json:"temperature,omitempty"`
	ToolChoice          *ChatToolChoice         `json:"tool_choice,omitempty"`
	Tools               []ChatTool              `json:"tools,omitempty"`
	TopA                *float64                `json:"top_a,omitempty"`
	TopK                *int                    `json:"top_k,omitempty"`
	TopLogprobs         *int                    `json:"top_logprobs,omitempty"`
	TopP                *float64                `json:"top_p,omitempty"`
	Trace               *ChatTraceConfig        `json:"trace,omitempty"`
	User                string                  `json:"user,omitempty"`

	MetadataLevel ChatMetadataLevel `json:"-"`
}

ChatCompletionRequest represents the request body of the chat completion endpoint. Messages is required, Model may be omitted when a router plugin or preset decides the route. Zero values and nil pointers of the remaining fields are omitted from the request. MetadataLevel is sent as the X-OpenRouter-Metadata header and is not part of the body.

type ChatCompletionResponse added in v1.0.0 

type ChatCompletionResponse struct {
	ID                 string              `json:"id"`
	Object             ChatObject          `json:"object"`
	Created            int64               `json:"created"`
	Model              string              `json:"model"`
	Choices            []ChatChoice        `json:"choices"`
	SystemFingerprint  *string             `json:"system_fingerprint"`
	ServiceTier        *string             `json:"service_tier"`
	Usage              *ChatUsage          `json:"usage,omitempty"`
	OpenRouterMetadata *OpenRouterMetadata `json:"openrouter_metadata,omitempty"`
}

ChatCompletionResponse is the root response of the chat completion endpoint.

type ChatCompletionTokensDetails added in v1.0.0 

type ChatCompletionTokensDetails struct {
	ReasoningTokens          *int `json:"reasoning_tokens"`
	AudioTokens              *int `json:"audio_tokens"`
	AcceptedPredictionTokens *int `json:"accepted_prediction_tokens"`
	RejectedPredictionTokens *int `json:"rejected_prediction_tokens"`
}

ChatCompletionTokensDetails represents the breakdown of tokens generated by the model, including the accepted and rejected tokens of a prediction.

type ChatContent added in v1.0.0 

type ChatContent struct {
	Text  string
	Parts []ChatContentPart
}

ChatContent represents the content of a message, encoded either as a plain string or as a list of content parts. Parts takes precedence over Text when both are set.

func (ChatContent) MarshalJSON added in v1.0.0 

func (cc ChatContent) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface for ChatContent.

func (ChatContent) String added in v1.0.0 

func (cc ChatContent) String() string

String returns the text of the content, joining every text part if it is encoded as content parts. Non-text parts are skipped.

func (*ChatContent) UnmarshalJSON added in v1.0.0 

func (cc *ChatContent) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface for ChatContent.

type ChatContentFile added in v1.0.0 

type ChatContentFile struct {
	FileData string `json:"file_data,omitempty"`
	FileID   string `json:"file_id,omitempty"`
	Filename string `json:"filename,omitempty"`
}

ChatContentFile holds the document of a file content part, either inline as a base64 data url or url, or by the id of a previously uploaded file.

type ChatContentImageURL added in v1.0.0 

type ChatContentImageURL struct {
	URL    string          `json:"url"`
	Detail ChatImageDetail `json:"detail,omitempty"`
}

ChatContentImageURL holds the url of an image content part, as a base64 data url or an HTTP(S) url.

type ChatContentInputAudio added in v1.0.0 

type ChatContentInputAudio struct {
	Data   string `json:"data"`
	Format string `json:"format"`
}

ChatContentInputAudio holds the base64 encoded audio of an audio content part. The supported formats (wav, mp3, flac, m4a, ogg, aiff, aac, pcm16, pcm24) vary by provider.

type ChatContentPart added in v1.0.0 

type ChatContentPart struct {
	Type                  ChatContentPartType        `json:"type"`
	Text                  string                     `json:"text,omitempty"`
	ImageURL              *ChatContentImageURL       `json:"image_url,omitempty"`
	InputAudio            *ChatContentInputAudio     `json:"input_audio,omitempty"`
	VideoURL              *ChatContentVideoURL       `json:"video_url,omitempty"`
	File                  *ChatContentFile           `json:"file,omitempty"`
	CacheControl          *AnthropicCacheControl     `json:"cache_control,omitempty"`
	PromptCacheBreakpoint *ChatPromptCacheBreakpoint `json:"prompt_cache_breakpoint,omitempty"`
}

ChatContentPart represents a single content part of a message. Type determines which of the remaining fields are used.

type ChatContentPartType added in v1.0.0 

type ChatContentPartType string

ChatContentPartType is the type of a message content part. 

const (
	ChatContentPartTypeText       ChatContentPartType = "text"
	ChatContentPartTypeImageURL   ChatContentPartType = "image_url"
	ChatContentPartTypeInputAudio ChatContentPartType = "input_audio"
	ChatContentPartTypeVideoURL   ChatContentPartType = "video_url"
	ChatContentPartTypeFile       ChatContentPartType = "file"

	// Deprecated: use ChatContentPartTypeVideoURL instead.
	ChatContentPartTypeInputVideo ChatContentPartType = "input_video"
)

type ChatContentVideoURL added in v1.0.0 

type ChatContentVideoURL struct {
	URL string `json:"url"`
}

ChatContentVideoURL holds the url of a video content part, as a base64 data url or an HTTP(S) url.

type ChatContextCompressionEngine added in v1.0.0 

type ChatContextCompressionEngine string

ChatContextCompressionEngine is the engine used to compress the context. 

const (
	ChatContextCompressionEngineMiddleOut ChatContextCompressionEngine = "middle-out"
)

type ChatContextCompressionPlugin added in v1.0.0 

type ChatContextCompressionPlugin struct {
	ID      ChatPluginID                 `json:"id"`
	Enabled *bool                        `json:"enabled,omitempty"`
	Engine  ChatContextCompressionEngine `json:"engine,omitempty"`
}

ChatContextCompressionPlugin represents the context-compression plugin.

type ChatCostTier added in v1.0.0 

type ChatCostTier string

ChatCostTier is the named cost and quality setting of a router plugin. 

const (
	ChatCostTierLow    ChatCostTier = "low"
	ChatCostTierMedium ChatCostTier = "medium"
	ChatCostTierHigh   ChatCostTier = "high"
	ChatCostTierXHigh  ChatCostTier = "xhigh"
	ChatCostTierMax    ChatCostTier = "max"
)

type ChatDatetimeTool added in v1.0.0 

type ChatDatetimeTool struct {
	Type       ChatToolType            `json:"type"`
	Parameters *ChatDatetimeToolConfig `json:"parameters,omitempty"`
}

ChatDatetimeTool represents the built-in datetime server tool, returning the current date and time.

type ChatDatetimeToolConfig added in v1.0.0 

type ChatDatetimeToolConfig struct {
	Timezone string `json:"timezone,omitempty"`
}

ChatDatetimeToolConfig holds the configuration of the datetime server tool. Timezone is an IANA timezone name and defaults to UTC.

type ChatDebugOptions added in v1.0.0 

type ChatDebugOptions struct {
	EchoUpstreamBody bool `json:"echo_upstream_body,omitempty"`
}

ChatDebugOptions holds the debug options of a request. They only take effect on streaming requests.

type ChatErrorType added in v1.0.0 

type ChatErrorType string

ChatErrorType is the canonical OpenRouter error type of a streaming error, it is stable across all api formats. 

const (
	ChatErrorTypeContextLengthExceeded  ChatErrorType = "context_length_exceeded"
	ChatErrorTypeMaxTokensExceeded      ChatErrorType = "max_tokens_exceeded"
	ChatErrorTypeTokenLimitExceeded     ChatErrorType = "token_limit_exceeded"
	ChatErrorTypeStringTooLong          ChatErrorType = "string_too_long"
	ChatErrorTypeAuthentication         ChatErrorType = "authentication"
	ChatErrorTypePermissionDenied       ChatErrorType = "permission_denied"
	ChatErrorTypePaymentRequired        ChatErrorType = "payment_required"
	ChatErrorTypeRateLimitExceeded      ChatErrorType = "rate_limit_exceeded"
	ChatErrorTypeProviderOverloaded     ChatErrorType = "provider_overloaded"
	ChatErrorTypeProviderUnavailable    ChatErrorType = "provider_unavailable"
	ChatErrorTypeInvalidRequest         ChatErrorType = "invalid_request"
	ChatErrorTypeInvalidPrompt          ChatErrorType = "invalid_prompt"
	ChatErrorTypeNotFound               ChatErrorType = "not_found"
	ChatErrorTypePreconditionFailed     ChatErrorType = "precondition_failed"
	ChatErrorTypePayloadTooLarge        ChatErrorType = "payload_too_large"
	ChatErrorTypeUnprocessable          ChatErrorType = "unprocessable"
	ChatErrorTypeContentPolicyViolation ChatErrorType = "content_policy_violation"
	ChatErrorTypeRefusal                ChatErrorType = "refusal"
	ChatErrorTypeInvalidImage           ChatErrorType = "invalid_image"
	ChatErrorTypeImageTooLarge          ChatErrorType = "image_too_large"
	ChatErrorTypeImageTooSmall          ChatErrorType = "image_too_small"
	ChatErrorTypeUnsupportedImageFormat ChatErrorType = "unsupported_image_format"
	ChatErrorTypeImageNotFound          ChatErrorType = "image_not_found"
	ChatErrorTypeImageDownloadFailed    ChatErrorType = "image_download_failed"
	ChatErrorTypeServer                 ChatErrorType = "server"
	ChatErrorTypeTimeout                ChatErrorType = "timeout"
	ChatErrorTypeUnmapped               ChatErrorType = "unmapped"
)

type ChatFileParserPlugin added in v1.0.0 

type ChatFileParserPlugin struct {
	ID      ChatPluginID          `json:"id"`
	Enabled *bool                 `json:"enabled,omitempty"`
	PDF     *ChatPDFParserOptions `json:"pdf,omitempty"`
}

ChatFileParserPlugin represents the file-parser plugin.

type ChatFilesTool added in v1.0.0 

type ChatFilesTool struct {
	Type       ChatToolType         `json:"type"`
	Parameters *ChatFilesToolConfig `json:"parameters,omitempty"`
}

ChatFilesTool represents the built-in files server tool, reading, writing, editing and listing workspace files. It requires the x-openrouter-file-ids request header.

type ChatFilesToolConfig added in v1.0.0 

type ChatFilesToolConfig struct{}

ChatFilesToolConfig holds the configuration of the files server tool.

type ChatFinishReason added in v1.0.0 

type ChatFinishReason string

ChatFinishReason is the reason a completion stopped. 

const (
	ChatFinishReasonToolCalls     ChatFinishReason = "tool_calls"
	ChatFinishReasonStop          ChatFinishReason = "stop"
	ChatFinishReasonLength        ChatFinishReason = "length"
	ChatFinishReasonContentFilter ChatFinishReason = "content_filter"
	ChatFinishReasonError         ChatFinishReason = "error"
)

type ChatFunction added in v1.0.0 

type ChatFunction struct {
	Name        string         `json:"name"`
	Description string         `json:"description,omitempty"`
	Parameters  map[string]any `json:"parameters,omitempty"`
	Strict      *bool          `json:"strict,omitempty"`
}

ChatFunction represents the definition of a callable function. Name is limited to 64 characters of a-z, A-Z, 0-9, underscores and dashes.

type ChatFunctionTool added in v1.0.0 

type ChatFunctionTool struct {
	Type         ChatToolType           `json:"type"`
	Function     ChatFunction           `json:"function"`
	CacheControl *AnthropicCacheControl `json:"cache_control,omitempty"`
}

ChatFunctionTool represents a regular function tool.

type ChatFusionPlugin added in v1.0.0 

type ChatFusionPlugin struct {
	ID             ChatPluginID     `json:"id"`
	AnalysisModels []string         `json:"analysis_models,omitempty"`
	Enabled        *bool            `json:"enabled,omitempty"`
	MaxToolCalls   *int             `json:"max_tool_calls,omitempty"`
	Model          string           `json:"model,omitempty"`
	Preset         ChatFusionPreset `json:"preset,omitempty"`
	Tools          []ChatNestedTool `json:"tools,omitempty"`
}

ChatFusionPlugin represents the fusion plugin, running an expert panel of models and synthesizing their answers. At most 8 analysis models are accepted, MaxToolCalls defaults to 8 and is capped at 16.

type ChatFusionPreset added in v1.0.0 

type ChatFusionPreset string

ChatFusionPreset is a curated panel and analyst configuration of the fusion plugin. 

const (
	ChatFusionPresetGeneralHigh   ChatFusionPreset = "general-high"
	ChatFusionPresetGeneralBudget ChatFusionPreset = "general-budget"
	ChatFusionPresetGeneralFast   ChatFusionPreset = "general-fast"
)

type ChatFusionTool added in v1.0.0 

type ChatFusionTool struct {
	Type       ChatToolType          `json:"type"`
	Parameters *ChatFusionToolConfig `json:"parameters,omitempty"`
}

ChatFusionTool represents the built-in fusion server tool, fanning the prompt out to a panel of analysis models and summarizing their output.

type ChatFusionToolConfig added in v1.0.0 

type ChatFusionToolConfig struct {
	AnalysisModels      []string               `json:"analysis_models,omitempty"`
	CacheControl        *AnthropicCacheControl `json:"cache_control,omitempty"`
	MaxCompletionTokens *int                   `json:"max_completion_tokens,omitempty"`
	MaxToolCalls        *int                   `json:"max_tool_calls,omitempty"`
	Model               string                 `json:"model,omitempty"`
	Reasoning           *ChatToolReasoning     `json:"reasoning,omitempty"`
	Temperature         *float64               `json:"temperature,omitempty"`
	Tools               []ChatNestedTool       `json:"tools,omitempty"`
}

ChatFusionToolConfig holds the configuration of the fusion server tool. At most 8 analysis models are accepted, MaxToolCalls is capped at 16.

type ChatImageConfig added in v1.0.0 

type ChatImageConfig map[string]any

ChatImageConfig holds provider specific image generation options keyed by option name (aspect_ratio, quality, size, ...). Unrecognized keys are forwarded as-is and ignored by providers that do not support them.

type ChatImageDetail added in v1.0.0 

type ChatImageDetail string

ChatImageDetail is the detail level an image content part is processed with. Original is an OpenRouter extension requesting true original-resolution media, it is downgraded to high for providers without such a tier. 

const (
	ChatImageDetailAuto     ChatImageDetail = "auto"
	ChatImageDetailLow      ChatImageDetail = "low"
	ChatImageDetailHigh     ChatImageDetail = "high"
	ChatImageDetailOriginal ChatImageDetail = "original"
)

type ChatImageGenerationTool added in v1.0.0 

type ChatImageGenerationTool struct {
	Type       ChatToolType                  `json:"type"`
	Parameters ChatImageGenerationToolConfig `json:"parameters,omitempty"`
}

ChatImageGenerationTool represents the built-in image generation server tool.

type ChatImageGenerationToolConfig added in v1.0.0 

type ChatImageGenerationToolConfig map[string]any

ChatImageGenerationToolConfig holds the configuration of the image generation server tool. It accepts every ChatImageConfig option plus a "model" key, which defaults to openai/gpt-5-image.

type ChatJSONSchema added in v1.0.0 

type ChatJSONSchema struct {
	Name        string         `json:"name"`
	Description string         `json:"description,omitempty"`
	Schema      map[string]any `json:"schema,omitempty"`
	Strict      *bool          `json:"strict,omitempty"`
}

ChatJSONSchema represents the schema of a json_schema response format. Name is required and limited to 64 characters of a-z, A-Z, 0-9, underscores and dashes.

type ChatLogprobs added in v1.0.0 

type ChatLogprobs struct {
	Content []ChatTokenLogprob `json:"content"`
	Refusal []ChatTokenLogprob `json:"refusal"`
}

ChatLogprobs represents the log probabilities of a completion.

type ChatMessage added in v1.0.0 

type ChatMessage struct {
	Role    ChatRole    `json:"role"`
	Content ChatContent `json:"content,omitzero"`
	Name    string      `json:"name,omitempty"`

	Audio            *ChatAudioOutput      `json:"audio,omitempty"`
	Images           []ChatAssistantImage  `json:"images,omitempty"`
	Model            string                `json:"model,omitempty"`
	Reasoning        string                `json:"reasoning,omitempty"`
	ReasoningDetails []ChatReasoningDetail `json:"reasoning_details,omitempty"`
	Refusal          string                `json:"refusal,omitempty"`
	ToolCalls        []ChatToolCall        `json:"tool_calls,omitempty"`

	ToolCallID string `json:"tool_call_id,omitempty"`
}

ChatMessage represents a single message of a conversation, for both requests and responses. Role determines which of the remaining fields are meaningful: Content and Name for system, developer and user messages, Content and ToolCallID for tool messages, everything else for assistant messages.

func AssistantMessage added in v1.0.1 

func AssistantMessage(content string) ChatMessage

AssistantMessage creates a new assistant message with the given text content.

func SystemMessage added in v1.0.1 

func SystemMessage(content string) ChatMessage

SystemMessage creates a new system message with the given text content.

func ToolMessage added in v1.0.1 

func ToolMessage(callID string, content string) ChatMessage

ToolMessage creates a new tool (response) message with a call ID and content.

func UserMessage added in v1.0.1 

func UserMessage(content string) ChatMessage

UserMessage creates a new user message with the given text content.

func UserMessageWithImage added in v1.0.1 

func UserMessageWithImage(text, imageURL string) ChatMessage

UserMessageWithImage creates a new user message with text and image URL.

type ChatMetadataLevel added in v1.0.0 

type ChatMetadataLevel string

ChatMetadataLevel is the opt-in level for surfacing routing metadata on the response. 

const (
	ChatMetadataLevelDisabled ChatMetadataLevel = "disabled"
	ChatMetadataLevelEnabled  ChatMetadataLevel = "enabled"
)

type ChatModerationPlugin added in v1.0.0 

type ChatModerationPlugin struct {
	ID ChatPluginID `json:"id"`
}

ChatModerationPlugin represents the moderation plugin.

type ChatNestedTool added in v1.0.0 

type ChatNestedTool struct {
	Type       ChatToolType   `json:"type"`
	Parameters map[string]any `json:"parameters,omitempty"`
}

ChatNestedTool represents a tool made available to the inner calls of an advisor, subagent or fusion server tool. Only OpenRouter server tools are supported, function tools are rejected.

type ChatObject added in v1.0.0 

type ChatObject string

ChatObject is the object type of a chat completion response or chunk. 

const (
	ChatObjectCompletion      ChatObject = "chat.completion"
	ChatObjectCompletionChunk ChatObject = "chat.completion.chunk"
)

type ChatPDFParserEngine added in v1.0.0 

type ChatPDFParserEngine string

ChatPDFParserEngine is the engine used to parse pdf files. 

const (
	ChatPDFParserEngineMistralOCR   ChatPDFParserEngine = "mistral-ocr"
	ChatPDFParserEngineNative       ChatPDFParserEngine = "native"
	ChatPDFParserEngineCloudflareAI ChatPDFParserEngine = "cloudflare-ai"

	// Deprecated: automatically redirected to ChatPDFParserEngineCloudflareAI.
	ChatPDFParserEnginePDFText ChatPDFParserEngine = "pdf-text"
)

type ChatPDFParserOptions added in v1.0.0 

type ChatPDFParserOptions struct {
	Engine ChatPDFParserEngine `json:"engine,omitempty"`
}

ChatPDFParserOptions holds the pdf parsing options of the file-parser plugin.

type ChatParetoPriceSource added in v1.0.0 

type ChatParetoPriceSource string

ChatParetoPriceSource is the price used as the cost axis of the pareto router. 

const (
	ChatParetoPriceSourcePrompt      ChatParetoPriceSource = "prompt"
	ChatParetoPriceSourceWeightedAvg ChatParetoPriceSource = "weighted_avg"
)

type ChatParetoRouterPlugin added in v1.0.0 

type ChatParetoRouterPlugin struct {
	ID             ChatPluginID          `json:"id"`
	Enabled        *bool                 `json:"enabled,omitempty"`
	MaxPrice       *float64              `json:"max_price,omitempty"`
	MinCodingScore *float64              `json:"min_coding_score,omitempty"`
	PriceSource    ChatParetoPriceSource `json:"price_source,omitempty"`
}

ChatParetoRouterPlugin represents the pareto-router plugin. MaxPrice is in USD per million tokens and bypasses MinCodingScore when set.

type ChatPlugin added in v1.0.0 

type ChatPlugin interface {
	// contains filtered or unexported methods
}

ChatPlugin is implemented by every plugin configuration that can be enabled on a chat completion request.

type ChatPluginID added in v1.0.0 

type ChatPluginID string

ChatPluginID is the identifier of a plugin. 

const (
	ChatPluginIDAutoRouter         ChatPluginID = "auto-router"
	ChatPluginIDAutoBetaRouter     ChatPluginID = "auto-beta-router"
	ChatPluginIDModeration         ChatPluginID = "moderation"
	ChatPluginIDWeb                ChatPluginID = "web"
	ChatPluginIDWebFetch           ChatPluginID = "web-fetch"
	ChatPluginIDFileParser         ChatPluginID = "file-parser"
	ChatPluginIDResponseHealing    ChatPluginID = "response-healing"
	ChatPluginIDContextCompression ChatPluginID = "context-compression"
	ChatPluginIDParetoRouter       ChatPluginID = "pareto-router"
	ChatPluginIDFusion             ChatPluginID = "fusion"
)

type ChatPrediction added in v1.0.0 

type ChatPrediction struct {
	Type    ChatPredictionType `json:"type"`
	Content ChatContent        `json:"content"`
}

ChatPrediction represents static predicted output content. Supported models use it to reduce latency when much of the response is known in advance.

type ChatPredictionType added in v1.0.0 

type ChatPredictionType string

ChatPredictionType is the type of a predicted output. 

const (
	ChatPredictionTypeContent ChatPredictionType = "content"
)

type ChatPromptCacheBreakpoint added in v1.0.0 

type ChatPromptCacheBreakpoint struct {
	Mode ChatPromptCacheMode `json:"mode"`
}

ChatPromptCacheBreakpoint marks an explicit prompt cache boundary on a content block. Everything through the block carrying the marker is part of the candidate cached prefix. It is interchangeable with AnthropicCacheControl, OpenRouter converts between the two based on the serving provider.

type ChatPromptCacheMode added in v1.0.0 

type ChatPromptCacheMode string

ChatPromptCacheMode is the prompt caching mode of a request or content block. 

const (
	ChatPromptCacheModeExplicit ChatPromptCacheMode = "explicit"
)

type ChatPromptCacheOptions added in v1.0.0 

type ChatPromptCacheOptions struct {
	Mode ChatPromptCacheMode `json:"mode"`
	TTL  string              `json:"ttl,omitempty"`
}

ChatPromptCacheOptions represents the request level prompt cache controls. ChatPromptCacheModeExplicit disables provider managed breakpoints so only blocks marked with a ChatPromptCacheBreakpoint are cached. Only supported by OpenAI GPT-5.6 and newer.

type ChatReasoningConfig added in v1.0.0 

type ChatReasoningConfig struct {
	Effort  ReasoningEffort      `json:"effort,omitempty"`
	Summary ChatReasoningSummary `json:"summary,omitempty"`
}

ChatReasoningConfig represents the reasoning configuration of a request. Effort cannot differ from the shorthand ChatCompletionRequest.ReasoningEffort.

type ChatReasoningDetail added in v1.0.0 

type ChatReasoningDetail struct {
	Type       ChatReasoningDetailType `json:"type"`
	ID         string                  `json:"id,omitempty"`
	Index      int                     `json:"index,omitempty"`
	Format     ChatReasoningFormat     `json:"format,omitempty"`
	Summary    string                  `json:"summary,omitempty"`
	Data       string                  `json:"data,omitempty"`
	Text       string                  `json:"text,omitempty"`
	Signature  string                  `json:"signature,omitempty"`
	ToolName   string                  `json:"tool_name,omitempty"`
	Arguments  string                  `json:"arguments,omitempty"`
	Result     string                  `json:"result,omitempty"`
	ToolCallID string                  `json:"tool_call_id,omitempty"`
}

ChatReasoningDetail represents a single reasoning detail of an extended thinking model. Type determines which of the remaining fields are populated: Summary for summaries, Data for encrypted reasoning, Text and Signature for text and ToolName, Arguments, Result and ToolCallID for server tool calls.

type ChatReasoningDetailType added in v1.0.0 

type ChatReasoningDetailType string

ChatReasoningDetailType is the type of a reasoning detail. 

const (
	ChatReasoningDetailTypeSummary        ChatReasoningDetailType = "reasoning.summary"
	ChatReasoningDetailTypeEncrypted      ChatReasoningDetailType = "reasoning.encrypted"
	ChatReasoningDetailTypeText           ChatReasoningDetailType = "reasoning.text"
	ChatReasoningDetailTypeServerToolCall ChatReasoningDetailType = "reasoning.server_tool_call"
)

type ChatReasoningFormat added in v1.0.0 

type ChatReasoningFormat string

ChatReasoningFormat is the upstream format a reasoning detail was produced in. 

const (
	ChatReasoningFormatUnknown                  ChatReasoningFormat = "unknown"
	ChatReasoningFormatOpenAIResponsesV1        ChatReasoningFormat = "openai-responses-v1"
	ChatReasoningFormatAzureOpenAIResponsesV1   ChatReasoningFormat = "azure-openai-responses-v1"
	ChatReasoningFormatBedrockOpenAIResponsesV1 ChatReasoningFormat = "bedrock-openai-responses-v1"
	ChatReasoningFormatXAIResponsesV1           ChatReasoningFormat = "xai-responses-v1"
	ChatReasoningFormatMetaResponsesV1          ChatReasoningFormat = "meta-responses-v1"
	ChatReasoningFormatAnthropicClaudeV1        ChatReasoningFormat = "anthropic-claude-v1"
	ChatReasoningFormatGoogleGeminiV1           ChatReasoningFormat = "google-gemini-v1"
)

type ChatReasoningSummary added in v1.0.0 

type ChatReasoningSummary string

ChatReasoningSummary is the verbosity of the reasoning summary of a request. 

const (
	ChatReasoningSummaryAuto     ChatReasoningSummary = "auto"
	ChatReasoningSummaryConcise  ChatReasoningSummary = "concise"
	ChatReasoningSummaryDetailed ChatReasoningSummary = "detailed"
)

type ChatResponseFormat added in v1.0.0 

type ChatResponseFormat struct {
	Type       ChatResponseFormatType `json:"type"`
	JSONSchema *ChatJSONSchema        `json:"json_schema,omitempty"`
	Grammar    string                 `json:"grammar,omitempty"`
}

ChatResponseFormat represents the response format configuration of a request. Type determines which of the remaining fields are used: JSONSchema for json_schema, Grammar for grammar, none for text, json_object and python.

type ChatResponseFormatType added in v1.0.0 

type ChatResponseFormatType string

ChatResponseFormatType is the type of a response format configuration. 

const (
	ChatResponseFormatTypeText       ChatResponseFormatType = "text"
	ChatResponseFormatTypeJSONObject ChatResponseFormatType = "json_object"
	ChatResponseFormatTypeJSONSchema ChatResponseFormatType = "json_schema"
	ChatResponseFormatTypeGrammar    ChatResponseFormatType = "grammar"
	ChatResponseFormatTypePython     ChatResponseFormatType = "python"
)

type ChatResponseHealingPlugin added in v1.0.0 

type ChatResponseHealingPlugin struct {
	ID      ChatPluginID `json:"id"`
	Enabled *bool        `json:"enabled,omitempty"`
}

ChatResponseHealingPlugin represents the response-healing plugin.

type ChatRole added in v1.0.0 

type ChatRole string

ChatRole is the role of the author of a message. 

const (
	ChatRoleSystem    ChatRole = "system"
	ChatRoleDeveloper ChatRole = "developer"
	ChatRoleUser      ChatRole = "user"
	ChatRoleAssistant ChatRole = "assistant"
	ChatRoleTool      ChatRole = "tool"
)

type ChatRoute deprecated added in v1.0.0 

type ChatRoute string

ChatRoute is the legacy alias of ProviderSortConfig.Partition.

Deprecated: use ProviderPreferences.Sort.Partition instead. 

const (
	// Deprecated: use ProviderSortPartitionModel instead.
	ChatRouteFallback ChatRoute = "fallback"
	// Deprecated: use ProviderSortPartitionNone instead.
	ChatRouteSort ChatRoute = "sort"
)

type ChatSearchContextSize added in v1.0.0 

type ChatSearchContextSize string

ChatSearchContextSize is how much context is retrieved per search result. It is overridden by an explicit character cap. 

const (
	ChatSearchContextSizeLow    ChatSearchContextSize = "low"
	ChatSearchContextSizeMedium ChatSearchContextSize = "medium"
	ChatSearchContextSizeHigh   ChatSearchContextSize = "high"
)

type ChatSearchModelsTool added in v1.0.0 

type ChatSearchModelsTool struct {
	Type       ChatToolType                `json:"type"`
	Parameters *ChatSearchModelsToolConfig `json:"parameters,omitempty"`
}

ChatSearchModelsTool represents the built-in experimental search models server tool, searching and filtering the models available on OpenRouter.

type ChatSearchModelsToolConfig added in v1.0.0 

type ChatSearchModelsToolConfig struct {
	MaxResults *int `json:"max_results,omitempty"`
}

ChatSearchModelsToolConfig holds the configuration of the search models server tool. MaxResults defaults to 5 and is capped at 20.

type ChatServiceTier added in v1.0.0 

type ChatServiceTier string

ChatServiceTier is the service tier a request is processed with. 

const (
	ChatServiceTierAuto     ChatServiceTier = "auto"
	ChatServiceTierDefault  ChatServiceTier = "default"
	ChatServiceTierFlex     ChatServiceTier = "flex"
	ChatServiceTierPriority ChatServiceTier = "priority"
	ChatServiceTierScale    ChatServiceTier = "scale"
)

type ChatStopCondition added in v1.0.0 

type ChatStopCondition struct {
	Type             ChatStopConditionType `json:"type"`
	StepCount        *int                  `json:"step_count,omitempty"`
	ToolName         string                `json:"tool_name,omitempty"`
	MaxTokens        *int                  `json:"max_tokens,omitempty"`
	MaxCostInDollars *float64              `json:"max_cost_in_dollars,omitempty"`
	Reason           string                `json:"reason,omitempty"`
}

ChatStopCondition represents a single stop condition of the server tool agent loop. Any condition firing halts the loop. Type determines which of the remaining fields are used.

type ChatStopConditionType added in v1.0.0 

type ChatStopConditionType string

ChatStopConditionType is the type of a server tool stop condition. 

const (
	ChatStopConditionTypeStepCountIs    ChatStopConditionType = "step_count_is"
	ChatStopConditionTypeHasToolCall    ChatStopConditionType = "has_tool_call"
	ChatStopConditionTypeMaxTokensUsed  ChatStopConditionType = "max_tokens_used"
	ChatStopConditionTypeMaxCost        ChatStopConditionType = "max_cost"
	ChatStopConditionTypeFinishReasonIs ChatStopConditionType = "finish_reason_is"
)

type ChatStreamChoice added in v1.0.0 

type ChatStreamChoice struct {
	Index        int              `json:"index"`
	FinishReason ChatFinishReason `json:"finish_reason"`
	Delta        ChatStreamDelta  `json:"delta"`
	Logprobs     *ChatLogprobs    `json:"logprobs,omitempty"`
}

ChatStreamChoice represents a single choice of a streaming chunk.

type ChatStreamChunk added in v1.0.0 

type ChatStreamChunk struct {
	ID                 string              `json:"id"`
	Object             ChatObject          `json:"object"`
	Created            int64               `json:"created"`
	Model              string              `json:"model"`
	Choices            []ChatStreamChoice  `json:"choices"`
	SystemFingerprint  string              `json:"system_fingerprint,omitempty"`
	ServiceTier        *string             `json:"service_tier,omitempty"`
	Usage              *ChatUsage          `json:"usage,omitempty"`
	OpenRouterMetadata *OpenRouterMetadata `json:"openrouter_metadata,omitempty"`
	Error              *ChatStreamError    `json:"error,omitempty"`
}

ChatStreamChunk represents a single chunk of a streaming chat completion. Error is populated when the request failed after the response started.

type ChatStreamDelta added in v1.0.0 

type ChatStreamDelta struct {
	Role             ChatRole              `json:"role,omitempty"`
	Content          string                `json:"content,omitempty"`
	Reasoning        string                `json:"reasoning,omitempty"`
	ReasoningDetails []ChatReasoningDetail `json:"reasoning_details,omitempty"`
	Refusal          string                `json:"refusal,omitempty"`
	Audio            *ChatAudioOutput      `json:"audio,omitempty"`
	Images           []ChatAssistantImage  `json:"images,omitempty"`
	ToolCalls        []ChatStreamToolCall  `json:"tool_calls,omitempty"`
}

ChatStreamDelta represents the incremental changes of a streaming choice.

type ChatStreamError added in v1.0.0 

type ChatStreamError struct {
	Message  string                   `json:"message"`
	Code     int64                    `json:"code"`
	Metadata *ChatStreamErrorMetadata `json:"metadata,omitempty"`
}

ChatStreamError represents the error details of a streaming completion that failed after the response started.

func (*ChatStreamError) Error added in v1.0.0 

func (e *ChatStreamError) Error() string

Error returns the formatted string representation of the streaming chat error.

type ChatStreamErrorMetadata added in v1.0.0 

type ChatStreamErrorMetadata struct {
	ErrorType    ChatErrorType `json:"error_type"`
	ProviderCode string        `json:"provider_code,omitempty"`
}

ChatStreamErrorMetadata represents the structured metadata of a streaming error.

type ChatStreamOptions added in v1.0.0 

type ChatStreamOptions struct {
	// Deprecated: this field has no effect, full usage details are always
	// included.
	IncludeUsage *bool `json:"include_usage,omitempty"`
}

ChatStreamOptions holds the streaming options of a request.

type ChatStreamToolCall added in v1.0.0 

type ChatStreamToolCall struct {
	Index    int                         `json:"index"`
	ID       string                      `json:"id,omitempty"`
	Type     ChatToolType                `json:"type,omitempty"`
	Function *ChatStreamToolCallFunction `json:"function,omitempty"`
}

ChatStreamToolCall represents the delta of a tool call. Index identifies the tool call the delta belongs to, the remaining fields are only sent once the provider knows them.

type ChatStreamToolCallFunction added in v1.0.0 

type ChatStreamToolCallFunction struct {
	Name      string `json:"name,omitempty"`
	Arguments string `json:"arguments,omitempty"`
}

ChatStreamToolCallFunction holds the name and json encoded argument delta of a streamed tool call.

type ChatSubagentTool added in v1.0.0 

type ChatSubagentTool struct {
	Type       ChatToolType            `json:"type"`
	Parameters *ChatSubagentToolConfig `json:"parameters,omitempty"`
}

ChatSubagentTool represents the built-in subagent server tool, delegating self-contained tasks to a smaller, cheaper worker model.

type ChatSubagentToolConfig added in v1.0.0 

type ChatSubagentToolConfig struct {
	Instructions        string             `json:"instructions,omitempty"`
	MaxCompletionTokens *int               `json:"max_completion_tokens,omitempty"`
	MaxToolCalls        *int               `json:"max_tool_calls,omitempty"`
	Model               string             `json:"model,omitempty"`
	Name                string             `json:"name,omitempty"`
	Reasoning           *ChatToolReasoning `json:"reasoning,omitempty"`
	Temperature         *float64           `json:"temperature,omitempty"`
	Tools               []ChatNestedTool   `json:"tools,omitempty"`
}

ChatSubagentToolConfig holds the configuration of a single subagent server tool entry.

type ChatTokenLogprob added in v1.0.0 

type ChatTokenLogprob struct {
	Token       string           `json:"token"`
	Logprob     float64          `json:"logprob"`
	Bytes       []int            `json:"bytes"`
	TopLogprobs []ChatTopLogprob `json:"top_logprobs"`
}

ChatTokenLogprob represents the log probability of a single token.

type ChatTool added in v1.0.0 

type ChatTool interface {
	// contains filtered or unexported methods
}

ChatTool is implemented by every tool definition of a chat completion request, both regular function tools and OpenRouter built-in server tools.

type ChatToolCall added in v1.0.0 

type ChatToolCall struct {
	ID       string               `json:"id"`
	Type     ChatToolType         `json:"type"`
	Function ChatToolCallFunction `json:"function"`
}

ChatToolCall represents a tool call made by the assistant.

type ChatToolCallFunction added in v1.0.0 

type ChatToolCallFunction struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

ChatToolCallFunction holds the name and json encoded arguments of a tool call.

type ChatToolChoice added in v1.0.0 

type ChatToolChoice struct {
	Mode     ChatToolChoiceMode      `json:"-"`
	Type     ChatToolType            `json:"type,omitempty"`
	Function *ChatToolChoiceFunction `json:"function,omitempty"`
}

ChatToolChoice represents the tool choice configuration of a request. Mode encodes the plain "none", "auto" and "required" choices and takes precedence, otherwise Type and Function name the tool to force.

func (ChatToolChoice) MarshalJSON added in v1.0.0 

func (tc ChatToolChoice) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface for ChatToolChoice.

type ChatToolChoiceFunction added in v1.0.0 

type ChatToolChoiceFunction struct {
	Name string `json:"name"`
}

ChatToolChoiceFunction holds the name of the function a named tool choice forces.

type ChatToolChoiceMode added in v1.0.0 

type ChatToolChoiceMode string

ChatToolChoiceMode is a plain tool choice, without naming a specific tool. 

const (
	ChatToolChoiceModeNone     ChatToolChoiceMode = "none"
	ChatToolChoiceModeAuto     ChatToolChoiceMode = "auto"
	ChatToolChoiceModeRequired ChatToolChoiceMode = "required"
)

type ChatToolReasoning added in v1.0.0 

type ChatToolReasoning struct {
	Effort    ReasoningEffort `json:"effort,omitempty"`
	MaxTokens *int            `json:"max_tokens,omitempty"`
}

ChatToolReasoning represents the reasoning configuration forwarded to the inner calls of an advisor, subagent or fusion server tool.

type ChatToolType added in v1.0.0 

type ChatToolType string

ChatToolType is the type of a tool definition, tool call or forced tool choice. 

const (
	ChatToolTypeFunction        ChatToolType = "function"
	ChatToolTypeAdvisor         ChatToolType = "openrouter:advisor"
	ChatToolTypeBash            ChatToolType = "openrouter:bash"
	ChatToolTypeDatetime        ChatToolType = "openrouter:datetime"
	ChatToolTypeFiles           ChatToolType = "openrouter:files"
	ChatToolTypeFusion          ChatToolType = "openrouter:fusion"
	ChatToolTypeImageGeneration ChatToolType = "openrouter:image_generation"
	ChatToolTypeSearchModels    ChatToolType = "openrouter:experimental__search_models"
	ChatToolTypeSubagent        ChatToolType = "openrouter:subagent"
	ChatToolTypeWebFetch        ChatToolType = "openrouter:web_fetch"
	ChatToolTypeWebSearch       ChatToolType = "openrouter:web_search"

	ChatToolTypeWebSearchShorthand       ChatToolType = "web_search"
	ChatToolTypeWebSearchPreview         ChatToolType = "web_search_preview"
	ChatToolTypeWebSearchPreview20250311 ChatToolType = "web_search_preview_2025_03_11"
	ChatToolTypeWebSearch20250826        ChatToolType = "web_search_2025_08_26"
)

type ChatTopLogprob added in v1.0.0 

type ChatTopLogprob struct {
	Token   string  `json:"token"`
	Logprob float64 `json:"logprob"`
	Bytes   []int   `json:"bytes"`
}

ChatTopLogprob represents a single alternative token and its log probability.

type ChatTraceConfig added in v1.0.0 

type ChatTraceConfig struct {
	TraceID        string `json:"trace_id,omitempty"`
	TraceName      string `json:"trace_name,omitempty"`
	SpanName       string `json:"span_name,omitempty"`
	GenerationName string `json:"generation_name,omitempty"`
	ParentSpanID   string `json:"parent_span_id,omitempty"`
}

ChatTraceConfig holds the observability metadata of a request. The known keys receive special handling, they are forwarded to the configured broadcast destinations.

type ChatUsage added in v1.0.0 

type ChatUsage struct {
	PromptTokens            int                          `json:"prompt_tokens"`
	CompletionTokens        int                          `json:"completion_tokens"`
	TotalTokens             int                          `json:"total_tokens"`
	Cost                    *float64                     `json:"cost"`
	CostDetails             *CostDetails                 `json:"cost_details"`
	PromptTokensDetails     *PromptTokensDetails         `json:"prompt_tokens_details"`
	CompletionTokensDetails *ChatCompletionTokensDetails `json:"completion_tokens_details"`
	ServerToolUseDetails    *ServerToolUse               `json:"server_tool_use_details"`
	IsBYOK                  bool                         `json:"is_byok"`
}

ChatUsage represents the token and cost usage of a chat completion.

type ChatUserLocationType added in v1.0.0 

type ChatUserLocationType string

ChatUserLocationType is the precision of a web search user location. 

const (
	ChatUserLocationTypeApproximate ChatUserLocationType = "approximate"
)

type ChatWebFetchEngine added in v1.0.0 

type ChatWebFetchEngine string

ChatWebFetchEngine is the engine backing web fetch. 

const (
	ChatWebFetchEngineAuto       ChatWebFetchEngine = "auto"
	ChatWebFetchEngineNative     ChatWebFetchEngine = "native"
	ChatWebFetchEngineOpenRouter ChatWebFetchEngine = "openrouter"
	ChatWebFetchEngineExa        ChatWebFetchEngine = "exa"
	ChatWebFetchEngineParallel   ChatWebFetchEngine = "parallel"
	ChatWebFetchEngineFirecrawl  ChatWebFetchEngine = "firecrawl"
)

type ChatWebFetchPlugin added in v1.0.0 

type ChatWebFetchPlugin struct {
	ID               ChatPluginID `json:"id"`
	AllowedDomains   []string     `json:"allowed_domains,omitempty"`
	BlockedDomains   []string     `json:"blocked_domains,omitempty"`
	MaxContentTokens *int         `json:"max_content_tokens,omitempty"`
	MaxUses          *int         `json:"max_uses,omitempty"`
}

ChatWebFetchPlugin represents the web-fetch plugin.

type ChatWebFetchTool added in v1.0.0 

type ChatWebFetchTool struct {
	Type       ChatToolType            `json:"type"`
	Parameters *ChatWebFetchToolConfig `json:"parameters,omitempty"`
}

ChatWebFetchTool represents the built-in web fetch server tool, fetching the full content of a web page or PDF.

type ChatWebFetchToolConfig added in v1.0.0 

type ChatWebFetchToolConfig struct {
	AllowedDomains   []string           `json:"allowed_domains,omitempty"`
	BlockedDomains   []string           `json:"blocked_domains,omitempty"`
	Engine           ChatWebFetchEngine `json:"engine,omitempty"`
	MaxContentTokens *int               `json:"max_content_tokens,omitempty"`
	MaxUses          *int               `json:"max_uses,omitempty"`
}

ChatWebFetchToolConfig holds the configuration of the web fetch server tool.

type ChatWebSearchEngine added in v1.0.0 

type ChatWebSearchEngine string

ChatWebSearchEngine is the engine backing web search. Auto is only valid on server tool configurations, the web search plugin requires an explicit engine. 

const (
	ChatWebSearchEngineAuto       ChatWebSearchEngine = "auto"
	ChatWebSearchEngineNative     ChatWebSearchEngine = "native"
	ChatWebSearchEngineExa        ChatWebSearchEngine = "exa"
	ChatWebSearchEngineParallel   ChatWebSearchEngine = "parallel"
	ChatWebSearchEngineFirecrawl  ChatWebSearchEngine = "firecrawl"
	ChatWebSearchEnginePerplexity ChatWebSearchEngine = "perplexity"
)

type ChatWebSearchPlugin added in v1.0.0 

type ChatWebSearchPlugin struct {
	ID             ChatPluginID               `json:"id"`
	Enabled        *bool                      `json:"enabled,omitempty"`
	Engine         ChatWebSearchEngine        `json:"engine,omitempty"`
	ExcludeDomains []string                   `json:"exclude_domains,omitempty"`
	IncludeDomains []string                   `json:"include_domains,omitempty"`
	MaxResults     *int                       `json:"max_results,omitempty"`
	MaxUses        *int                       `json:"max_uses,omitempty"`
	SearchPrompt   string                     `json:"search_prompt,omitempty"`
	UserLocation   *ChatWebSearchUserLocation `json:"user_location,omitempty"`
}

ChatWebSearchPlugin represents the web search plugin.

type ChatWebSearchShorthandTool added in v1.0.0 

type ChatWebSearchShorthandTool struct {
	Type              ChatToolType               `json:"type"`
	AllowedDomains    []string                   `json:"allowed_domains,omitempty"`
	Engine            ChatWebSearchEngine        `json:"engine,omitempty"`
	ExcludedDomains   []string                   `json:"excluded_domains,omitempty"`
	MaxCharacters     *int                       `json:"max_characters,omitempty"`
	MaxResults        *int                       `json:"max_results,omitempty"`
	MaxTotalResults   *int                       `json:"max_total_results,omitempty"`
	MaxUses           *int                       `json:"max_uses,omitempty"`
	Parameters        *ChatWebSearchToolConfig   `json:"parameters,omitempty"`
	SearchContextSize ChatSearchContextSize      `json:"search_context_size,omitempty"`
	UserLocation      *ChatWebSearchUserLocation `json:"user_location,omitempty"`
}

ChatWebSearchShorthandTool represents a web search tool declared with the OpenAI Responses API syntax. It is converted to the built-in web search server tool, Parameters overrides the flattened options.

type ChatWebSearchTool added in v1.0.0 

type ChatWebSearchTool struct {
	Type       ChatToolType             `json:"type"`
	Parameters *ChatWebSearchToolConfig `json:"parameters,omitempty"`
}

ChatWebSearchTool represents the built-in web search server tool.

type ChatWebSearchToolConfig added in v1.0.0 

type ChatWebSearchToolConfig struct {
	AllowedDomains    []string                   `json:"allowed_domains,omitempty"`
	Engine            ChatWebSearchEngine        `json:"engine,omitempty"`
	ExcludedDomains   []string                   `json:"excluded_domains,omitempty"`
	MaxCharacters     *int                       `json:"max_characters,omitempty"`
	MaxResults        *int                       `json:"max_results,omitempty"`
	MaxTotalResults   *int                       `json:"max_total_results,omitempty"`
	MaxUses           *int                       `json:"max_uses,omitempty"`
	SearchContextSize ChatSearchContextSize      `json:"search_context_size,omitempty"`
	UserLocation      *ChatWebSearchUserLocation `json:"user_location,omitempty"`
}

ChatWebSearchToolConfig holds the configuration of the web search server tool. AllowedDomains and ExcludedDomains are mutually exclusive, MaxCharacters takes precedence over SearchContextSize.

type ChatWebSearchUserLocation added in v1.0.0 

type ChatWebSearchUserLocation struct {
	Type     ChatUserLocationType `json:"type"`
	City     string               `json:"city,omitempty"`
	Country  string               `json:"country,omitempty"`
	Region   string               `json:"region,omitempty"`
	Timezone string               `json:"timezone,omitempty"`
}

ChatWebSearchUserLocation represents the approximate user location used to bias search results.

type Client added in v1.0.0 

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

Client represents an OpenRouter API client.

func NewClient added in v1.0.0 

func NewClient(token string, options ...Option) *Client

NewClient returns a new client instance with the api token and options.

func (*Client) CreateChatCompletion added in v1.0.0 

func (c *Client) CreateChatCompletion(ctx context.Context, request ChatCompletionRequest) (*ChatCompletionResponse, error)

CreateChatCompletion sends a chat completion request and returns the response.

func (*Client) CreateChatCompletionStream added in v1.0.0 

func (c *Client) CreateChatCompletionStream(ctx context.Context, request ChatCompletionRequest) (OpenrouterStream[ChatStreamChunk], error)

CreateChatCompletionStream sends a streaming chat completion request and returns a stream of completion chunks.

func (*Client) CreateEmbeddings added in v1.0.0 

func (c *Client) CreateEmbeddings(ctx context.Context, request EmbeddingRequest) (*EmbeddingResponse, error)

CreateEmbeddings submits an embedding request and returns the response.

func (*Client) CreateSpeech added in v1.0.0 

func (c *Client) CreateSpeech(ctx context.Context, request SpeechRequest) (*SpeechResponse, error)

CreateSpeech synthesizes audio from the input text. The body of the returned response is not read or closed, closing it is up to the caller.

func (*Client) CreateTranscription added in v1.0.0 

func (c *Client) CreateTranscription(ctx context.Context, request STTRequest) (*STTResponse, error)

CreateTranscription transcribes audio into text.

func (*Client) Do added in v1.0.0 

func (c *Client) Do(req *http.Request) (*http.Response, error)

Do sends an HTTP request and processes any returned API errors.

func (*Client) GenerateImage added in v1.0.0 

func (c *Client) GenerateImage(ctx context.Context, request ImageGenerationRequest) (*ImageGenerationResponse, error)

GenerateImage generates images based on the provided request.

func (*Client) GenerateImageStream added in v1.0.0 

func (c *Client) GenerateImageStream(ctx context.Context, request ImageGenerationRequest) (OpenrouterStream[ImageStreamEvent], error)

GenerateImageStream generates images as a stream of events.

func (*Client) GetCurrentApiKey added in v1.0.0 

func (c *Client) GetCurrentApiKey(ctx context.Context) (*ApiKeyInfo, error)

GetCurrentApiKey returns details about the API key used for the current session.

func (*Client) GetModelBySlug added in v1.0.0 

func (c *Client) GetModelBySlug(ctx context.Context, slug string) (*Model, error)

GetModelBySlug retrieves detailed information about a model by its slug.

func (*Client) GetModelEndpoints added in v1.1.4 

func (c *Client) GetModelEndpoints(ctx context.Context, slug string) (*ModelEndpoints, error)

GetModelEndpoints retrieves detailed information about a model by its slug, including the provider endpoints serving it.

func (*Client) ListEmbeddingModels added in v1.0.0 

func (c *Client) ListEmbeddingModels(ctx context.Context, options *ListEmbeddingModelsOptions) ([]Model, error)

ListEmbeddingModels retrieves the list of available embeddings models.

func (*Client) ListImageModels added in v1.0.0 

func (c *Client) ListImageModels(ctx context.Context) ([]ImageModel, error)

ListImageModels retrieves the list of image generation models.

func (*Client) ListModels added in v1.0.0 

func (c *Client) ListModels(ctx context.Context, options *ListModelsOptions) ([]Model, error)

ListModels retrieves the list of available models filtered by options.

func (*Client) ListUserModels added in v1.0.0 

func (c *Client) ListUserModels(ctx context.Context, options *ListUserModelsOptions) ([]Model, error)

ListUserModels retrieves the list of models available to the current user.

func (*Client) NewRequest added in v1.0.0 

func (c *Client) NewRequest(ctx context.Context, method, path string, data any) (*http.Request, error)

NewRequest constructs a new HTTP request targeting the OpenRouter API.

func (*Client) ToOpenAI added in v1.1.0 

func (c *Client) ToOpenAI(options ...OpenAIOption) *OpenAIClient

ToOpenAI returns an OpenAI compatible client derived from this OpenRouter client, carrying over the http client and api token. The given options are applied on top, so the base url and http client can be overridden.

type CompletionChoice added in v1.1.0 

type CompletionChoice struct {
	Index        int                 `json:"index"`
	FinishReason string              `json:"finish_reason"`
	Text         string              `json:"text"`
	Logprobs     *CompletionLogprobs `json:"logprobs,omitempty"`
}

CompletionChoice represents a single completion choice.

type CompletionInput added in v1.1.0 

type CompletionInput struct {
	Text        string
	Texts       []string
	Tokens      []int
	TokenArrays [][]int
}

CompletionInput represents text, token, or batch prompt input(s). Exactly one of the fields should be set. TokenArrays takes precedence over Tokens, Texts and Text when more than one is set.

func (CompletionInput) MarshalJSON added in v1.1.0 

func (ci CompletionInput) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface for CompletionInput.

type CompletionLogprobs added in v1.1.0 

type CompletionLogprobs struct {
	TextOffset    []int                `json:"text_offset,omitempty"`
	TokenLogprobs []float64            `json:"token_logprobs,omitempty"`
	Tokens        []string             `json:"tokens,omitempty"`
	TopLogprobs   []map[string]float64 `json:"top_logprobs,omitempty"`
}

CompletionLogprobs represents the log probabilities of a completion choice.

type CompletionObject added in v1.1.0 

type CompletionObject string

CompletionObject is the object type of a completion response or chunk. 

const (
	CompletionObjectTextCompletion CompletionObject = "text_completion"
)

type CompletionRequest added in v1.1.0 

type CompletionRequest struct {
	Model  string          `json:"model"`
	Prompt CompletionInput `json:"prompt"`

	BestOf           *int               `json:"best_of,omitempty"`
	Echo             *bool              `json:"echo,omitempty"`
	FrequencyPenalty *float64           `json:"frequency_penalty,omitempty"`
	LogitBias        map[string]float64 `json:"logit_bias,omitempty"`
	Logprobs         *int               `json:"logprobs,omitempty"`
	MaxTokens        *int               `json:"max_tokens,omitempty"`
	N                *int               `json:"n,omitempty"`
	PresencePenalty  *float64           `json:"presence_penalty,omitempty"`
	Seed             *int               `json:"seed,omitempty"`
	Stop             []string           `json:"stop,omitempty"`
	Stream           *bool              `json:"stream,omitempty"`
	StreamOptions    *ChatStreamOptions `json:"stream_options,omitempty"`
	Suffix           string             `json:"suffix,omitempty"`
	Temperature      *float64           `json:"temperature,omitempty"`
	TopP             *float64           `json:"top_p,omitempty"`
	User             string             `json:"user,omitempty"`
}

CompletionRequest is the request body of the completions endpoint. Model and Prompt are required, zero values and nil pointers of the remaining fields are omitted from the request.

type CompletionResponse added in v1.1.0 

type CompletionResponse struct {
	ID                string             `json:"id"`
	Object            CompletionObject   `json:"object"`
	Created           int64              `json:"created"`
	Model             string             `json:"model"`
	Choices           []CompletionChoice `json:"choices"`
	SystemFingerprint *string            `json:"system_fingerprint"`
	Usage             *CompletionUsage   `json:"usage,omitempty"`
}

CompletionResponse is the root response of the completions endpoint.

type CompletionStreamChoice added in v1.1.0 

type CompletionStreamChoice struct {
	Index        int                 `json:"index"`
	Text         string              `json:"text"`
	FinishReason *string             `json:"finish_reason"`
	Logprobs     *CompletionLogprobs `json:"logprobs,omitempty"`
}

CompletionStreamChoice represents a single choice of a streaming completion.

type CompletionStreamChunk added in v1.1.0 

type CompletionStreamChunk struct {
	ID                string                   `json:"id"`
	Object            CompletionObject         `json:"object"`
	Created           int64                    `json:"created"`
	Model             string                   `json:"model"`
	Choices           []CompletionStreamChoice `json:"choices"`
	SystemFingerprint *string                  `json:"system_fingerprint"`
	Usage             *CompletionUsage         `json:"usage,omitempty"`
}

CompletionStreamChunk represents a single chunk of a streaming completion.

type CompletionTokensDetails added in v1.0.0 

type CompletionTokensDetails struct {
	ReasoningTokens *int `json:"reasoning_tokens"`
	AudioTokens     *int `json:"audio_tokens"`
	ImageTokens     *int `json:"image_tokens"`
}

CompletionTokensDetails represents the breakdown of tokens generated by the model.

type CompletionUsage added in v1.1.0 

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

CompletionUsage represents the token usage of a completion.

type ContentPartImage added in v1.0.0 

type ContentPartImage struct {
	Type     ContentPartType     `json:"type"`
	ImageURL ContentPartImageURL `json:"image_url"`
}

ContentPartImage represents an image content part, as a base64 data url or an HTTP(S) url.

type ContentPartImageURL added in v1.0.0 

type ContentPartImageURL struct {
	URL string `json:"url"`
}

ContentPartImageURL holds the url of a ContentPartImage.

type ContentPartType added in v1.0.0 

type ContentPartType string

ContentPartType is the type of a content part. 

const (
	ContentPartTypeImageURL ContentPartType = "image_url"
)

type CostDetails added in v1.0.0 

type CostDetails struct {
	UpstreamInferenceCost            *float64 `json:"upstream_inference_cost"`
	UpstreamInferencePromptCost      float64  `json:"upstream_inference_prompt_cost"`
	UpstreamInferenceCompletionsCost float64  `json:"upstream_inference_completions_cost"`
}

CostDetails represents the breakdown of upstream inference costs.

type CreditsError added in v1.0.2 

type CreditsError struct {
	ErrorStatus

	Message     string
	LimitSource string
	RemedyHint  string
}

CreditsError represents a 402 caused by an insufficient credit balance.

func (*CreditsError) Error added in v1.0.2 

func (c *CreditsError) Error() string

Error returns the formatted string representation of the credits error.

type DesignArenaBenchmark added in v1.0.0 

type DesignArenaBenchmark struct {
	Arena    string  `json:"arena"`
	Category string  `json:"category"`
	ELO      float64 `json:"elo"`
	WinRate  float64 `json:"win_rate"`
	Rank     int     `json:"rank"`
}

DesignArenaBenchmark represents a single Design Arena entry for a specific arena and category pair.

type Embedding added in v1.0.0 

type Embedding struct {
	Object    EmbeddingObject `json:"object"`
	Embedding EmbeddingValue  `json:"embedding"`
	Index     int             `json:"index"`
}

Embedding represents a single embedding object of an embeddings response.

type EmbeddingContentPart added in v1.0.0 

type EmbeddingContentPart struct {
	Type       EmbeddingContentPartType `json:"type"`
	Text       string                   `json:"text,omitempty"`
	ImageURL   *ContentPartImageURL     `json:"image_url,omitempty"`
	InputAudio *EmbeddingMedia          `json:"input_audio,omitempty"`
	InputVideo *EmbeddingMedia          `json:"input_video,omitempty"`
	InputFile  *EmbeddingMedia          `json:"input_file,omitempty"`
}

EmbeddingContentPart represents a single content part of a multimodal embedding input. Type determines which of the remaining fields are used.

type EmbeddingContentPartType added in v1.0.0 

type EmbeddingContentPartType string

EmbeddingContentPartType is the type of a multimodal embedding content part. 

const (
	EmbeddingContentPartTypeText       EmbeddingContentPartType = "text"
	EmbeddingContentPartTypeImageURL   EmbeddingContentPartType = "image_url"
	EmbeddingContentPartTypeInputAudio EmbeddingContentPartType = "input_audio"
	EmbeddingContentPartTypeInputVideo EmbeddingContentPartType = "input_video"
	EmbeddingContentPartTypeInputFile  EmbeddingContentPartType = "input_file"
)

type EmbeddingEncodingFormat added in v1.0.0 

type EmbeddingEncodingFormat string

EmbeddingEncodingFormat is the encoding of the returned embedding vectors. 

const (
	EmbeddingEncodingFormatFloat  EmbeddingEncodingFormat = "float"
	EmbeddingEncodingFormatBase64 EmbeddingEncodingFormat = "base64"
)

type EmbeddingInput added in v1.0.0 

type EmbeddingInput struct {
	Text             string
	Texts            []string
	Tokens           []int
	TokenArrays      [][]int
	MultimodalInputs []EmbeddingMultimodalInput
}

EmbeddingInput represents text, token, or multimodal input(s) to embed. Exactly one of the fields should be set. MultimodalInputs takes precedence over TokenArrays, Tokens, Texts and Text when more than one is set.

func (EmbeddingInput) MarshalJSON added in v1.0.0 

func (ei EmbeddingInput) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface for EmbeddingInput.

func (*EmbeddingInput) UnmarshalJSON added in v1.0.0 

func (ei *EmbeddingInput) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface for EmbeddingInput.

type EmbeddingMedia added in v1.0.0 

type EmbeddingMedia struct {
	Data   string `json:"data"`
	Format string `json:"format,omitempty"`
}

EmbeddingMedia holds base64-encoded media and its format for an audio, video or file embedding content part.

type EmbeddingMultimodalInput added in v1.0.0 

type EmbeddingMultimodalInput struct {
	Content []EmbeddingContentPart `json:"content"`
}

EmbeddingMultimodalInput represents a single multimodal embedding input made of one or more content parts.

type EmbeddingObject added in v1.0.0 

type EmbeddingObject string

EmbeddingObject is the object type of an embeddings response or embedding. 

const (
	EmbeddingObjectList      EmbeddingObject = "list"
	EmbeddingObjectEmbedding EmbeddingObject = "embedding"
)

type EmbeddingPromptTokensDetails added in v1.0.0 

type EmbeddingPromptTokensDetails struct {
	AudioTokens *int `json:"audio_tokens,omitempty"`
	FileTokens  *int `json:"file_tokens,omitempty"`
	ImageTokens *int `json:"image_tokens,omitempty"`
	TextTokens  *int `json:"text_tokens,omitempty"`
	VideoTokens *int `json:"video_tokens,omitempty"`
}

EmbeddingPromptTokensDetails represents the per-modality token breakdown of an embeddings request. It is only present when the input contains two or more modalities and the upstream provider returns modality-level usage data. Only non-zero modality counts are included.

type EmbeddingRequest added in v1.0.0 

type EmbeddingRequest struct {
	Model string         `json:"model"`
	Input EmbeddingInput `json:"input"`

	Dimensions     *int                    `json:"dimensions,omitempty"`
	EncodingFormat EmbeddingEncodingFormat `json:"encoding_format,omitempty"`
	InputType      string                  `json:"input_type,omitempty"`
	Provider       *ProviderPreferences    `json:"provider,omitempty"`
	User           string                  `json:"user,omitempty"`
}

EmbeddingRequest represents the request body of the embeddings endpoint. Model and Input are required, zero values and nil pointers of the remaining fields are omitted from the request.

type EmbeddingResponse added in v1.0.0 

type EmbeddingResponse struct {
	ID     string          `json:"id,omitempty"`
	Object EmbeddingObject `json:"object"`
	Data   []Embedding     `json:"data"`
	Model  string          `json:"model"`
	Usage  *EmbeddingUsage `json:"usage,omitempty"`
}

EmbeddingResponse is the root response of the embeddings endpoint.

type EmbeddingUsage added in v1.0.0 

type EmbeddingUsage struct {
	PromptTokens        int                           `json:"prompt_tokens"`
	TotalTokens         int                           `json:"total_tokens"`
	Cost                *float64                      `json:"cost,omitempty"`
	CostDetails         *CostDetails                  `json:"cost_details,omitempty"`
	PromptTokensDetails *EmbeddingPromptTokensDetails `json:"prompt_tokens_details,omitempty"`
	IsBYOK              bool                          `json:"is_byok"`
}

EmbeddingUsage represents the token and cost usage of an embeddings request.

type EmbeddingValue added in v1.0.0 

type EmbeddingValue struct {
	Floats []float64
	Base64 string
}

EmbeddingValue represents an embedding vector encoded either as an array of floats or as a base64 string. Floats takes precedence over Base64 when both are set.

func (EmbeddingValue) MarshalJSON added in v1.0.0 

func (ev EmbeddingValue) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface for EmbeddingValue.

func (*EmbeddingValue) UnmarshalJSON added in v1.0.0 

func (ev *EmbeddingValue) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface for EmbeddingValue.

type EndpointInfo added in v1.0.0 

type EndpointInfo struct {
	Provider string `json:"provider"`
	Model    string `json:"model"`
	Selected bool   `json:"selected"`
}

EndpointInfo represents a single endpoint considered while routing a request.

type EndpointLatencyStats added in v1.1.4 

type EndpointLatencyStats struct {
	P50 float64 `json:"p50"`
	P75 float64 `json:"p75"`
	P90 float64 `json:"p90"`
	P99 float64 `json:"p99"`
}

EndpointLatencyStats represents the latency percentiles of an endpoint over the last 30 minutes, in milliseconds.

type EndpointThroughputStats added in v1.1.4 

type EndpointThroughputStats struct {
	P50 float64 `json:"p50"`
	P75 float64 `json:"p75"`
	P90 float64 `json:"p90"`
	P99 float64 `json:"p99"`
}

EndpointThroughputStats represents the throughput percentiles of an endpoint over the last 30 minutes, in tokens per second.

type EndpointsMetadata added in v1.0.0 

type EndpointsMetadata struct {
	Total     int            `json:"total"`
	Available []EndpointInfo `json:"available"`
}

EndpointsMetadata represents the endpoints considered while routing a request.

type ErrorStatus added in v1.0.2 

type ErrorStatus struct {
	Code         int64
	Type         ErrorType
	ProviderCode string
	RetryAfter   time.Duration
	Previous     []SubError
}

ErrorStatus carries the fields every OpenRouter error response shares. It is embedded in each concrete error type, so Code, Type, RetryAfter, Retryable and errors.Is work uniformly regardless of which one you got back.

func (ErrorStatus) Retryable added in v1.0.2 

func (s ErrorStatus) Retryable() bool

Retryable reports whether retrying the same request could plausibly succeed. Honor RetryAfter first when it is non-zero.

func (ErrorStatus) Unwrap added in v1.0.2 

func (s ErrorStatus) Unwrap() error

Unwrap maps the error onto its sentinel category. error_type wins when present because it survives provider-specific status mangling.

type ErrorType added in v1.0.2 

type ErrorType string

ErrorType is the stable error_type vocabulary OpenRouter tags errors with. It is more precise than the HTTP status and is carried identically on response bodies and mid-stream SSE events. 

const (
	ErrorTypeContextLengthExceeded ErrorType = "context_length_exceeded"
	ErrorTypeMaxTokensExceeded     ErrorType = "max_tokens_exceeded"
	ErrorTypeTokenLimitExceeded    ErrorType = "token_limit_exceeded"
	ErrorTypeStringTooLong         ErrorType = "string_too_long"
	ErrorTypeAuthentication        ErrorType = "authentication"
	ErrorTypePermissionDenied      ErrorType = "permission_denied"
	ErrorTypePaymentRequired       ErrorType = "payment_required"
	ErrorTypeRateLimitExceeded     ErrorType = "rate_limit_exceeded"
	ErrorTypeProviderOverloaded    ErrorType = "provider_overloaded"
	ErrorTypeProviderUnavailable   ErrorType = "provider_unavailable"
	ErrorTypeInvalidRequest        ErrorType = "invalid_request"
	ErrorTypeInvalidPrompt         ErrorType = "invalid_prompt"
	ErrorTypeNotFound              ErrorType = "not_found"
	ErrorTypePreconditionFailed    ErrorType = "precondition_failed"
	ErrorTypePayloadTooLarge       ErrorType = "payload_too_large"
	ErrorTypeUnprocessable         ErrorType = "unprocessable"
	ErrorTypeContentPolicy         ErrorType = "content_policy_violation"
	ErrorTypeRefusal               ErrorType = "refusal"
	ErrorTypeInvalidImage          ErrorType = "invalid_image"
	ErrorTypeImageTooLarge         ErrorType = "image_too_large"
	ErrorTypeImageTooSmall         ErrorType = "image_too_small"
	ErrorTypeUnsupportedImage      ErrorType = "unsupported_image_format"
	ErrorTypeImageNotFound         ErrorType = "image_not_found"
	ErrorTypeImageDownloadFailed   ErrorType = "image_download_failed"
	ErrorTypeServer                ErrorType = "server"
	ErrorTypeTimeout               ErrorType = "timeout"
	ErrorTypeUnmapped              ErrorType = "unmapped"
)

type FlexibleTime 

type FlexibleTime struct {
	time.Time
}

FlexibleTime handles multiple timestamp formats

func (FlexibleTime) MarshalJSON 

func (ft FlexibleTime) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface for FlexibleTime.

func (*FlexibleTime) UnmarshalJSON 

func (ft *FlexibleTime) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface for FlexibleTime.

type FrontendDataPolicy 

type FrontendDataPolicy struct {
	Training           bool   `json:"training"`
	TrainingOpenRouter bool   `json:"trainingOpenRouter"`
	RetainsPrompts     bool   `json:"retainsPrompts"`
	RetentionDays      *int   `json:"retentionDays,omitempty"`
	CanPublish         bool   `json:"canPublish"`
	TermsOfServiceURL  string `json:"termsOfServiceURL"`
	PrivacyPolicyURL   string `json:"privacyPolicyURL"`
	RequiresUserIDs    bool   `json:"requiresUserIDs,omitempty"`
}

FrontendDataPolicy represents a provider's data handling policy.

type FrontendDefaultParams 

type FrontendDefaultParams struct {
	Temperature       *float64 `json:"temperature"`
	TopP              *float64 `json:"top_p"`
	TopK              *float64 `json:"top_k"`
	FrequencyPenalty  *float64 `json:"frequency_penalty"`
	PresencePenalty   *float64 `json:"presence_penalty"`
	RepetitionPenalty *float64 `json:"repetition_penalty"`
}

FrontendDefaultParams represents default sampling parameters for a model.

type FrontendDerankReason added in v0.2.0 

type FrontendDerankReason struct {
	Signal             string  `json:"signal"`
	StddevsBelowMedian float64 `json:"stddevs_below_median"`
	Threshold          float64 `json:"threshold"`
	Value              float64 `json:"value"`
}

FrontendDerankReason represents a single reason an endpoint was deranked.

type FrontendDerankResult added in v0.2.0 

type FrontendDerankResult struct {
	IsDeranked    bool                   `json:"is_deranked"`
	DerankReasons []FrontendDerankReason `json:"derank_reasons"`
}

FrontendDerankResult represents whether and why an endpoint is deranked.

type FrontendDisplayPricing added in v0.2.0 

type FrontendDisplayPricing struct {
	Kind              string `json:"kind"`
	SKULabel          string `json:"sku_label"`
	Price             string `json:"price"`
	DisplayMultiplier int    `json:"displayMultiplier"`
	UnitLabel         string `json:"unitLabel"`
}

FrontendDisplayPricing represents a human-readable pricing line item.

type FrontendEndpoint 

type FrontendEndpoint struct {
	ID                           string                            `json:"id"`
	Name                         string                            `json:"name"`
	ContextLength                int                               `json:"context_length"`
	Model                        *FrontendModel                    `json:"model"`
	ModelVariantSlug             string                            `json:"model_variant_slug"`
	ModelVariantPermaslug        string                            `json:"model_variant_permaslug"`
	AdapterName                  string                            `json:"adapter_name"`
	ProviderName                 string                            `json:"provider_name"`
	ProviderInfo                 *FrontendProviderInfo             `json:"provider_info"`
	ProviderDisplayName          string                            `json:"provider_display_name"`
	ProviderSlug                 string                            `json:"provider_slug"`
	ProviderModelID              string                            `json:"provider_model_id"`
	Quantization                 string                            `json:"quantization"`
	Variant                      string                            `json:"variant"`
	IsFree                       bool                              `json:"is_free"`
	CanAbort                     bool                              `json:"can_abort"`
	MaxPromptTokens              *int                              `json:"max_prompt_tokens"`
	MaxCompletionTokens          int                               `json:"max_completion_tokens"`
	MaxTokensPerImage            *int                              `json:"max_tokens_per_image"`
	SupportedParameters          []string                          `json:"supported_parameters"`
	ExcludedParameters           []string                          `json:"excluded_parameters"`
	IsBYOK                       bool                              `json:"is_byok"`
	ModerationRequired           bool                              `json:"moderation_required"`
	DataPolicy                   *FrontendDataPolicy               `json:"data_policy"`
	Pricing                      *FrontendPricing                  `json:"pricing"`
	DisplayPricing               []FrontendDisplayPricing          `json:"display_pricing"`
	VariablePricings             []FrontendVariablePricing         `json:"variable_pricings,omitempty"`
	LineItems                    []FrontendLineItem                `json:"line_items,omitempty"`
	PricingJSON                  map[string]any                    `json:"pricing_json"`
	PricingVersionID             string                            `json:"pricing_version_id"`
	IsHidden                     bool                              `json:"is_hidden"`
	IsPrivate                    bool                              `json:"is_private"`
	IsDeranked                   bool                              `json:"is_deranked"`
	IsDisabled                   bool                              `json:"is_disabled"`
	SupportsToolParams           bool                              `json:"supports_tool_parameters"`
	SupportsReasoning            bool                              `json:"supports_reasoning"`
	SupportsMultipart            bool                              `json:"supports_multipart"`
	LimitRPM                     *int                              `json:"limit_rpm"`
	LimitRPD                     *int                              `json:"limit_rpd"`
	LimitRPMCF                   *int                              `json:"limit_rpm_cf"`
	HasCompletions               bool                              `json:"has_completions"`
	HasChatCompletions           bool                              `json:"has_chat_completions"`
	Features                     *FrontendFeatures                 `json:"features"`
	SupportedVideoParameters     *FrontendSupportedVideoParameters `json:"supported_video_parameters"`
	ProviderRegion               *string                           `json:"provider_region"`
	DeprecationDate              *FlexibleTime                     `json:"deprecation_date"`
	AllowedPassthroughParameters []string                          `json:"allowed_passthrough_parameters"`
	CapacityTPM                  *float64                          `json:"capacity_tpm"`
	CreatedAt                    FlexibleTime                      `json:"created_at"`
	RoutingHeuristics            *FrontendRoutingHeuristics        `json:"routing_heuristics"`
	Status                       int                               `json:"status"`
	StatusHeuristics             *FrontendStatusHeuristics         `json:"status_heuristics"`
	StatusHeuristics5m           *FrontendStatusHeuristics         `json:"status_heuristics_5m"`
	StatusHeuristics1d           *FrontendStatusHeuristics         `json:"status_heuristics_1d"`
	Fortuna                      *FrontendFortuna                  `json:"fortuna"`
}

FrontendEndpoint represents a provider endpoint serving a model.

type FrontendFeatures 

type FrontendFeatures struct {
	ReasoningConfig          *FrontendReasoningConfig `json:"reasoning_config,omitempty"`
	ChatTemplateConfig       map[string]any           `json:"chat_template_config,omitempty"`
	ReasoningReturnMechanism *string                  `json:"reasoning_return_mechanism,omitempty"`
	SupportsFileURLs         *bool                    `json:"supports_file_urls,omitempty"`
	SupportsBase64Video      *bool                    `json:"supports_base64_video_input,omitempty"`
	SupportsVideoURLs        *bool                    `json:"supports_video_urls,omitempty"`
	SupportsToolChoice       *FrontendToolChoice      `json:"supports_tool_choice,omitempty"`
	SupportsInputAudio       *bool                    `json:"supports_input_audio,omitempty"`
	SupportsNativeWeb        *bool                    `json:"supports_native_web_search,omitempty"`
	SupportsMultipart        *bool                    `json:"supports_multipart,omitempty"`
}

FrontendFeatures represents model and endpoint feature support.

type FrontendFortuna added in v0.2.0 

type FrontendFortuna struct {
	BetaAlpha          float64 `json:"beta_alpha"`
	BetaBeta           float64 `json:"beta_beta"`
	CapacityScore      float64 `json:"capacity_score"`
	CapacityCeilingRPM float64 `json:"capacity_ceiling_rpm"`
	RecentPeakRPM      float64 `json:"recent_peak_rpm"`
}

FrontendFortuna represents capacity and load-balancing scoring for an endpoint.

type FrontendIcon 

type FrontendIcon struct {
	URL string `json:"url"`
}

FrontendIcon represents a provider icon.

type FrontendLineItem 

type FrontendLineItem struct {
	Type  string `json:"type"`
	Value string `json:"value"`
}

FrontendLineItem represents a pricing line item.

type FrontendModel 

type FrontendModel struct {
	Slug                  string                   `json:"slug"`
	HFSlug                *string                  `json:"hf_slug"`
	UpdatedAt             FlexibleTime             `json:"updated_at"`
	CreatedAt             FlexibleTime             `json:"created_at"`
	HFUpdatedAt           *FlexibleTime            `json:"hf_updated_at"`
	Name                  string                   `json:"name"`
	ShortName             string                   `json:"short_name"`
	Author                string                   `json:"author"`
	AuthorDisplayName     string                   `json:"author_display_name"`
	Description           string                   `json:"description"`
	ModelVersionGroupID   *string                  `json:"model_version_group_id"`
	ContextLength         int                      `json:"context_length"`
	InputModalities       []string                 `json:"input_modalities"`
	OutputModalities      []string                 `json:"output_modalities"`
	HasTextOutput         bool                     `json:"has_text_output"`
	Group                 string                   `json:"group"`
	InstructType          *string                  `json:"instruct_type"`
	DefaultSystem         *string                  `json:"default_system"`
	DefaultStops          []string                 `json:"default_stops"`
	Hidden                bool                     `json:"hidden"`
	Router                *string                  `json:"router"`
	WarningMessage        *string                  `json:"warning_message"`
	PromotionMessage      *string                  `json:"promotion_message"`
	RoutingErrorMessage   *string                  `json:"routing_error_message"`
	IsPrivate             bool                     `json:"is_private"`
	Permaslug             string                   `json:"permaslug"`
	SupportsReasoning     bool                     `json:"supports_reasoning"`
	ReasoningConfig       *FrontendReasoningConfig `json:"reasoning_config"`
	Features              *FrontendFeatures        `json:"features"`
	DefaultParameters     *FrontendDefaultParams   `json:"default_parameters"`
	DefaultOrder          []string                 `json:"default_order"`
	QuickStartExampleType string                   `json:"quick_start_example_type"`
	IsTrainableText       *bool                    `json:"is_trainable_text"`
	IsTrainableImage      *bool                    `json:"is_trainable_image"`
	KnowledgeCutoff       *string                  `json:"knowledge_cutoff"`
	LimitRPM              *int                     `json:"limit_rpm"`
	LimitRPD              *int                     `json:"limit_rpd"`
	SupportedTTSVoices    []string                 `json:"supported_tts_voices"`
	Endpoint              *FrontendEndpoint        `json:"endpoint,omitempty"`
}

FrontendModel represents a model in the frontend API.

func ListFrontendModels 

func ListFrontendModels(ctx context.Context) ([]FrontendModel, error)

ListFrontendModels retrieves the model catalog from the OpenRouter frontend API.

type FrontendPricing 

type FrontendPricing struct {
	Prompt            StringifiedNumber        `json:"prompt"`
	Completion        StringifiedNumber        `json:"completion"`
	Image             StringifiedNumber        `json:"image,omitempty"`
	ImageOutput       StringifiedNumber        `json:"image_output,omitempty"`
	Audio             StringifiedNumber        `json:"audio,omitempty"`
	InputAudioCache   StringifiedNumber        `json:"input_audio_cache,omitempty"`
	InputCacheRead    StringifiedNumber        `json:"input_cache_read,omitempty"`
	InputCacheWrite   StringifiedNumber        `json:"input_cache_write,omitempty"`
	InternalReasoning StringifiedNumber        `json:"internal_reasoning,omitempty"`
	WebSearch         StringifiedNumber        `json:"web_search,omitempty"`
	Discount          float64                  `json:"discount"`
	DisplayPricing    []FrontendDisplayPricing `json:"display_pricing,omitempty"`
	LineItems         []FrontendLineItem       `json:"line_items,omitempty"`
}

FrontendPricing represents endpoint pricing information.

type FrontendProvider added in v1.1.4 

type FrontendProvider struct {
	Name               string              `json:"name"`
	DisplayName        string              `json:"displayName"`
	Slug               string              `json:"slug"`
	AdapterName        string              `json:"adapterName"`
	BaseURL            string              `json:"baseUrl"`
	DataPolicy         *FrontendDataPolicy `json:"dataPolicy"`
	Headquarters       string              `json:"headquarters,omitempty"`
	Datacenters        []string            `json:"datacenters,omitempty"`
	HasChatCompletions bool                `json:"hasChatCompletions"`
	HasCompletions     bool                `json:"hasCompletions"`
	IsAbortable        bool                `json:"isAbortable"`
	ModerationRequired bool                `json:"moderationRequired"`
	StatusPageURL      *string             `json:"statusPageUrl"`
	BYOKEnabled        bool                `json:"byokEnabled"`
	Icon               *FrontendIcon       `json:"icon"`
	SendClientIP       bool                `json:"sendClientIp"`
	PricingStrategy    string              `json:"pricingStrategy"`
}

FrontendProvider represents an inference provider in the frontend API.

func ListFrontendProviders added in v1.1.4 

func ListFrontendProviders(ctx context.Context) ([]FrontendProvider, error)

ListFrontendProviders retrieves the provider list from the OpenRouter frontend API.

type FrontendProviderInfo 

type FrontendProviderInfo struct {
	Name                  string                            `json:"name"`
	DisplayName           string                            `json:"displayName"`
	Slug                  string                            `json:"slug"`
	BaseURL               string                            `json:"baseUrl"`
	DataPolicy            *FrontendDataPolicy               `json:"dataPolicy"`
	Headquarters          string                            `json:"headquarters"`
	Datacenters           []string                          `json:"datacenters,omitempty"`
	RegionOverrides       map[string]FrontendRegionOverride `json:"regionOverrides,omitempty"`
	HasChatCompletions    bool                              `json:"hasChatCompletions"`
	HasCompletions        bool                              `json:"hasCompletions"`
	IsAbortable           bool                              `json:"isAbortable"`
	ModerationRequired    bool                              `json:"moderationRequired"`
	Editors               []string                          `json:"editors"`
	Owners                []string                          `json:"owners"`
	AdapterName           string                            `json:"adapterName"`
	IsMultipartSupported  bool                              `json:"isMultipartSupported,omitempty"`
	StatusPageURL         *string                           `json:"statusPageUrl"`
	BYOKEnabled           bool                              `json:"byokEnabled"`
	Icon                  *FrontendIcon                     `json:"icon"`
	IgnoredProviderModels []string                          `json:"ignoredProviderModels,omitempty"`
	SendClientIP          bool                              `json:"sendClientIp"`
	PricingStrategy       string                            `json:"pricingStrategy"`
}

FrontendProviderInfo represents information about an inference provider.

type FrontendReasoningConfig 

type FrontendReasoningConfig struct {
	StartToken                *string  `json:"start_token"`
	EndToken                  *string  `json:"end_token"`
	IsMandatoryReasoning      *bool    `json:"is_mandatory_reasoning,omitempty"`
	SupportsReasoningEffort   *bool    `json:"supports_reasoning_effort,omitempty"`
	SupportedReasoningEfforts []string `json:"supported_reasoning_efforts"`
	DefaultReasoningEffort    *string  `json:"default_reasoning_effort,omitempty"`
	DefaultReasoningEnabled   *bool    `json:"default_reasoning_enabled,omitempty"`
	ReasoningReturnMechanism  *string  `json:"reasoning_return_mechanism,omitempty"`
}

FrontendReasoningConfig represents reasoning configuration for a model or endpoint.

type FrontendRegionOverride 

type FrontendRegionOverride struct {
	BaseURL string `json:"baseUrl"`
}

FrontendRegionOverride represents region-specific provider overrides.

type FrontendRoutingHeuristics added in v0.2.0 

type FrontendRoutingHeuristics struct {
	RequestCount                       int                   `json:"request_count"`
	P50Throughput                      float64               `json:"p50_throughput"`
	P50Latency                         float64               `json:"p50_latency"`
	RequestCount30Minutes              int                   `json:"request_count_30_minutes"`
	P50Throughput30Minutes             float64               `json:"p50_throughput_30_minutes"`
	P75Throughput30Minutes             float64               `json:"p75_throughput_30_minutes"`
	P90Throughput30Minutes             float64               `json:"p90_throughput_30_minutes"`
	P99Throughput30Minutes             float64               `json:"p99_throughput_30_minutes"`
	P50Latency30Minutes                float64               `json:"p50_latency_30_minutes"`
	P75Latency30Minutes                float64               `json:"p75_latency_30_minutes"`
	P90Latency30Minutes                float64               `json:"p90_latency_30_minutes"`
	P99Latency30Minutes                float64               `json:"p99_latency_30_minutes"`
	EffectivePromptPrice               float64               `json:"effective_prompt_price"`
	EffectiveCompletionPrice           float64               `json:"effective_completion_price"`
	RequestCount5Minutes               int                   `json:"request_count_5_minutes"`
	P50Throughput5Minutes              float64               `json:"p50_throughput_5_minutes"`
	P75Throughput5Minutes              float64               `json:"p75_throughput_5_minutes"`
	P90Throughput5Minutes              float64               `json:"p90_throughput_5_minutes"`
	P99Throughput5Minutes              float64               `json:"p99_throughput_5_minutes"`
	P50Latency5Minutes                 float64               `json:"p50_latency_5_minutes"`
	P75Latency5Minutes                 float64               `json:"p75_latency_5_minutes"`
	P90Latency5Minutes                 float64               `json:"p90_latency_5_minutes"`
	P99Latency5Minutes                 float64               `json:"p99_latency_5_minutes"`
	P50Throughput2Hours                float64               `json:"p50_throughput_2_hours"`
	ToolFinishReasonRequestSuccessRate *float64              `json:"tool_finish_reason_request_success_rate,omitempty"`
	ToolCallsFinishReasonRequestCount  *int                  `json:"tool_calls_finish_reason_request_count,omitempty"`
	DerankResult                       *FrontendDerankResult `json:"derank_result,omitempty"`
}

FrontendRoutingHeuristics represents throughput, latency and routing statistics for an endpoint.

type FrontendStatusHeuristics added in v0.2.0 

type FrontendStatusHeuristics struct {
	Success         int `json:"success"`
	DerankableError int `json:"derankableError"`
	RateLimited     int `json:"rateLimited"`
}

FrontendStatusHeuristics represents request outcome counts over a time window.

type FrontendSupportedVideoParameters added in v0.2.0 

type FrontendSupportedVideoParameters struct {
	SupportedResolutions  []string `json:"supported_resolutions"`
	SupportedAspectRatios []string `json:"supported_aspect_ratios"`
	SupportedSizes        []string `json:"supported_sizes"`
	SupportedDurations    []int    `json:"supported_durations"`
	SupportedFrameImages  []string `json:"supported_frame_images"`
	GenerateAudio         *bool    `json:"generate_audio"`
	Seed                  *bool    `json:"seed"`
}

FrontendSupportedVideoParameters represents video generation parameter support for an endpoint.

type FrontendToolChoice 

type FrontendToolChoice struct {
	LiteralNone     bool `json:"literal_none"`
	LiteralAuto     bool `json:"literal_auto"`
	LiteralRequired bool `json:"literal_required"`
	TypeFunction    bool `json:"type_function"`
}

FrontendToolChoice represents which tool_choice values an endpoint supports.

type FrontendVariablePricing 

type FrontendVariablePricing struct {
	Type            string            `json:"type"`
	Threshold       any               `json:"threshold"`
	Prompt          StringifiedNumber `json:"prompt"`
	Completions     StringifiedNumber `json:"completions"`
	InputCacheRead  StringifiedNumber `json:"input_cache_read,omitempty"`
	InputCacheWrite StringifiedNumber `json:"input_cache_write,omitempty"`
}

FrontendVariablePricing represents variable pricing tiers.

type GeneratedImage added in v1.0.0 

type GeneratedImage struct {
	B64JSON   string `json:"b64_json"`
	MediaType string `json:"media_type,omitempty"`
}

GeneratedImage represents a single generated image. MediaType is omitted if the format could not be determined. For svg output the markup is utf-8 encoded inside B64JSON.

type HttpError added in v1.0.2 

type HttpError struct {
	ErrorStatus

	Status string
}

HttpError represents a response that carried no usable OpenRouter error body.

func (*HttpError) Error added in v1.0.2 

func (h *HttpError) Error() string

Error returns the formatted string representation of the HTTP error.

type ImageAspectRatio added in v1.0.0 

type ImageAspectRatio string

ImageAspectRatio is a normalized aspect ratio of a generated image. Providers clamp to their supported subset. 

const (
	ImageAspectRatio1x1        ImageAspectRatio = "1:1"
	ImageAspectRatio1x2        ImageAspectRatio = "1:2"
	ImageAspectRatio1x4        ImageAspectRatio = "1:4"
	ImageAspectRatio1x8        ImageAspectRatio = "1:8"
	ImageAspectRatio2x1        ImageAspectRatio = "2:1"
	ImageAspectRatio2x3        ImageAspectRatio = "2:3"
	ImageAspectRatio3x2        ImageAspectRatio = "3:2"
	ImageAspectRatio3x4        ImageAspectRatio = "3:4"
	ImageAspectRatio4x1        ImageAspectRatio = "4:1"
	ImageAspectRatio4x3        ImageAspectRatio = "4:3"
	ImageAspectRatio4x5        ImageAspectRatio = "4:5"
	ImageAspectRatio5x4        ImageAspectRatio = "5:4"
	ImageAspectRatio8x1        ImageAspectRatio = "8:1"
	ImageAspectRatio9x16       ImageAspectRatio = "9:16"
	ImageAspectRatio16x9       ImageAspectRatio = "16:9"
	ImageAspectRatio9x19Point5 ImageAspectRatio = "9:19.5"
	ImageAspectRatio19Point5x9 ImageAspectRatio = "19.5:9"
	ImageAspectRatio9x20       ImageAspectRatio = "9:20"
	ImageAspectRatio20x9       ImageAspectRatio = "20:9"
	ImageAspectRatio9x21       ImageAspectRatio = "9:21"
	ImageAspectRatio21x9       ImageAspectRatio = "21:9"
	ImageAspectRatioAuto       ImageAspectRatio = "auto"
)

type ImageBackground added in v1.0.0 

type ImageBackground string

ImageBackground is the background treatment of a generated image. Transparent requires an output format that supports alpha (png or webp). 

const (
	ImageBackgroundAuto        ImageBackground = "auto"
	ImageBackgroundTransparent ImageBackground = "transparent"
	ImageBackgroundOpaque      ImageBackground = "opaque"
)

type ImageCapability added in v1.0.0 

type ImageCapability struct {
	Type   ImageCapabilityType `json:"type"`
	Values []string            `json:"values,omitempty"`
	Min    *float64            `json:"min,omitempty"`
	Max    *float64            `json:"max,omitempty"`
}

ImageCapability is a typed descriptor for one supported request parameter. Type determines which of the remaining fields are populated: Values for enum, Min and Max for range, none for boolean.

type ImageCapabilityType added in v1.0.0 

type ImageCapabilityType string

ImageCapabilityType is the kind of a supported parameter descriptor. 

const (
	ImageCapabilityTypeBoolean ImageCapabilityType = "boolean"
	ImageCapabilityTypeEnum    ImageCapabilityType = "enum"
	ImageCapabilityTypeRange   ImageCapabilityType = "range"
)

type ImageGenerationRequest added in v1.0.0 

type ImageGenerationRequest struct {
	Model  string `json:"model"`
	Prompt string `json:"prompt"`

	AspectRatio       ImageAspectRatio     `json:"aspect_ratio,omitempty"`
	Background        ImageBackground      `json:"background,omitempty"`
	InputReferences   []ContentPartImage   `json:"input_references,omitempty"`
	Count             *int                 `json:"n,omitempty"`
	OutputCompression *int                 `json:"output_compression,omitempty"`
	OutputFormat      ImageOutputFormat    `json:"output_format,omitempty"`
	Provider          *ProviderPreferences `json:"provider,omitempty"`
	Quality           ImageQuality         `json:"quality,omitempty"`
	Resolution        ImageResolution      `json:"resolution,omitempty"`
	Seed              *int                 `json:"seed,omitempty"`
	Size              string               `json:"size,omitempty"`
	Stream            *bool                `json:"stream,omitempty"`
}

ImageGenerationRequest represents the request body of the image generation endpoint. Model and Prompt are required, zero values and nil pointers of the remaining fields are omitted from the request. Size is a shorthand for the output dimensions: a tier ("2K", "4K") is equivalent to Resolution and combines with AspectRatio, an explicit pixel size ("2048x2048") is authoritative and is rejected alongside a mismatched Resolution or AspectRatio. At most 16 InputReferences are accepted.

type ImageGenerationResponse added in v1.0.0 

type ImageGenerationResponse struct {
	Created int64            `json:"created"`
	Data    []GeneratedImage `json:"data"`
	Usage   *Usage           `json:"usage,omitempty"`
}

ImageGenerationResponse is the root response for the image generation endpoint.

type ImageModel added in v1.0.0 

type ImageModel struct {
	ID                  string                   `json:"id"`
	Name                string                   `json:"name"`
	Description         string                   `json:"description"`
	Created             int64                    `json:"created"`
	Architecture        ImageModelArchitecture   `json:"architecture"`
	SupportedParameters ImageSupportedParameters `json:"supported_parameters"`
	SupportsStreaming   bool                     `json:"supports_streaming"`
	Endpoints           string                   `json:"endpoints"`
}

ImageModel represents an image generation model.

type ImageModelArchitecture added in v1.0.0 

type ImageModelArchitecture struct {
	InputModalities  []InputModality  `json:"input_modalities"`
	OutputModalities []OutputModality `json:"output_modalities"`
}

ImageModelArchitecture represents the architecture information of an image generation model.

type ImageOutputFormat added in v1.0.0 

type ImageOutputFormat string

ImageOutputFormat is the encoding of the returned image bytes. Svg is supported by vectorization models only. 

const (
	ImageOutputFormatPNG  ImageOutputFormat = "png"
	ImageOutputFormatJPEG ImageOutputFormat = "jpeg"
	ImageOutputFormatWebP ImageOutputFormat = "webp"
	ImageOutputFormatSVG  ImageOutputFormat = "svg"
)

type ImageQuality added in v1.0.0 

type ImageQuality string

ImageQuality is the rendering quality of a generated image. Providers without a quality knob ignore it. 

const (
	ImageQualityAuto   ImageQuality = "auto"
	ImageQualityLow    ImageQuality = "low"
	ImageQualityMedium ImageQuality = "medium"
	ImageQualityHigh   ImageQuality = "high"
)

type ImageResolution added in v1.0.0 

type ImageResolution string

ImageResolution is a normalized resolution tier of a generated image. The concrete pixel dimensions are derived per provider. 

const (
	ImageResolution512 ImageResolution = "512"
	ImageResolution1K  ImageResolution = "1K"
	ImageResolution2K  ImageResolution = "2K"
	ImageResolution4K  ImageResolution = "4K"
)

type ImageStreamError added in v1.0.0 

type ImageStreamError struct {
	Message string  `json:"message"`
	Code    *string `json:"code"`
	Param   *string `json:"param"`
	Type    *string `json:"type"`
}

ImageStreamError represents the provider error details of a streaming generation that failed after the response started.

func (*ImageStreamError) Error added in v1.0.0 

func (e *ImageStreamError) Error() string

Error returns the formatted string representation of the streaming image error.

type ImageStreamEvent added in v1.0.0 

type ImageStreamEvent struct {
	Type              ImageStreamEventType `json:"type"`
	B64JSON           string               `json:"b64_json,omitempty"`
	MediaType         string               `json:"media_type,omitempty"`
	PartialImageIndex int                  `json:"partial_image_index,omitempty"`
	Text              string               `json:"text,omitempty"`
	Phase             ImageStreamPhase     `json:"phase,omitempty"`
	Created           int64                `json:"created,omitempty"`
	Usage             *Usage               `json:"usage,omitempty"`
	Error             *ImageStreamError    `json:"error,omitempty"`
}

ImageStreamEvent represents a single event of a streaming image generation request. Type determines which of the remaining fields are populated: B64JSON and PartialImageIndex for partial images, Text and Phase for text chunks, B64JSON, MediaType, Created and Usage for the completed event and Error for the error event.

type ImageStreamEventType added in v1.0.0 

type ImageStreamEventType string

ImageStreamEventType is the type of a streaming image generation event. 

const (
	ImageStreamEventTypePartialImage ImageStreamEventType = "image_generation.partial_image"
	ImageStreamEventTypeTextChunk    ImageStreamEventType = "image_generation.text_chunk"
	ImageStreamEventTypeCompleted    ImageStreamEventType = "image_generation.completed"
	ImageStreamEventTypeError        ImageStreamEventType = "error"
)

type ImageStreamPhase added in v1.0.0 

type ImageStreamPhase string

ImageStreamPhase is the generation phase a text chunk belongs to. Content is the renderable output, reasoning and draft are intermediate provider phases. 

const (
	ImageStreamPhaseContent   ImageStreamPhase = "content"
	ImageStreamPhaseReasoning ImageStreamPhase = "reasoning"
	ImageStreamPhaseDraft     ImageStreamPhase = "draft"
)

type ImageSupportedParameters added in v1.0.0 

type ImageSupportedParameters map[string]ImageCapability

ImageSupportedParameters represents the union of supported parameters across every endpoint of an image generation model, keyed by parameter name. It is a coarse discovery aid, the definitive per-endpoint set is behind the endpoints url of the model.

type InputModality added in v1.0.0 

type InputModality string

InputModality is a modality a model accepts as input. 

const (
	InputModalityText  InputModality = "text"
	InputModalityImage InputModality = "image"
	InputModalityFile  InputModality = "file"
	InputModalityAudio InputModality = "audio"
	InputModalityVideo InputModality = "video"
)

type InstructType added in v1.0.0 

type InstructType string

InstructType is the instruction format type of a model. 

const (
	InstructTypeNone        InstructType = "none"
	InstructTypeAiroboros   InstructType = "airoboros"
	InstructTypeAlpaca      InstructType = "alpaca"
	InstructTypeAlpacaModif InstructType = "alpaca-modif"
	InstructTypeChatML      InstructType = "chatml"
	InstructTypeClaude      InstructType = "claude"
	InstructTypeCodeLlama   InstructType = "code-llama"
	InstructTypeGemma       InstructType = "gemma"
	InstructTypeLlama2      InstructType = "llama2"
	InstructTypeLlama3      InstructType = "llama3"
	InstructTypeMistral     InstructType = "mistral"
	InstructTypeNemotron    InstructType = "nemotron"
	InstructTypeNeural      InstructType = "neural"
	InstructTypeOpenChat    InstructType = "openchat"
	InstructTypePhi3        InstructType = "phi3"
	InstructTypeRWKV        InstructType = "rwkv"
	InstructTypeVicuna      InstructType = "vicuna"
	InstructTypeZephyr      InstructType = "zephyr"
	InstructTypeDeepSeekR1  InstructType = "deepseek-r1"
	InstructTypeDeepSeekV31 InstructType = "deepseek-v3.1"
	InstructTypeQwQ         InstructType = "qwq"
	InstructTypeQwen3       InstructType = "qwen3"
)

type JsonResponseStream added in v1.0.0 

type JsonResponseStream[T any] struct {
	// contains filtered or unexported fields
}

JsonResponseStream wraps a slice of chunks as a stream.

func NewJsonResponseStream added in v1.0.0 

func NewJsonResponseStream[T any](chunks ...T) *JsonResponseStream[T]

NewJsonResponseStream returns a new JsonResponseStream initialized with chunks.

func (*JsonResponseStream[T]) Add added in v1.0.0 

func (s *JsonResponseStream[T]) Add(chunks ...T)

Add appends one or more chunks to the stream.

func (*JsonResponseStream[T]) Close added in v1.0.0 

func (s *JsonResponseStream[T]) Close()

Close makes subsequent Recv calls return io.EOF.

func (*JsonResponseStream[T]) Recv added in v1.0.0 

func (s *JsonResponseStream[T]) Recv() (T, error)

Recv returns the next chunk, or io.EOF when exhausted or after Close.

type ListEmbeddingModelsOptions added in v1.0.0 

type ListEmbeddingModelsOptions struct {
	Offset *int `url:"offset,omitempty"`
	Limit  *int `url:"limit,omitempty"`
}

ListEmbeddingModelsOptions holds the optional query parameters of the embeddings models list endpoint. Zero values and nil pointers are omitted from the request. When both Offset and Limit are omitted, the full list is returned.

type ListModelsOptions added in v1.0.0 

type ListModelsOptions struct {
	Offset *int `url:"offset,omitempty"`
	Limit  *int `url:"limit,omitempty"`

	Category             ModelCategory    `url:"category,omitempty"`
	Sort                 ModelSort        `url:"sort,omitempty"`
	Search               string           `url:"search,omitempty"`
	Architecture         string           `url:"architecture,omitempty"`
	ModelAuthors         []string         `url:"model_authors,omitempty"`
	Providers            []string         `url:"providers,omitempty"`
	SupportedParameters  []Parameter      `url:"supported_parameters,omitempty"`
	InputModalities      []InputModality  `url:"input_modalities,omitempty"`
	OutputModalities     []OutputModality `url:"output_modalities,omitempty"`
	Context              *int             `url:"context,omitempty"`
	MinPrice             *float64         `url:"min_price,omitempty"`
	MaxPrice             *float64         `url:"max_price,omitempty"`
	MinOutputPrice       *float64         `url:"min_output_price,omitempty"`
	MaxOutputPrice       *float64         `url:"max_output_price,omitempty"`
	MinAgeDays           *int             `url:"min_age_days,omitempty"`
	MaxAgeDays           *int             `url:"max_age_days,omitempty"`
	MinIntelligenceIndex *float64         `url:"min_intelligence_index,omitempty"`
	MaxIntelligenceIndex *float64         `url:"max_intelligence_index,omitempty"`
	MinCodingIndex       *float64         `url:"min_coding_index,omitempty"`
	MaxCodingIndex       *float64         `url:"max_coding_index,omitempty"`
	MinAgenticIndex      *float64         `url:"min_agentic_index,omitempty"`
	MaxAgenticIndex      *float64         `url:"max_agentic_index,omitempty"`
	MinToolSuccessRate   *float64         `url:"min_tool_success_rate,omitempty"`
	MaxToolSuccessRate   *float64         `url:"max_tool_success_rate,omitempty"`
	Distillable          *bool            `url:"distillable,omitempty"`
	Region               ModelRegion      `url:"region,omitempty"`
	ZDR                  bool             `url:"zdr,omitempty"`
}

ListModelsOptions holds the optional query parameters of the models list endpoint. Zero values and nil pointers are omitted from the request.

type ListUserModelsOptions added in v1.0.0 

type ListUserModelsOptions struct {
	Offset *int `url:"offset,omitempty"`
	Limit  *int `url:"limit,omitempty"`
}

ListUserModelsOptions holds the optional query parameters of the user models list endpoint.

type Model added in v1.0.0 

type Model struct {
	ID                  string                  `json:"id"`
	CanonicalSlug       string                  `json:"canonical_slug"`
	Name                string                  `json:"name"`
	Description         string                  `json:"description"`
	Created             int64                   `json:"created"`
	ContextLength       *int                    `json:"context_length"`
	HuggingFaceID       *string                 `json:"hugging_face_id,omitempty"`
	ExpirationDate      *FlexibleTime           `json:"expiration_date"`
	KnowledgeCutoff     *FlexibleTime           `json:"knowledge_cutoff"`
	Architecture        ModelArchitecture       `json:"architecture"`
	Pricing             ModelPricing            `json:"pricing"`
	TopProvider         ModelTopProvider        `json:"top_provider"`
	PerRequestLimits    *ModelPerRequestLimits  `json:"per_request_limits"`
	DefaultParameters   *ModelDefaultParameters `json:"default_parameters"`
	SupportedParameters []Parameter             `json:"supported_parameters"`
	SupportedVoices     []string                `json:"supported_voices"`
	Reasoning           *ModelReasoning         `json:"reasoning,omitempty"`
	Benchmarks          *ModelBenchmarks        `json:"benchmarks,omitempty"`
	Links               ModelLinks              `json:"links"`
}

Model represents an AI model available on OpenRouter.

type ModelArchitecture added in v1.0.0 

type ModelArchitecture struct {
	Modality         *string          `json:"modality"`
	InputModalities  []InputModality  `json:"input_modalities"`
	OutputModalities []OutputModality `json:"output_modalities"`
	InstructType     *InstructType    `json:"instruct_type"`
	Tokenizer        ModelGroup       `json:"tokenizer,omitempty"`
}

ModelArchitecture represents the architecture information of a model.

type ModelBenchmarks added in v1.0.0 

type ModelBenchmarks struct {
	ArtificialAnalysis *ArtificialAnalysisBenchmark `json:"artificial_analysis,omitempty"`
	DesignArena        []DesignArenaBenchmark       `json:"design_arena"`
}

ModelBenchmarks represents third-party benchmark rankings of a model. It is omitted when no benchmark data is available.

type ModelCategory added in v1.0.0 

type ModelCategory string

ModelCategory is a use case category models can be filtered by. 

const (
	ModelCategoryProgramming  ModelCategory = "programming"
	ModelCategoryRoleplay     ModelCategory = "roleplay"
	ModelCategoryMarketing    ModelCategory = "marketing"
	ModelCategoryMarketingSEO ModelCategory = "marketing/seo"
	ModelCategoryTechnology   ModelCategory = "technology"
	ModelCategoryScience      ModelCategory = "science"
	ModelCategoryTranslation  ModelCategory = "translation"
	ModelCategoryLegal        ModelCategory = "legal"
	ModelCategoryFinance      ModelCategory = "finance"
	ModelCategoryHealth       ModelCategory = "health"
	ModelCategoryTrivia       ModelCategory = "trivia"
	ModelCategoryAcademia     ModelCategory = "academia"
)

type ModelDefaultParameters added in v1.0.0 

type ModelDefaultParameters struct {
	Temperature       *float64 `json:"temperature"`
	TopP              *float64 `json:"top_p"`
	TopK              *int     `json:"top_k"`
	FrequencyPenalty  *float64 `json:"frequency_penalty"`
	PresencePenalty   *float64 `json:"presence_penalty"`
	RepetitionPenalty *float64 `json:"repetition_penalty"`
}

ModelDefaultParameters represents the default sampling parameters of a model.

type ModelEndpoint added in v1.1.4 

type ModelEndpoint struct {
	Name                    string                   `json:"name"`
	ModelID                 string                   `json:"model_id"`
	ModelName               string                   `json:"model_name"`
	ContextLength           int                      `json:"context_length"`
	Pricing                 ModelPricing             `json:"pricing"`
	ProviderName            string                   `json:"provider_name"`
	Tag                     string                   `json:"tag"`
	Quantization            Quantization             `json:"quantization"`
	MaxCompletionTokens     *int                     `json:"max_completion_tokens"`
	MaxPromptTokens         *int                     `json:"max_prompt_tokens"`
	SupportedParameters     []Parameter              `json:"supported_parameters"`
	Status                  int                      `json:"status"`
	UptimeLast30m           *float64                 `json:"uptime_last_30m"`
	UptimeLast5m            *float64                 `json:"uptime_last_5m"`
	UptimeLast1d            *float64                 `json:"uptime_last_1d"`
	SupportsImplicitCaching bool                     `json:"supports_implicit_caching"`
	SupportsVoiceCloning    bool                     `json:"supports_voice_cloning"`
	LatencyLast30m          *EndpointLatencyStats    `json:"latency_last_30m"`
	ThroughputLast30m       *EndpointThroughputStats `json:"throughput_last_30m"`
}

ModelEndpoint represents a single provider endpoint serving a model.

type ModelEndpoints added in v1.1.4 

type ModelEndpoints struct {
	ID           string            `json:"id"`
	Name         string            `json:"name"`
	Created      int64             `json:"created"`
	Description  string            `json:"description"`
	Architecture ModelArchitecture `json:"architecture"`
	Endpoints    []ModelEndpoint   `json:"endpoints"`
}

ModelEndpoints represents a model together with the provider endpoints serving it.

type ModelGroup added in v1.0.0 

type ModelGroup string

ModelGroup is the tokenizer type (model family) used by a model. 

const (
	ModelGroupRouter   ModelGroup = "Router"
	ModelGroupMedia    ModelGroup = "Media"
	ModelGroupOther    ModelGroup = "Other"
	ModelGroupGPT      ModelGroup = "GPT"
	ModelGroupClaude   ModelGroup = "Claude"
	ModelGroupGemini   ModelGroup = "Gemini"
	ModelGroupGemma    ModelGroup = "Gemma"
	ModelGroupGrok     ModelGroup = "Grok"
	ModelGroupCohere   ModelGroup = "Cohere"
	ModelGroupNova     ModelGroup = "Nova"
	ModelGroupQwen     ModelGroup = "Qwen"
	ModelGroupYi       ModelGroup = "Yi"
	ModelGroupDeepSeek ModelGroup = "DeepSeek"
	ModelGroupMistral  ModelGroup = "Mistral"
	ModelGroupLlama2   ModelGroup = "Llama2"
	ModelGroupLlama3   ModelGroup = "Llama3"
	ModelGroupLlama4   ModelGroup = "Llama4"
	ModelGroupPaLM     ModelGroup = "PaLM"
	ModelGroupRWKV     ModelGroup = "RWKV"
	ModelGroupQwen3    ModelGroup = "Qwen3"
)
type ModelLinks struct {
	Details string `json:"details"`
}

ModelLinks represents related api endpoints and resources of a model.

type ModelPerRequestLimits added in v1.0.0 

type ModelPerRequestLimits struct {
	PromptTokens     StringifiedNumber `json:"prompt_tokens"`
	CompletionTokens StringifiedNumber `json:"completion_tokens"`
}

ModelPerRequestLimits represents the per-request token limits of a model.

type ModelPricing added in v1.0.0 

type ModelPricing struct {
	Prompt            StringifiedNumber      `json:"prompt"`
	Completion        StringifiedNumber      `json:"completion"`
	Request           StringifiedNumber      `json:"request,omitempty"`
	Image             StringifiedNumber      `json:"image,omitempty"`
	ImageOutput       StringifiedNumber      `json:"image_output,omitempty"`
	ImageToken        StringifiedNumber      `json:"image_token,omitempty"`
	Audio             StringifiedNumber      `json:"audio,omitempty"`
	AudioOutput       StringifiedNumber      `json:"audio_output,omitempty"`
	InputAudioCache   StringifiedNumber      `json:"input_audio_cache,omitempty"`
	InputCacheRead    StringifiedNumber      `json:"input_cache_read,omitempty"`
	InputCacheWrite   StringifiedNumber      `json:"input_cache_write,omitempty"`
	InputCacheWrite1H StringifiedNumber      `json:"input_cache_write_1h,omitempty"`
	InternalReasoning StringifiedNumber      `json:"internal_reasoning,omitempty"`
	WebSearch         StringifiedNumber      `json:"web_search,omitempty"`
	Discount          float64                `json:"discount"`
	Overrides         []ModelPricingOverride `json:"overrides,omitempty"`
}

ModelPricing represents the pricing information of a model. All prices are in USD, per token unless documented otherwise.

type ModelPricingOverride added in v1.0.0 

type ModelPricingOverride struct {
	Prompt            StringifiedNumber `json:"prompt,omitempty"`
	Completion        StringifiedNumber `json:"completion,omitempty"`
	Audio             StringifiedNumber `json:"audio,omitempty"`
	InputAudioCache   StringifiedNumber `json:"input_audio_cache,omitempty"`
	InputCacheRead    StringifiedNumber `json:"input_cache_read,omitempty"`
	InputCacheWrite   StringifiedNumber `json:"input_cache_write,omitempty"`
	InputCacheWrite1H StringifiedNumber `json:"input_cache_write_1h,omitempty"`
	MinPromptTokens   *float64          `json:"min_prompt_tokens,omitempty"`
	UTCStart          *float64          `json:"utc_start,omitempty"`
	UTCEnd            *float64          `json:"utc_end,omitempty"`
}

ModelPricingOverride represents a conditional override of the base pricing. An entry applies only when all of its condition fields match the request, among applicable entries later entries win per price key and keys absent from an entry inherit the base price.

type ModelReasoning added in v1.0.0 

type ModelReasoning struct {
	Mandatory         bool              `json:"mandatory"`
	DefaultEffort     *ReasoningEffort  `json:"default_effort,omitempty"`
	DefaultEnabled    *bool             `json:"default_enabled,omitempty"`
	SupportedEfforts  []ReasoningEffort `json:"supported_efforts"`
	SupportsMaxTokens *bool             `json:"supports_max_tokens,omitempty"`
}

ModelReasoning represents the reasoning effort configuration of a model. It is omitted for non-reasoning models and dynamic router models.

type ModelRegion added in v1.0.0 

type ModelRegion string

ModelRegion is a data region models can be filtered by. 

const (
	ModelRegionEU ModelRegion = "eu"
)

type ModelSort added in v1.0.0 

type ModelSort string

ModelSort is a server-side ordering of the models list. Models without a score for the chosen benchmark are placed last. 

const (
	ModelSortMostPopular             ModelSort = "most-popular"
	ModelSortNewest                  ModelSort = "newest"
	ModelSortTopWeekly               ModelSort = "top-weekly"
	ModelSortPricingLowToHigh        ModelSort = "pricing-low-to-high"
	ModelSortPricingHighToLow        ModelSort = "pricing-high-to-low"
	ModelSortContextHighToLow        ModelSort = "context-high-to-low"
	ModelSortThroughputHighToLow     ModelSort = "throughput-high-to-low"
	ModelSortLatencyLowToHigh        ModelSort = "latency-low-to-high"
	ModelSortIntelligenceHighToLow   ModelSort = "intelligence-high-to-low"
	ModelSortCodingHighToLow         ModelSort = "coding-high-to-low"
	ModelSortAgenticHighToLow        ModelSort = "agentic-high-to-low"
	ModelSortDesignArenaELOHighToLow ModelSort = "design-arena-elo-high-to-low"
)

type ModelTopProvider added in v1.0.0 

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

ModelTopProvider represents information about the top provider of a model.

type ModerationError added in v1.0.2 

type ModerationError struct {
	ErrorStatus

	Message      string
	Reasons      []string
	FlaggedInput string
	ProviderName string
	ModelSlug    string
}

ModerationError represents input that was flagged before reaching a provider.

func (*ModerationError) Error added in v1.0.2 

func (m *ModerationError) Error() string

Error returns the formatted string representation of the moderation error.

type OpenAIClient added in v1.1.0 

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

OpenAIClient represents an OpenAI compatible API client. It sends requests in the OpenAI wire format and exposes the same methods as Client, returning the openingrouter types. Use NewOpenAIClient to build one directly or Client.ToOpenAI to derive one from an existing OpenRouter client.

func NewOpenAIClient added in v1.1.0 

func NewOpenAIClient(token string, options ...OpenAIOption) *OpenAIClient

NewOpenAIClient returns a new OpenAI compatible client instance with the api token and options. The default base url is https://api.openai.com/v1.

func (*OpenAIClient) CreateChatCompletion added in v1.1.0 

func (c *OpenAIClient) CreateChatCompletion(ctx context.Context, request ChatCompletionRequest) (*ChatCompletionResponse, error)

CreateChatCompletion sends a chat completion request and returns the response.

func (*OpenAIClient) CreateChatCompletionStream added in v1.1.0 

func (c *OpenAIClient) CreateChatCompletionStream(ctx context.Context, request ChatCompletionRequest) (OpenrouterStream[ChatStreamChunk], error)

CreateChatCompletionStream sends a streaming chat completion request and returns a stream of completion chunks.

func (*OpenAIClient) CreateEmbeddings added in v1.1.0 

func (c *OpenAIClient) CreateEmbeddings(ctx context.Context, request EmbeddingRequest) (*EmbeddingResponse, error)

CreateEmbeddings submits an embedding request and returns the response.

func (*OpenAIClient) Do added in v1.1.0 

func (c *OpenAIClient) Do(req *http.Request) (*http.Response, error)

Do sends an HTTP request and processes any returned API errors.

func (*OpenAIClient) GetModel added in v1.1.0 

func (c *OpenAIClient) GetModel(ctx context.Context, model string) (*Model, error)

GetModel retrieves a single model by its id.

func (*OpenAIClient) ListModels added in v1.1.0 

func (c *OpenAIClient) ListModels(ctx context.Context, _ *ListModelsOptions) ([]Model, error)

ListModels retrieves the list of models available on the OpenAI compatible API.

func (*OpenAIClient) NewRequest added in v1.1.0 

func (c *OpenAIClient) NewRequest(ctx context.Context, method, path string, data any) (*http.Request, error)

NewRequest constructs a new HTTP request targeting the OpenAI compatible API. It mirrors Client.NewRequest but omits the OpenRouter specific headers.

type OpenAICompatibleClient added in v1.1.1 

type OpenAICompatibleClient interface {
	NewRequest(ctx context.Context, method, path string, data any) (*http.Request, error)
	Do(req *http.Request) (*http.Response, error)

	ListModels(ctx context.Context, options *ListModelsOptions) ([]Model, error)

	CreateChatCompletion(ctx context.Context, request ChatCompletionRequest) (*ChatCompletionResponse, error)
	CreateChatCompletionStream(ctx context.Context, request ChatCompletionRequest) (OpenrouterStream[ChatStreamChunk], error)

	CreateEmbeddings(ctx context.Context, request EmbeddingRequest) (*EmbeddingResponse, error)
}

type OpenAIError added in v1.1.0 

type OpenAIError struct {
	ErrorStatus

	Message string
	Type    string
	Param   string
	Code    string
}

OpenAIError represents an error response returned by an OpenAI compatible API.

func (*OpenAIError) Error added in v1.1.0 

func (o *OpenAIError) Error() string

Error returns the formatted string representation of the OpenAI error.

type OpenAIOption added in v1.1.0 

type OpenAIOption func(*OpenAIClient)

OpenAIOption configures an OpenAI compatible API client.

func WithOpenAIBase added in v1.1.0 

func WithOpenAIBase(base string) OpenAIOption

WithOpenAIBase sets the base url of the client (default https://api.openai.com/v1). Panics if the given base is not a valid url.

func WithOpenAIHTTPClient added in v1.1.0 

func WithOpenAIHTTPClient(client *http.Client) OpenAIOption

WithOpenAIHTTPClient sets the http client for each request.

type OpenRouterError added in v1.0.0 

type OpenRouterError struct {
	ErrorStatus

	Message string

	// Metadata holds metadata shapes this package does not model yet (e.g.
	// guardrail patterns), preserved verbatim rather than dropped.
	Metadata json.RawMessage
}

OpenRouterError represents an error response returned by the OpenRouter API.

func (*OpenRouterError) Error added in v1.0.0 

func (o *OpenRouterError) Error() string

Error returns the formatted string representation of the OpenRouter error.

type OpenRouterMetadata added in v1.0.0 

type OpenRouterMetadata struct {
	Requested string            `json:"requested"`
	Strategy  RoutingStrategy   `json:"strategy"`
	Region    *string           `json:"region"`
	Summary   string            `json:"summary"`
	Attempt   int               `json:"attempt"`
	IsBYOK    bool              `json:"is_byok"`
	Endpoints EndpointsMetadata `json:"endpoints"`
	Attempts  []RouterAttempt   `json:"attempts,omitempty"`
	Params    *RouterParams     `json:"params,omitempty"`
	Pipeline  []PipelineStage   `json:"pipeline,omitempty"`
}

OpenRouterMetadata represents the routing metadata of a request. It is only returned when ChatCompletionRequest.MetadataLevel is enabled.

type OpenRouterResponse added in v1.0.0 

type OpenRouterResponse[T any] struct {
	Data T `json:"data"`
}

OpenRouterResponse is the root response of endpoints wrapping their payload in a data object.

type OpenrouterStream added in v1.0.0 

type OpenrouterStream[T any] interface {
	Recv() (T, error)
	Close()
}

OpenrouterStream represents a stream of typed elements.

type Option added in v1.0.0 

type Option func(*Client)

Option configures an OpenRouter API client.

func WithBase added in v1.0.0 

func WithBase(base string) Option

WithBase sets the base url of the client (default https://openrouter.ai/api/v1). Panics if the given base is not a valid url.

func WithClient added in v1.0.0 

func WithClient(client *http.Client) Option

WithClient sets the http client for each request.

func WithReferer added in v1.0.0 

func WithReferer(referer string) Option

WithReferer sets the HTTP-Referer header of each request.

func WithTitle added in v1.0.0 

func WithTitle(title string) Option

WithTitle sets the X-Title header of each request.

type OutputModality added in v1.0.0 

type OutputModality string

OutputModality is a modality a model produces as output. 

const (
	OutputModalityText          OutputModality = "text"
	OutputModalityImage         OutputModality = "image"
	OutputModalityEmbeddings    OutputModality = "embeddings"
	OutputModalityAudio         OutputModality = "audio"
	OutputModalityVideo         OutputModality = "video"
	OutputModalityRerank        OutputModality = "rerank"
	OutputModalitySpeech        OutputModality = "speech"
	OutputModalityTranscription OutputModality = "transcription"
)

type Parameter added in v1.0.0 

type Parameter string

Parameter is a request parameter that may be supported by a model. 

const (
	ParameterTemperature         Parameter = "temperature"
	ParameterTopP                Parameter = "top_p"
	ParameterTopK                Parameter = "top_k"
	ParameterMinP                Parameter = "min_p"
	ParameterTopA                Parameter = "top_a"
	ParameterFrequencyPenalty    Parameter = "frequency_penalty"
	ParameterPresencePenalty     Parameter = "presence_penalty"
	ParameterRepetitionPenalty   Parameter = "repetition_penalty"
	ParameterMaxTokens           Parameter = "max_tokens"
	ParameterMaxCompletionTokens Parameter = "max_completion_tokens"
	ParameterLogitBias           Parameter = "logit_bias"
	ParameterLogprobs            Parameter = "logprobs"
	ParameterTopLogprobs         Parameter = "top_logprobs"
	ParameterPrediction          Parameter = "prediction"
	ParameterSeed                Parameter = "seed"
	ParameterResponseFormat      Parameter = "response_format"
	ParameterStructuredOutputs   Parameter = "structured_outputs"
	ParameterStop                Parameter = "stop"
	ParameterTools               Parameter = "tools"
	ParameterToolChoice          Parameter = "tool_choice"
	ParameterParallelToolCalls   Parameter = "parallel_tool_calls"
	ParameterIncludeReasoning    Parameter = "include_reasoning"
	ParameterReasoning           Parameter = "reasoning"
	ParameterReasoningEffort     Parameter = "reasoning_effort"
	ParameterWebSearchOptions    Parameter = "web_search_options"
	ParameterVerbosity           Parameter = "verbosity"
)

type PipelineStage added in v1.0.0 

type PipelineStage struct {
	Type           PipelineStageType `json:"type"`
	Name           string            `json:"name"`
	Summary        string            `json:"summary,omitempty"`
	GuardrailID    string            `json:"guardrail_id,omitempty"`
	GuardrailScope string            `json:"guardrail_scope,omitempty"`
	CostUSD        *float64          `json:"cost_usd,omitempty"`
	Data           map[string]any    `json:"data,omitempty"`
}

PipelineStage represents a single stage of the request pipeline. Multiple plugins share a type, Name disambiguates which one emitted the stage.

type PipelineStageType added in v1.0.0 

type PipelineStageType string

PipelineStageType is the categorical kind of a pipeline stage. 

const (
	PipelineStageTypeGuardrail          PipelineStageType = "guardrail"
	PipelineStageTypePlugin             PipelineStageType = "plugin"
	PipelineStageTypeServerTools        PipelineStageType = "server_tools"
	PipelineStageTypeResponseHealing    PipelineStageType = "response_healing"
	PipelineStageTypeContextCompression PipelineStageType = "context_compression"
)

type PromptTokensDetails added in v1.0.0 

type PromptTokensDetails struct {
	CachedTokens     *int `json:"cached_tokens"`
	CacheWriteTokens *int `json:"cache_write_tokens"`
	AudioTokens      *int `json:"audio_tokens"`
	FileTokens       *int `json:"file_tokens"`
	VideoTokens      *int `json:"video_tokens"`
}

PromptTokensDetails represents the breakdown of tokens used in the prompt. CacheWriteTokens is only returned for models with explicit caching and cache write pricing.

type ProviderDataCollection added in v1.0.0 

type ProviderDataCollection string

ProviderDataCollection is the data collection policy an endpoint must satisfy. If no provider meets the requirement, the request fails. 

const (
	ProviderDataCollectionAllow ProviderDataCollection = "allow"
	ProviderDataCollectionDeny  ProviderDataCollection = "deny"
)

type ProviderError added in v1.0.0 

type ProviderError struct {
	ErrorStatus

	Raw          string
	ProviderName string
	IsBYOK       bool
}

ProviderError represents an error returned by an underlying model provider.

func (*ProviderError) Error added in v1.0.0 

func (p *ProviderError) Error() string

Error returns the formatted string representation of the provider error.

type ProviderLatencyCutoffs added in v1.0.0 

type ProviderLatencyCutoffs struct {
	P50 *float64 `json:"p50,omitempty"`
	P75 *float64 `json:"p75,omitempty"`
	P90 *float64 `json:"p90,omitempty"`
	P99 *float64 `json:"p99,omitempty"`
}

ProviderLatencyCutoffs represents the preferred maximum latency of an endpoint in seconds, per percentile. Endpoints above a cutoff may still be used, but are deprioritized in routing. All given cutoffs must be met to be preferred.

type ProviderMaxPrice added in v1.0.0 

type ProviderMaxPrice struct {
	Prompt     StringifiedNumber `json:"prompt,omitempty"`
	Completion StringifiedNumber `json:"completion,omitempty"`
	Image      StringifiedNumber `json:"image,omitempty"`
	Audio      StringifiedNumber `json:"audio,omitempty"`
	Request    StringifiedNumber `json:"request,omitempty"`
}

ProviderMaxPrice represents the maximum price a request may cost. Token prices are in USD per million tokens, the rest per unit.

type ProviderOptions added in v1.0.0 

type ProviderOptions map[string]map[string]any

ProviderOptions holds provider specific options keyed by provider slug. Only the options of the matched provider are forwarded, the rest are ignored and unrecognized keys are silently dropped.

type ProviderPreferences added in v1.0.0 

type ProviderPreferences struct {
	Order          []string            `json:"order,omitempty"`
	Only           []string            `json:"only,omitempty"`
	Ignore         []string            `json:"ignore,omitempty"`
	AllowFallbacks *bool               `json:"allow_fallbacks,omitempty"`
	Sort           *ProviderSortConfig `json:"sort,omitempty"`
	Options        ProviderOptions     `json:"options,omitempty"`

	DataCollection         ProviderDataCollection     `json:"data_collection,omitempty"`
	EnforceDistillableText *bool                      `json:"enforce_distillable_text,omitempty"`
	MaxPrice               *ProviderMaxPrice          `json:"max_price,omitempty"`
	PreferredMaxLatency    *ProviderLatencyCutoffs    `json:"preferred_max_latency,omitempty"`
	PreferredMinThroughput *ProviderThroughputCutoffs `json:"preferred_min_throughput,omitempty"`
	Quantizations          []Quantization             `json:"quantizations,omitempty"`
	RequireParameters      *bool                      `json:"require_parameters,omitempty"`
	ZDR                    *bool                      `json:"zdr,omitempty"`
}

ProviderPreferences represents the provider routing preferences and provider specific passthrough configuration of a request. Order, Only and Ignore are merged with the account-wide settings.

type ProviderSort added in v1.0.0 

type ProviderSort string

ProviderSort is the sorting strategy used to pick an endpoint. 

const (
	ProviderSortPrice      ProviderSort = "price"
	ProviderSortThroughput ProviderSort = "throughput"
	ProviderSortLatency    ProviderSort = "latency"
	ProviderSortExacto     ProviderSort = "exacto"
)

type ProviderSortConfig added in v1.0.0 

type ProviderSortConfig struct {
	By        ProviderSort          `json:"by,omitempty"`
	Partition ProviderSortPartition `json:"partition,omitempty"`
}

ProviderSortConfig represents the sorting strategy used for a request when no explicit order is given. Setting it disables load balancing.

type ProviderSortPartition added in v1.0.0 

type ProviderSortPartition string

ProviderSortPartition is the partitioning strategy applied before sorting. Model groups endpoints by model so fallback models remain fallbacks, none sorts all endpoints together regardless of model. 

const (
	ProviderSortPartitionModel ProviderSortPartition = "model"
	ProviderSortPartitionNone  ProviderSortPartition = "none"
)

type ProviderThroughputCutoffs added in v1.0.0 

type ProviderThroughputCutoffs struct {
	P50 *float64 `json:"p50,omitempty"`
	P75 *float64 `json:"p75,omitempty"`
	P90 *float64 `json:"p90,omitempty"`
	P99 *float64 `json:"p99,omitempty"`
}

ProviderThroughputCutoffs represents the preferred minimum throughput of an endpoint in tokens per second, per percentile. Endpoints below a cutoff may still be used, but are deprioritized in routing. All given cutoffs must be met to be preferred.

type Quantization added in v1.0.0 

type Quantization string

Quantization is the quantization level of an endpoint. 

const (
	QuantizationInt4    Quantization = "int4"
	QuantizationInt8    Quantization = "int8"
	QuantizationFP4     Quantization = "fp4"
	QuantizationMXFP4   Quantization = "mxfp4"
	QuantizationNVFP4   Quantization = "nvfp4"
	QuantizationFP6     Quantization = "fp6"
	QuantizationFP8     Quantization = "fp8"
	QuantizationMXFP8   Quantization = "mxfp8"
	QuantizationFP16    Quantization = "fp16"
	QuantizationBF16    Quantization = "bf16"
	QuantizationFP32    Quantization = "fp32"
	QuantizationUnknown Quantization = "unknown"
)

type ReasoningEffort added in v1.0.0 

type ReasoningEffort string

ReasoningEffort is a reasoning effort level, in descending effort order. 

const (
	ReasoningEffortMax     ReasoningEffort = "max"
	ReasoningEffortXHigh   ReasoningEffort = "xhigh"
	ReasoningEffortHigh    ReasoningEffort = "high"
	ReasoningEffortMedium  ReasoningEffort = "medium"
	ReasoningEffortLow     ReasoningEffort = "low"
	ReasoningEffortMinimal ReasoningEffort = "minimal"
	ReasoningEffortNone    ReasoningEffort = "none"
)

type RouterAttempt added in v1.0.0 

type RouterAttempt struct {
	Provider string `json:"provider"`
	Model    string `json:"model"`
	Status   int    `json:"status"`
}

RouterAttempt represents a single upstream attempt of a request.

type RouterParams added in v1.0.0 

type RouterParams struct {
	QualityFloor    *float64 `json:"quality_floor,omitempty"`
	ThroughputFloor *float64 `json:"throughput_floor,omitempty"`
	VersionGroup    string   `json:"version_group,omitempty"`
}

RouterParams represents the routing parameters a request was resolved with.

type RoutingStrategy added in v1.0.0 

type RoutingStrategy string

RoutingStrategy is the strategy a request was routed with. 

const (
	RoutingStrategyDirect      RoutingStrategy = "direct"
	RoutingStrategyAuto        RoutingStrategy = "auto"
	RoutingStrategyFree        RoutingStrategy = "free"
	RoutingStrategyLatest      RoutingStrategy = "latest"
	RoutingStrategyAlias       RoutingStrategy = "alias"
	RoutingStrategyFallback    RoutingStrategy = "fallback"
	RoutingStrategyPareto      RoutingStrategy = "pareto"
	RoutingStrategyBodybuilder RoutingStrategy = "bodybuilder"
	RoutingStrategyFusion      RoutingStrategy = "fusion"
)

type STTInputAudio added in v1.0.0 

type STTInputAudio struct {
	Data   string `json:"data"`
	Format string `json:"format"`
}

STTInputAudio holds base64-encoded audio data and its format to transcribe.

type STTProviderPreferences added in v1.0.0 

type STTProviderPreferences struct {
	Options ProviderOptions `json:"options,omitempty"`
}

STTProviderPreferences represents the provider specific passthrough configuration of a speech-to-text request.

type STTRequest added in v1.0.0 

type STTRequest struct {
	Model      string        `json:"model"`
	InputAudio STTInputAudio `json:"input_audio"`

	Language               string                    `json:"language,omitempty"`
	Provider               *STTProviderPreferences   `json:"provider,omitempty"`
	ResponseFormat         STTResponseFormat         `json:"response_format,omitempty"`
	Temperature            *float64                  `json:"temperature,omitempty"`
	TimestampGranularities []STTTimestampGranularity `json:"timestamp_granularities,omitempty"`
}

STTRequest represents the request body of the speech-to-text transcription endpoint. Model and InputAudio are required, zero values and nil pointers of the remaining fields are omitted from the request.

type STTResponse added in v1.0.0 

type STTResponse struct {
	Text string `json:"text"`

	Duration *float64     `json:"duration,omitempty"`
	Language string       `json:"language,omitempty"`
	Segments []STTSegment `json:"segments,omitempty"`
	Task     string       `json:"task,omitempty"`
	Usage    *STTUsage    `json:"usage,omitempty"`
	Words    []STTWord    `json:"words,omitempty"`
}

STTResponse is the root response returned by the speech-to-text transcription endpoint. Text is required and always present. Additional fields such as Duration, Language, Segments, Task, and Words are populated when ResponseFormat is set to verbose_json.

type STTResponseFormat added in v1.0.0 

type STTResponseFormat string

STTResponseFormat is the output response format of a transcription request. 

const (
	STTResponseFormatJSON        STTResponseFormat = "json"
	STTResponseFormatVerboseJSON STTResponseFormat = "verbose_json"
)

type STTSegment added in v1.0.0 

type STTSegment struct {
	ID               int     `json:"id"`
	Seek             int     `json:"seek"`
	Start            float64 `json:"start"`
	End              float64 `json:"end"`
	Text             string  `json:"text"`
	Tokens           []int   `json:"tokens,omitempty"`
	Temperature      float64 `json:"temperature"`
	AvgLogprob       float64 `json:"avg_logprob"`
	CompressionRatio float64 `json:"compression_ratio"`
	NoSpeechProb     float64 `json:"no_speech_prob"`
	Speaker          *int    `json:"speaker,omitempty"`
}

STTSegment represents a timestamped transcript segment, returned when ResponseFormat is verbose_json.

type STTTimestampGranularity added in v1.0.0 

type STTTimestampGranularity string

STTTimestampGranularity is a timestamp detail level for verbose_json transcription responses. 

const (
	STTTimestampGranularityWord    STTTimestampGranularity = "word"
	STTTimestampGranularitySegment STTTimestampGranularity = "segment"
)

type STTUsage added in v1.0.0 

type STTUsage struct {
	Cost         *float64 `json:"cost,omitempty"`
	InputTokens  int      `json:"input_tokens,omitempty"`
	OutputTokens int      `json:"output_tokens,omitempty"`
	Seconds      *float64 `json:"seconds,omitempty"`
	TotalTokens  int      `json:"total_tokens,omitempty"`
}

STTUsage represents aggregated usage statistics for a speech-to-text request.

type STTWord added in v1.0.0 

type STTWord struct {
	Word    string  `json:"word"`
	Start   float64 `json:"start"`
	End     float64 `json:"end"`
	Speaker *int    `json:"speaker,omitempty"`
}

STTWord represents a timestamped word, returned when the provider includes word-level timestamps.

type ServerSentEventsStream added in v1.0.0 

type ServerSentEventsStream[T any] struct {
	// contains filtered or unexported fields
}

ServerSentEventsStream receives Server-Sent Events from an HTTP response.

func NewServerSentEventsStream added in v1.0.0 

func NewServerSentEventsStream[T any](ctx context.Context, resp *http.Response) *ServerSentEventsStream[T]

NewServerSentEventsStream starts a background reader over resp.Body and yields decoded T values. The returned stream owns resp: call Close (typically via defer) to cancel the reader and release the body.

func (*ServerSentEventsStream[T]) Close added in v1.0.0 

func (s *ServerSentEventsStream[T]) Close()

Close terminates the stream and cleans up resources.

func (*ServerSentEventsStream[T]) Recv added in v1.0.0 

func (s *ServerSentEventsStream[T]) Recv() (T, error)

Recv reads the next chunk from the stream.

type ServerToolUse added in v1.0.0 

type ServerToolUse struct {
	ToolCallsRequested *int `json:"tool_calls_requested"`
	ToolCallsExecuted  *int `json:"tool_calls_executed"`
	WebSearchRequests  *int `json:"web_search_requests"`
}

ServerToolUse represents the usage of server-side tool execution. A server-orchestrated web search is counted in both ToolCallsRequested and WebSearchRequests, provider-native web search may report WebSearchRequests only, so the two must not be summed.

type SpeechProviderPreferences added in v1.0.0 

type SpeechProviderPreferences struct {
	Options ProviderOptions `json:"options,omitempty"`
}

SpeechProviderPreferences represents the provider specific passthrough configuration of a speech request. Unlike ProviderPreferences the speech endpoint accepts passthrough options only, there is no provider routing.

type SpeechRequest added in v1.0.0 

type SpeechRequest struct {
	Model string `json:"model"`
	Input string `json:"input"`
	Voice string `json:"voice"`

	Provider       *SpeechProviderPreferences `json:"provider,omitempty"`
	ResponseFormat SpeechResponseFormat       `json:"response_format,omitempty"`
	Speed          *float64                   `json:"speed,omitempty"`
}

SpeechRequest represents the request body of the speech synthesis endpoint. Model, Input and Voice are required, zero values and nil pointers of the remaining fields are omitted from the request. Voice identifiers are provider specific, the supported set of a model is listed in Model.SupportedVoices.

type SpeechResponse added in v1.0.0 

type SpeechResponse struct {
	GenerationID string
	ContentType  string
	Body         io.ReadCloser
}

SpeechResponse represents the synthesized audio of a speech request. Body is the raw audio bytestream and is owned by the caller, it must be closed once read. ContentType is the media type of the bytestream and varies by the requested format (audio/mpeg for mp3, audio/pcm for 16-bit little-endian pcm).

type SpeechResponseFormat added in v1.0.0 

type SpeechResponseFormat string

SpeechResponseFormat is the audio encoding of a synthesized bytestream. It defaults to pcm. 

const (
	SpeechResponseFormatMP3 SpeechResponseFormat = "mp3"
	SpeechResponseFormatPCM SpeechResponseFormat = "pcm"
)

type StringifiedNumber 

type StringifiedNumber float64

StringifiedNumber represents a number that was stringified in JSON

func (StringifiedNumber) Float64 

func (sn StringifiedNumber) Float64() float64

Float64 returns the float64 value

func (StringifiedNumber) MarshalJSON 

func (sn StringifiedNumber) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface for StringifiedNumber.

func (*StringifiedNumber) UnmarshalJSON 

func (sn *StringifiedNumber) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface for StringifiedNumber.

type SubError added in v1.0.2 

type SubError struct {
	Code         int64  `json:"code"`
	Message      string `json:"message"`
	ProviderName string `json:"provider_name"`
	Raw          string `json:"raw"`
}

SubError is one failed upstream attempt from metadata.previous_errors.

type Usage added in v1.0.0 

type Usage struct {
	PromptTokens            int                       `json:"prompt_tokens"`
	CompletionTokens        int                       `json:"completion_tokens"`
	TotalTokens             int                       `json:"total_tokens"`
	Cost                    *float64                  `json:"cost"`
	CostDetails             *CostDetails              `json:"cost_details"`
	PromptTokensDetails     *PromptTokensDetails      `json:"prompt_tokens_details"`
	CompletionTokensDetails *CompletionTokensDetails  `json:"completion_tokens_details"`
	ServerToolUse           *ServerToolUse            `json:"server_tool_use"`
	CacheCreation           *AnthropicCacheCreation   `json:"cache_creation"`
	Iterations              []AnthropicUsageIteration `json:"iterations"`
	Speed                   AnthropicSpeed            `json:"speed,omitempty"`
	ServiceTier             *string                   `json:"service_tier"`
	IsBYOK                  bool                      `json:"is_byok"`
}

Usage represents the token and cost usage of a request, when available.

Source Files

View all Source files

Directories

Path Synopsis
internal
openai
Package openai holds the wire types of the OpenAI api.
 Package openai holds the wire types of the OpenAI api.

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.