openrouter

README

openrouter

openrouter is a Go client for the OpenRouter API. It implements the github.com/goloop/ai interface, so it looks and works like every other goloop AI provider. OpenRouter is a routing gateway: one API and key reach many model providers, with models namespaced as provider/model.

Features

• Chat completions: Generate for a single response, Stream for token-by-token output through iter.Seq2.
• Tool use (function calling), multimodal image input and system prompts.
• Native ChatCompletion and ChatCompletionStream with the full option set.
• Model listing across all routed providers.
• App-attribution headers via WithReferer and WithTitle.
• Retries on 429 and 5xx with backoff; normalized, typed API errors.
• Depends only on github.com/goloop/ai and the standard library.
• Structured output: ai.Format maps onto the provider's response_format (JSON mode or a JSON Schema); read the reply with resp.JSON(&v).
• Hosted capabilities: ai.Request.Hosted is refused with ai.ErrNoHosted, because a hosted search here depends on the route rather than the provider.

Installation

go get github.com/goloop/openrouter

Quick start

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/goloop/ai"
	"github.com/goloop/openrouter"
)

func main() {
	c := openrouter.New(os.Getenv("OPENROUTER_API_KEY"),
		openrouter.WithReferer("https://myapp.example"),
		openrouter.WithTitle("My App"),
	)

	resp, err := c.Generate(context.Background(), &ai.Request{
		Model:    openrouter.ModelClaudeSonnet,
		Messages: []ai.Message{ai.UserText("Say hello in one word.")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(resp.Text())
}

Streaming

for chunk, err := range c.Stream(ctx, req) {
	if err != nil {
		break
	}
	fmt.Print(chunk.Text)
}

Choosing a model

Any provider/model string works; a few are provided as constants (ModelGPT4o, ModelClaudeSonnet, ModelGeminiFlash, ...). List everything available with c.Models(ctx), or fetch one with c.GetModel(ctx, id).

Documentation

Full reference: DOC.md (Ukrainian: DOC.UK.md).

Contributing

See CONTRIBUTING.md.

License

MIT - see LICENSE.

Documentation

Overview

Package openrouter is a client for the OpenRouter API, built on the goloop/ai interface.

OpenRouter is a routing gateway: one API and key reach many model providers, with models namespaced as "provider/model". The Client implements ai.Client, so Generate and Stream work the same as with any other goloop AI provider. On top of that it exposes the native chat completions endpoint with its full options, model listing and single-model lookup. The wire format is chat-completions compatible.

c := openrouter.New(os.Getenv("OPENROUTER_API_KEY"))
resp, err := c.Generate(ctx, &ai.Request{
    Model:    openrouter.ModelClaudeSonnet,
    Messages: []ai.Message{ai.UserText("Say hello in one word.")},
})

Structured output

ai.Request.Format maps onto the provider's response_format, so a request for JSON is enforced rather than merely asked for, and ai.Response.JSON decodes the reply. Plain JSON mode also puts ai.Format.Instruction into the system prompt, because this wire format rejects json_object unless the word "json" appears in the messages.

Hosted capabilities

This provider routes to models rather than serving one, so what a request can do depends on the route behind it, and a hosted search is a routing feature rather than a tool the model is offered. ai.Hosted is refused with ai.ErrNoHosted rather than answered differently per route.

The refusal is the documented behavior, not a gap waiting to be filled in silence: an answer produced without the search that was asked for looks exactly like one produced with it. A caller who would rather have the answer anyway asks again without ai.Request.Hosted.

Asking what this driver can do

Capabilities describes this driver for the decision taken before a call: whether to offer a feature at all, and whether it needs one request or two.

if ai.SupportsHosted(c, ai.Hosted{Kind: ai.HostedWebSearch}) { ... }

It is a hint and not a permission - support also depends on the model, the account and the region - so ai.ErrNoHosted and ai.ErrNoFormat remain the source of truth and a caller still handles them. What changes is that a refusal the provider only reports as a 400 now arrives as those same sentinels, wrapped around the original ai.APIError, so one errors.Is covers a limitation this driver knew in advance and one it learned over the wire.

WithReferer and WithTitle set the app-attribution headers OpenRouter uses for ranking. It depends only on goloop/ai and the standard library.

Index

• Constants
• type ChatChoice
• type ChatFunctionCall
• type ChatFunctionDef
• type ChatMessage
• type ChatRequest
• type ChatResponse
• type ChatStreamChunk
• type ChatTool
• type ChatToolCall
• type ChatUsage
• type Client
  • func New(apiKey string, opts ...Option) *Client
  • func (c *Client) Capabilities() ai.Capabilities
  • func (c *Client) ChatCompletion(ctx context.Context, req *ChatRequest) (*ChatResponse, error)
  • func (c *Client) ChatCompletionStream(ctx context.Context, req *ChatRequest) iter.Seq2[ChatStreamChunk, error]
  • func (c *Client) Generate(ctx context.Context, req *ai.Request) (*ai.Response, error)
  • func (c *Client) GetModel(ctx context.Context, id string) (*Model, error)
  • func (c *Client) Models(ctx context.Context) ([]Model, error)
  • func (c *Client) Stream(ctx context.Context, req *ai.Request) iter.Seq2[ai.Chunk, error]
• type Model
• type Option
  • func WithBaseURL(u string) Option
  • func WithHTTPClient(c *http.Client) Option
  • func WithHeader(key, value string) Option
  • func WithMaxRetries(n int) Option
  • func WithReferer(url string) Option
  • func WithTimeout(d time.Duration) Option
  • func WithTitle(title string) Option

Examples

• Client.Generate
• Client.GetModel
• New

Constants

const (
	ModelGPT4o        = "openai/gpt-4o"
	ModelClaudeSonnet = "anthropic/claude-sonnet-4"
	ModelGeminiFlash  = "google/gemini-2.5-flash"
	ModelLlama3170B   = "meta-llama/llama-3.1-70b-instruct"
	ModelDeepSeekChat = "deepseek/deepseek-chat"
	ModelMistralLarge = "mistralai/mistral-large"
)

Convenience model identifiers. OpenRouter routes to many providers; a model is namespaced as "provider/model". Any model string is accepted; use Models to discover what is available.

const DefaultBaseURL = "https://openrouter.ai/api/v1"

DefaultBaseURL is the OpenRouter API base URL, including the version segment.

Types

type ChatChoice

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

ChatChoice is one completion choice.

type ChatFunctionCall

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

ChatFunctionCall is the function name and JSON-encoded arguments of a call.

type ChatFunctionDef

type ChatFunctionDef struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	Parameters  json.RawMessage `json:"parameters,omitempty"`
}

ChatFunctionDef is a function's name, description and JSON Schema parameters.

type ChatMessage

type ChatMessage struct {
	Role       string         `json:"role"`
	Content    any            `json:"content,omitempty"`
	Name       string         `json:"name,omitempty"`
	ToolCalls  []ChatToolCall `json:"tool_calls,omitempty"`
	ToolCallID string         `json:"tool_call_id,omitempty"`
}

ChatMessage is one message in a chat request or response. Content is a string or a slice of content parts (for images).

type ChatRequest

type ChatRequest struct {
	Model          string          `json:"model"`
	Messages       []ChatMessage   `json:"messages"`
	Tools          []ChatTool      `json:"tools,omitempty"`
	ToolChoice     any             `json:"tool_choice,omitempty"`
	Temperature    *float64        `json:"temperature,omitempty"`
	TopP           *float64        `json:"top_p,omitempty"`
	MaxTokens      int             `json:"max_tokens,omitempty"`
	Stop           []string        `json:"stop,omitempty"`
	N              int             `json:"n,omitempty"`
	Seed           *int            `json:"seed,omitempty"`
	ResponseFormat json.RawMessage `json:"response_format,omitempty"`
	User           string          `json:"user,omitempty"`
	Stream         bool            `json:"stream,omitempty"`
	StreamOptions  *streamOptions  `json:"stream_options,omitempty"`
}

ChatRequest is the native chat completions request, exposing the full option set (response_format, seed, n and so on). Build one directly for features the shared ai.Request does not model, or let Generate build it.

type ChatResponse

type ChatResponse struct {
	ID      string       `json:"id"`
	Object  string       `json:"object"`
	Model   string       `json:"model"`
	Choices []ChatChoice `json:"choices"`
	Usage   ChatUsage    `json:"usage"`
}

ChatResponse is the native chat completions response.

type ChatStreamChunk

type ChatStreamChunk struct {
	ID      string `json:"id"`
	Model   string `json:"model"`
	Choices []struct {
		Index int `json:"index"`
		Delta struct {
			Content   string `json:"content"`
			ToolCalls []struct {
				Index    int    `json:"index"`
				ID       string `json:"id"`
				Function struct {
					Name      string `json:"name"`
					Arguments string `json:"arguments"`
				} `json:"function"`
			} `json:"tool_calls"`
		} `json:"delta"`
		FinishReason string `json:"finish_reason"`
	} `json:"choices"`
	Usage *ChatUsage `json:"usage"`
}

ChatStreamChunk is one streamed chat completions event.

type ChatTool

type ChatTool struct {
	Type     string          `json:"type"`
	Function ChatFunctionDef `json:"function"`
}

ChatTool declares a callable function.

type ChatToolCall

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

ChatToolCall is a tool call the model produced.

type ChatUsage

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

ChatUsage reports token usage for a chat completion.

type Client

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

Client is an OpenRouter API client. It implements ai.Client and adds the provider's native endpoints. The wire format is chat-completions compatible.

func New

func New(apiKey string, opts ...Option) *Client

New returns a Client for the given API key. Shared options (WithBaseURL, WithHTTPClient, WithTimeout, WithMaxRetries, WithHeader) and OpenRouter options (WithReferer, WithTitle) configure it.

Example

package main

import (
	"fmt"

	"github.com/goloop/openrouter"
)

func main() {
	c := openrouter.New("sk-or-...")
	_ = c // use c.Generate, c.Stream, c.ChatCompletion, ...
	fmt.Println(openrouter.ModelClaudeSonnet)
}

Output:
anthropic/claude-sonnet-4

func (*Client) Capabilities

func (c *Client) Capabilities() ai.Capabilities

Capabilities describes what this driver can be asked for. It is a hint for the decision taken before a call - whether to offer a feature, and whether it needs one request or two - and never a substitute for handling ai.ErrNoHosted, ai.ErrNoFormat or ai.ErrFormatWithHosted, because support also depends on the model, the account and the region.

func (*Client) ChatCompletion

func (c *Client) ChatCompletion(ctx context.Context, req *ChatRequest) (*ChatResponse, error)

ChatCompletion sends a native chat completions request and returns the whole response. Use it for provider-specific options; use Generate for the shared, provider-agnostic path.

func (*Client) ChatCompletionStream

func (c *Client) ChatCompletionStream(ctx context.Context, req *ChatRequest) iter.Seq2[ChatStreamChunk, error]

ChatCompletionStream sends a native streaming chat request and returns an iterator over the raw chunks.

func (*Client) Generate

func (c *Client) Generate(ctx context.Context, req *ai.Request) (*ai.Response, error)

Generate implements ai.Client over chat completions.

Example

ExampleClient_Generate builds a request. Sending it needs a real API key, so this example only shows the shape.

package main

import (
	"fmt"

	"github.com/goloop/ai"
	"github.com/goloop/openrouter"
)

func main() {
	req := &ai.Request{
		Model: openrouter.ModelGPT4o,
		Messages: []ai.Message{
			ai.UserText("Name the capital of France."),
		},
	}
	fmt.Println(req.Model, len(req.Messages))
}

Output:
openai/gpt-4o 1

func (*Client) GetModel

func (c *Client) GetModel(ctx context.Context, id string) (*Model, error)

GetModel returns the model with the given ID. OpenRouter has no per-model endpoint, so it looks the model up in the full list and reports a 404 ai.APIError when the ID is not routed.

Example

ExampleClient_GetModel notes single-model lookup. OpenRouter has no per-model endpoint, so GetModel finds the model in the full list and reports a 404 ai.APIError when the ID is not routed.

package main

import (
	"fmt"

	"github.com/goloop/openrouter"
)

func main() {
	c := openrouter.New("sk-or-...")
	_ = c // m, _ := c.GetModel(ctx, openrouter.ModelClaudeSonnet)
	fmt.Println(openrouter.ModelClaudeSonnet)
}

Output:
anthropic/claude-sonnet-4

func (*Client) Models

func (c *Client) Models(ctx context.Context) ([]Model, error)

Models lists the models OpenRouter can route to.

func (*Client) Stream

func (c *Client) Stream(ctx context.Context, req *ai.Request) iter.Seq2[ai.Chunk, error]

Stream implements ai.Client over streaming chat completions.

type Model

type Model struct {
	ID            string `json:"id"`
	Name          string `json:"name"`
	Description   string `json:"description,omitempty"`
	ContextLength int    `json:"context_length,omitempty"`
	Pricing       struct {
		Prompt     string `json:"prompt,omitempty"`
		Completion string `json:"completion,omitempty"`
	} `json:"pricing,omitempty"`
}

Model describes a model listed by OpenRouter.

type Option

type Option func(*settings)

Option configures a Client in New.

func WithBaseURL

func WithBaseURL(u string) Option

WithBaseURL overrides the API base URL (proxies, gateways, mock servers).

func WithHTTPClient

func WithHTTPClient(c *http.Client) Option

WithHTTPClient sets the HTTP client used for requests.

func WithHeader

func WithHeader(key, value string) Option

WithHeader adds a header sent with every request.

func WithMaxRetries

func WithMaxRetries(n int) Option

WithMaxRetries sets how many times a request is retried on 429 and 5xx.

func WithReferer

func WithReferer(url string) Option

WithReferer sets the HTTP-Referer header used for app attribution and ranking on openrouter.ai.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the per-request timeout when no custom HTTP client is set.

func WithTitle

func WithTitle(title string) Option

WithTitle sets the X-Title header used for app attribution and ranking on openrouter.ai.