openrouter

package module
v1.2.0 Latest Latest
Warning

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

 Go to latest Published: Dec 1, 2025 License: Unlicense Imports: 18 Imported by: 1

README

openrouter-go

Go Report Card GoDoc Go Version

A zero-dependency Go package providing complete bindings for the OpenRouter API, supporting all available endpoints with full streaming capabilities.

Features

  • ✅ Complete API coverage (chat completions, legacy completions, models, model endpoints, and providers)
  • ✅ Full streaming support with Server-Sent Events (SSE)
  • ✅ Zero external dependencies
  • ✅ Go 1.25.1 support
  • ✅ Comprehensive error handling and retry logic
  • ✅ Context-aware cancellation
  • ✅ Thread-safe client operations
  • ✅ Extensive configuration options via functional options pattern
  • ✅ Per-request Zero Data Retention (ZDR) enforcement
  • ✅ Structured outputs with JSON schema validation
  • ✅ Tool/Function calling support with streaming
  • ✅ Message transforms for automatic context window management
  • ✅ Web Search plugin for real-time web data integration
  • ✅ Image inputs (multimodal) with URL and base64 support
  • ✅ Audio inputs with base64 encoding support (WAV, MP3)
  • ✅ PDF inputs with configurable parsing engines and file annotation reuse
  • ✅ Model listing and discovery with category filtering
  • ✅ Model endpoint inspection with pricing and uptime details
  • ✅ Provider listing with policy information
  • ✅ Credit balance and usage tracking
  • ✅ Activity analytics for usage monitoring and cost tracking
  • ✅ API key information retrieval with usage and rate limit details
  • ✅ API key management with listing, filtering, and creation capabilities

Installation

go get github.com/hra42/openrouter-go

Quick Start

package main

import (
    "context"
    "fmt"
    "github.com/hra42/openrouter-go"
)

func main() {
    client := openrouter.NewClient(
        openrouter.WithAPIKey("your-api-key"),
    )

    messages := []openrouter.Message{
        {Role: "user", Content: "Hello, how are you?"},
    }

    response, err := client.ChatComplete(context.Background(),
        openrouter.WithModel("openai/gpt-4o"),
        openrouter.WithMessages(messages),
    )

    if err != nil {
        panic(err)
    }

    fmt.Println(response.Choices[0].Message.Content)
}

API Design

Client Initialization
// Basic initialization
client := openrouter.NewClient("api-key")

// With options
client := openrouter.NewClient("api-key",
    openrouter.WithBaseURL("https://custom.openrouter.ai"),
    openrouter.WithHTTPClient(customHTTPClient),
    openrouter.WithTimeout(60 * time.Second),
    openrouter.WithRetry(3, time.Second),
    openrouter.WithAppName("MyApp"),
    openrouter.WithReferer("https://myapp.com"),
)
Chat Completions
// Non-streaming
response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("anthropic/claude-3-opus"),
    openrouter.WithTemperature(0.7),
    openrouter.WithMaxTokens(1000),
)

// Streaming
stream, err := client.ChatCompleteStream(ctx, messages,
    openrouter.WithModel("anthropic/claude-3-opus"),
)

for event := range stream.Events() {
    fmt.Print(event.Choices[0].Delta.Content)
}

if err := stream.Err(); err != nil {
    // Handle streaming error
}

// With Zero Data Retention (ZDR)
response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("anthropic/claude-3-opus"),
    openrouter.WithZDR(true), // Enforce ZDR for this request
)
Legacy Completions
// Non-streaming
response, err := client.Complete(ctx, "Once upon a time",
    openrouter.WithModel("openai/gpt-3.5-turbo-instruct"),
    openrouter.WithMaxTokens(100),
)

// Streaming
stream, err := client.CompleteStream(ctx, "Once upon a time",
    openrouter.WithModel("openai/gpt-3.5-turbo-instruct"),
)

// With Zero Data Retention (ZDR)
response, err := client.Complete(ctx, "Once upon a time",
    openrouter.WithModel("openai/gpt-3.5-turbo-instruct"),
    openrouter.WithCompletionZDR(true), // Enforce ZDR for this request
)
Listing Available Models
// List all available models
response, err := client.ListModels(ctx, nil)
if err != nil {
    log.Fatal(err)
}

for _, model := range response.Data {
    fmt.Printf("%s - %s\n", model.ID, model.Name)
    fmt.Printf("  Context: %.0f tokens\n", *model.ContextLength)
    fmt.Printf("  Pricing: $%s/M prompt, $%s/M completion\n",
        model.Pricing.Prompt, model.Pricing.Completion)
}

// Filter models by category (e.g., "programming")
response, err := client.ListModels(ctx, &openrouter.ListModelsOptions{
    Category: "programming",
})
Listing Model Endpoints

Get detailed information about the specific endpoints (providers) available for a model:

// List all endpoints for a specific model
response, err := client.ListModelEndpoints(ctx, "openai", "gpt-4")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Model: %s\n", response.Data.Name)
fmt.Printf("Total endpoints: %d\n\n", len(response.Data.Endpoints))

// Examine each provider endpoint
for _, endpoint := range response.Data.Endpoints {
    fmt.Printf("Provider: %s\n", endpoint.ProviderName)
    fmt.Printf("  Status: %s\n", endpoint.Status)
    fmt.Printf("  Context Length: %.0f tokens\n", endpoint.ContextLength)
    fmt.Printf("  Pricing - Prompt: $%s/M, Completion: $%s/M\n",
        endpoint.Pricing.Prompt, endpoint.Pricing.Completion)

    if endpoint.UptimeLast30m != nil {
        fmt.Printf("  Uptime (30m): %.2f%%\n", *endpoint.UptimeLast30m*100)
    }

    if endpoint.Quantization != nil {
        fmt.Printf("  Quantization: %s\n", *endpoint.Quantization)
    }

    fmt.Printf("  Supported Parameters: %v\n\n", endpoint.SupportedParameters)
}

This endpoint is useful for:

  • Comparing pricing across different providers for the same model
  • Checking provider availability and uptime
  • Finding endpoints with specific quantization levels
  • Discovering which parameters are supported by each provider
Listing Available Providers

Get information about all providers available through OpenRouter:

// List all providers
response, err := client.ListProviders(ctx)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Total providers: %d\n\n", len(response.Data))

// Display provider information
for _, provider := range response.Data {
    fmt.Printf("Provider: %s (%s)\n", provider.Name, provider.Slug)

    if provider.PrivacyPolicyURL != nil {
        fmt.Printf("  Privacy Policy: %s\n", *provider.PrivacyPolicyURL)
    }

    if provider.TermsOfServiceURL != nil {
        fmt.Printf("  Terms of Service: %s\n", *provider.TermsOfServiceURL)
    }

    if provider.StatusPageURL != nil {
        fmt.Printf("  Status Page: %s\n", *provider.StatusPageURL)
    }
}

This endpoint is useful for:

  • Reviewing provider policies and terms
  • Finding provider status pages for uptime monitoring
  • Understanding which providers are available
  • Checking provider compliance information
Getting Credit Balance

Retrieve your current credit balance and usage for the authenticated user:

// Get credit balance
response, err := client.GetCredits(ctx)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Total Credits: $%.2f\n", response.Data.TotalCredits)
fmt.Printf("Total Usage: $%.2f\n", response.Data.TotalUsage)

// Calculate remaining balance
remaining := response.Data.TotalCredits - response.Data.TotalUsage
fmt.Printf("Remaining: $%.2f\n", remaining)

// Check usage percentage
if response.Data.TotalCredits > 0 {
    usagePercent := (response.Data.TotalUsage / response.Data.TotalCredits) * 100
    fmt.Printf("Usage: %.2f%%\n", usagePercent)
}

This endpoint is useful for:

  • Monitoring credit consumption in real-time
  • Setting up alerts for low balance
  • Tracking API usage costs
  • Budget management and forecasting
Getting Activity Data

Retrieve daily user activity data grouped by model endpoint for the last 30 (completed) UTC days:

// Get all activity data
response, err := client.GetActivity(ctx, nil)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Total activity records: %d\n\n", len(response.Data))

// Calculate summary statistics
totalUsage := 0.0
totalRequests := 0.0

for _, data := range response.Data {
    totalUsage += data.Usage
    totalRequests += data.Requests
}

fmt.Printf("Total usage: $%.4f\n", totalUsage)
fmt.Printf("Total requests: %.0f\n", totalRequests)

// Filter by specific date
yesterday := time.Now().AddDate(0, 0, -1).Format("2006-01-02")
dateActivity, err := client.GetActivity(ctx, &openrouter.ActivityOptions{
    Date: yesterday,
})
if err != nil {
    log.Fatal(err)
}

// Display activity for specific date
for _, data := range dateActivity.Data {
    fmt.Printf("Date: %s\n", data.Date)
    fmt.Printf("Model: %s\n", data.Model)
    fmt.Printf("Provider: %s\n", data.ProviderName)
    fmt.Printf("Requests: %.0f\n", data.Requests)
    fmt.Printf("Usage: $%.4f\n", data.Usage)
    fmt.Printf("Tokens: %.0f prompt, %.0f completion, %.0f reasoning\n",
        data.PromptTokens, data.CompletionTokens, data.ReasoningTokens)
}

Important: This endpoint requires a provisioning key (not a regular inference API key). Create one at: https://openrouter.ai/settings/provisioning-keys

This endpoint is useful for:

  • Daily usage analytics and cost tracking
  • Model performance comparison
  • Provider usage distribution analysis
  • Historical cost analysis and forecasting
  • BYOK (Bring Your Own Key) usage tracking
Getting API Key Information

Retrieve information about your current API key including usage, limits, and rate limits:

// Get API key information
response, err := client.GetKey(ctx)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("API Key Label: %s\n", response.Data.Label)

// Display limit information
if response.Data.Limit != nil {
    fmt.Printf("Credit Limit: $%.2f\n", *response.Data.Limit)
} else {
    fmt.Printf("Credit Limit: Unlimited\n")
}

fmt.Printf("Usage: $%.4f\n", response.Data.Usage)

// Display remaining balance
if response.Data.LimitRemaining != nil {
    fmt.Printf("Remaining: $%.4f\n", *response.Data.LimitRemaining)

    // Calculate usage percentage
    if response.Data.Limit != nil && *response.Data.Limit > 0 {
        usagePercent := (response.Data.Usage / *response.Data.Limit) * 100
        fmt.Printf("Usage: %.2f%%\n", usagePercent)
    }
}

// Display key type
fmt.Printf("Free Tier: %v\n", response.Data.IsFreeTier)
fmt.Printf("Provisioning Key: %v\n", response.Data.IsProvisioningKey)

// Display rate limit if available
if response.Data.RateLimit != nil {
    fmt.Printf("Rate Limit: %.0f requests per %s\n",
        response.Data.RateLimit.Requests,
        response.Data.RateLimit.Interval)
}

This endpoint is useful for:

  • Monitoring API key usage and limits
  • Checking remaining credits
  • Understanding rate limit constraints
  • Identifying key type (free tier vs paid, inference vs provisioning)
  • Building usage alerts and notifications
Listing All API Keys

Retrieve a list of all API keys associated with your account. Requires a Provisioning API key (not a regular inference API key):

// List all API keys
response, err := client.ListKeys(ctx, nil)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Total API keys: %d\n\n", len(response.Data))

// Display key information
for i, key := range response.Data {
    status := "Active"
    if key.Disabled {
        status = "Disabled"
    }

    fmt.Printf("%d. %s [%s]\n", i+1, key.Label, status)
    fmt.Printf("   Name: %s\n", key.Name)
    fmt.Printf("   Limit: $%.2f\n", key.Limit)
    fmt.Printf("   Created: %s\n", key.CreatedAt)
    fmt.Printf("   Updated: %s\n", key.UpdatedAt)
}

// Example with pagination and filtering
offset := 10
includeDisabled := true
filteredKeys, err := client.ListKeys(ctx, &openrouter.ListKeysOptions{
    Offset:          &offset,
    IncludeDisabled: &includeDisabled,
})

Important: This endpoint requires a provisioning key (not a regular inference API key). Create one at: https://openrouter.ai/settings/provisioning-keys

This endpoint is useful for:

  • Managing multiple API keys programmatically
  • Auditing key usage and creation dates
  • Identifying and managing disabled keys
  • Implementing key rotation strategies
  • Building API key management dashboards
Getting API Key by Hash

Retrieve details about a specific API key by its hash. Requires a Provisioning API key:

// Get key details by hash (hash obtained from ListKeys or key creation)
hash := "abc123hash"
keyDetails, err := client.GetKeyByHash(ctx, hash)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Label: %s\n", keyDetails.Data.Label)
fmt.Printf("Name: %s\n", keyDetails.Data.Name)
fmt.Printf("Limit: $%.2f\n", keyDetails.Data.Limit)
fmt.Printf("Disabled: %v\n", keyDetails.Data.Disabled)
fmt.Printf("Created: %s\n", keyDetails.Data.CreatedAt)
fmt.Printf("Updated: %s\n", keyDetails.Data.UpdatedAt)

// Example: Get hash from list and retrieve details
keys, err := client.ListKeys(ctx, nil)
if err != nil {
    log.Fatal(err)
}

if len(keys.Data) > 0 {
    firstHash := keys.Data[0].Hash
    details, err := client.GetKeyByHash(ctx, firstHash)
    // ...
}

Important: This endpoint requires a provisioning key (not a regular inference API key). Create one at: https://openrouter.ai/settings/provisioning-keys

This endpoint is useful for:

  • Inspecting individual API key details
  • Verifying key status and configuration
  • Monitoring specific key usage patterns
  • Building key detail views in dashboards
  • Auditing key configuration changes
Creating API Keys

Create new API keys programmatically with custom limits and settings. Requires a Provisioning API key:

// Create an API key with a credit limit
limit := 100.0
keyResp, err := client.CreateKey(ctx, &openrouter.CreateKeyRequest{
    Name:  "Production API Key",
    Limit: &limit,
})
if err != nil {
    log.Fatal(err)
}

// ⚠️ IMPORTANT: Save this value immediately!
// This is the ONLY time the full API key will be returned
fmt.Printf("New API Key: %s\n", keyResp.Key)
fmt.Printf("Label: %s\n", keyResp.Data.Label)
fmt.Printf("Limit: $%.2f\n", keyResp.Data.Limit)

// Create a key with BYOK limit inclusion
includeBYOK := true
keyResp2, err := client.CreateKey(ctx, &openrouter.CreateKeyRequest{
    Name:               "BYOK Key",
    Limit:              &limit,
    IncludeBYOKInLimit: &includeBYOK,
})

// Create a key without a specific limit (uses account limit)
keyResp3, err := client.CreateKey(ctx, &openrouter.CreateKeyRequest{
    Name: "Unlimited Key",
})

Critical Security Note: The Key field in the response contains the actual API key value. This is the ONLY time this value will ever be returned. Store it securely immediately!

Important: This endpoint requires a provisioning key (not a regular inference API key). Create one at: https://openrouter.ai/settings/provisioning-keys

This endpoint is useful for:

  • Automated API key provisioning
  • Implementing key rotation workflows
  • Creating keys with custom credit limits
  • Setting up BYOK (Bring Your Own Key) configurations
  • Building self-service key management systems
Deleting API Keys

Delete an API key by its hash. Requires a Provisioning API key:

// Delete a key by hash (hash obtained from ListKeys or key creation)
hash := "abc123hash"
result, err := client.DeleteKey(ctx, hash)
if err != nil {
    log.Fatal(err)
}

if result.Data.Success {
    fmt.Println("API key successfully deleted")
}

// Example: Delete a key created in the same session
keyResp, err := client.CreateKey(ctx, &openrouter.CreateKeyRequest{
    Name: "Temporary Key",
})
if err != nil {
    log.Fatal(err)
}

// Later... delete it
deleteResult, err := client.DeleteKey(ctx, keyResp.Data.Hash)
if err != nil {
    log.Fatal(err)
}

⚠️ WARNING: This operation is irreversible! Once deleted, the API key cannot be recovered and any applications using it will immediately lose access.

Important: This endpoint requires a provisioning key (not a regular inference API key). Create one at: https://openrouter.ai/settings/provisioning-keys

This endpoint is useful for:

  • Automated key rotation and cleanup
  • Removing compromised or unused keys
  • Implementing temporary key workflows
  • Building key lifecycle management systems
  • Programmatic key revocation
Updating API Keys

Update an existing API key's properties (name, limit, disabled status) by its hash. Requires a Provisioning API key:

// Update just the key name
hash := "abc123hash"
newName := "Updated Production Key"
result, err := client.UpdateKey(ctx, hash, &openrouter.UpdateKeyRequest{
    Name: &newName,
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Updated key: %s\n", result.Data.Label)

// Disable a key
disabled := true
result, err := client.UpdateKey(ctx, hash, &openrouter.UpdateKeyRequest{
    Disabled: &disabled,
})

// Update credit limit
newLimit := 200.0
result, err := client.UpdateKey(ctx, hash, &openrouter.UpdateKeyRequest{
    Limit: &newLimit,
})

// Update multiple fields at once
result, err := client.UpdateKey(ctx, hash, &openrouter.UpdateKeyRequest{
    Name:               &newName,
    Limit:              &newLimit,
    IncludeBYOKInLimit: &[]bool{true}[0],
})

Important: This endpoint requires a provisioning key (not a regular inference API key). Create one at: https://openrouter.ai/settings/provisioning-keys

All fields in UpdateKeyRequest are optional - only include the fields you want to update:

  • Name: Display name for the API key
  • Disabled: Set to true to disable the key (prevents usage)
  • Limit: Credit limit in dollars
  • IncludeBYOKInLimit: Whether BYOK (Bring Your Own Key) usage counts toward the limit

This endpoint is useful for:

  • Rotating key names for better organization
  • Adjusting credit limits based on usage patterns
  • Temporarily disabling keys without deletion
  • Managing BYOK limit policies
  • Implementing dynamic key management workflows

Code Quality

The library is built with a focus on code quality and maintainability:

  • Named Constants: Magic numbers have been extracted as named constants for better readability and maintainability

    • defaultJitterFactor (0.25): Default jitter factor for retry backoff (±25%)
    • maxReconnectBackoff (10s): Maximum backoff duration for stream reconnection attempts
    • defaultMaxDelay (30s): Default maximum delay for retry backoff
    • defaultMultiplier (2.0): Default multiplier for exponential backoff

  • Generic Options Pattern: Uses Go 1.18+ generics to reduce code duplication in functional options

    • Type-safe option setters with RequestConfig interface constraint
    • Shared implementation for common fields across ChatCompletion and Completion requests
    • Eliminates ~400 lines of duplicate code while maintaining type safety

  • Comprehensive Testing: Extensive unit test coverage with table-driven tests

  • Race Detection: All code is tested for race conditions

  • Thread Safety: Client is safe for concurrent use across goroutines

  • Error Handling: Rich error types with detailed context

Package Structure

openrouter-go/
├── client.go            # Main client implementation
├── completions.go       # Completion endpoint methods
├── chat.go              # Chat completion endpoint methods
├── models_endpoint.go   # Models listing endpoint methods
├── model_endpoints.go   # Model endpoints inspection methods
├── providers_endpoint.go # Providers listing endpoint methods
├── credits_endpoint.go  # Credits balance endpoint methods
├── activity_endpoint.go # Activity analytics endpoint methods
├── key_endpoint.go      # API key information endpoint methods
├── models.go            # Request/response type definitions
├── options.go           # Functional options for configuration
├── stream.go            # SSE streaming with generic Stream[T] implementation
├── errors.go            # Custom error types
├── retry.go             # Retry and backoff logic with named constants
├── examples/
│   ├── basic/             # Basic usage examples
│   ├── streaming/         # Streaming examples
│   ├── structured-output/ # Structured outputs with JSON schema
│   ├── tool-calling/      # Tool/function calling examples
│   ├── web_search/        # Web search plugin examples
│   ├── list-models/       # Model listing examples
│   ├── model-endpoints/   # Model endpoints inspection examples
│   ├── list-providers/    # Provider listing examples
│   ├── get-credits/       # Credit balance tracking examples
│   ├── activity/          # Activity analytics examples
│   ├── key/               # API key information examples
│   ├── list-keys/         # API key listing examples
│   ├── create-key/        # API key creation examples
│   └── advanced/          # Advanced configuration examples
└── internal/
    └── sse/               # Internal SSE parser implementation

App Attribution

Get your app featured in OpenRouter rankings and analytics by including attribution headers:

client := openrouter.NewClient(
    openrouter.WithAPIKey("your-api-key"),
    // Your app's URL (primary identifier)
    openrouter.WithReferer("https://myapp.com"),
    // Your app's display name
    openrouter.WithAppName("My AI Assistant"),
)
Benefits

When you use app attribution, your app will:

  • Appear in OpenRouter's public rankings
  • Be featured on individual model pages in the "Apps" tab
  • Get detailed analytics at openrouter.ai/apps?url=<your-app-url>
  • Gain visibility in the OpenRouter developer community
Localhost Development

For localhost development, always include a title:

client := openrouter.NewClient(
    openrouter.WithAPIKey("your-api-key"),
    openrouter.WithReferer("http://localhost:3000"),
    openrouter.WithAppName("Development App"), // Required for localhost
)

See the app attribution example for more details.

Requirements

  • Go 1.25.1
  • No external dependencies

Status

✅ Production Ready - All 5 phases complete! The library is now ready for production use with:

  • ✅ Full foundation with all types and error handling
  • ✅ Robust HTTP communication with retry logic
  • ✅ Complete API implementation for chat and completions
  • ✅ Zero-dependency SSE streaming with reconnection support
  • ✅ Comprehensive test coverage and documentation
  • ✅ Production-ready examples for all use cases

Testing

Unit Tests

Run the unit test suite:

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests with race detection
go test -race ./...

# Run specific test
go test -run TestChatComplete
E2E Tests

The project includes a comprehensive end-to-end test suite in cmd/openrouter-test/ that tests against the live OpenRouter API. The test suite is organized into logical modules:

Test Structure:

cmd/openrouter-test/
├── main.go              # Entry point and CLI
└── tests/
    ├── helpers.go       # Shared utilities
    ├── chat.go          # Chat, streaming, completion tests
    ├── routing.go       # Provider routing, ZDR, model suffixes
    ├── structured.go    # Structured output tests
    ├── tools.go         # Tool/function calling tests
    ├── transforms.go    # Message transforms tests
    ├── search.go        # Web search tests
    ├── models.go        # Models, endpoints, providers tests
    ├── account.go       # Credits, activity tests
    └── apikeys.go       # API key management tests

Running E2E Tests:

# Set your API key
export OPENROUTER_API_KEY="your-api-key"

# Run all tests (excluding web search)
go run cmd/openrouter-test/main.go -test all

# Run specific test categories
go run cmd/openrouter-test/main.go -test chat
go run cmd/openrouter-test/main.go -test streaming
go run cmd/openrouter-test/main.go -test tools
go run cmd/openrouter-test/main.go -test websearch  # Run separately on demand

# Run with custom model
go run cmd/openrouter-test/main.go -test all -model anthropic/claude-3-haiku

# Run with verbose output
go run cmd/openrouter-test/main.go -test chat -v

# Available tests:
# all, chat, stream, completion, error, provider, zdr, suffix,
# price, structured, tools, transforms, websearch, models,
# endpoints, providers, credits, activity, key, listkeys,
# createkey, updatekey, deletekey
Message Transforms

The library supports message transforms to automatically handle prompts that exceed a model's context window. This feature uses "middle-out" compression to remove content from the middle of long prompts where models typically pay less attention.

Basic Transform Usage
// Enable middle-out compression for chat completions
response, err := client.ChatComplete(ctx,
    openrouter.WithModel("meta-llama/llama-3.1-8b-instruct"),
    openrouter.WithMessages(messages),
    openrouter.WithTransforms("middle-out"), // Auto-compress if exceeds context
)

// Enable for legacy completions
response, err := client.Complete(ctx, prompt,
    openrouter.WithModel("openai/gpt-3.5-turbo-instruct"),
    openrouter.WithCompletionTransforms("middle-out"),
)
How It Works

When middle-out transform is enabled:

  1. OpenRouter finds models with at least half of your required tokens (input + completion)
  2. If your prompt exceeds the model's context, content is removed from the middle
  3. For models with message count limits (e.g. Anthropic's Claude), messages are compressed to stay within limits
Default Behavior

All OpenRouter endpoints with 8K (8,192 tokens) or less context length automatically use middle-out by default. To disable:

// Explicitly disable transforms for smaller models
response, err := client.ChatComplete(ctx,
    openrouter.WithModel("some-8k-model"),
    openrouter.WithMessages(messages),
    openrouter.WithTransforms(), // Empty array disables transforms
)
When to Use

Message transforms are useful when:

  • Perfect recall is not required
  • You want automatic fallback for long conversations
  • Working with models that have smaller context windows
  • Handling variable-length user inputs that might exceed limits
Important Notes
  • Middle content is compressed because LLMs pay less attention to the middle of sequences
  • The transform handles both token limits and message count limits
  • Without transforms, requests exceeding limits will fail with an error
  • Consider using models with larger context windows if perfect recall is critical
Provider Routing

The library supports comprehensive provider routing options to control how your requests are handled across different providers.

Basic Provider Routing
// Specify provider order
response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("meta-llama/llama-3.1-70b-instruct"),
    openrouter.WithProviderOrder("together", "openai", "anthropic"),
)

// Disable fallbacks (only use specified providers)
response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("mistralai/mixtral-8x7b-instruct"),
    openrouter.WithProviderOrder("together"),
    openrouter.WithAllowFallbacks(false),
)

// Sort providers by throughput or price
response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("meta-llama/llama-3.1-70b-instruct"),
    openrouter.WithProviderSort("throughput"), // or "price", "latency"
)
Model Suffixes
// Use :nitro suffix for throughput optimization
response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("meta-llama/llama-3.1-70b-instruct:nitro"),
)

// Use :floor suffix for lowest price
response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("meta-llama/llama-3.1-70b-instruct:floor"),
)
Provider Filtering
// Only use specific providers
response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("openai/gpt-4o"),
    openrouter.WithOnlyProviders("azure", "openai"),
)

// Ignore specific providers
response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("meta-llama/llama-3.3-70b-instruct"),
    openrouter.WithIgnoreProviders("deepinfra"),
)

// Filter by quantization levels
response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("meta-llama/llama-3.1-8b-instruct"),
    openrouter.WithQuantizations("fp8", "fp16"),
)
Price Constraints
// Set maximum pricing constraints
maxPrice := openrouter.MaxPrice{
    Prompt: 1.0,     // Max $1 per million prompt tokens
    Completion: 2.0, // Max $2 per million completion tokens
}
response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("meta-llama/llama-3.1-70b-instruct"),
    openrouter.WithMaxPrice(maxPrice),
    openrouter.WithProviderSort("throughput"), // Use fastest provider under price limit
)
Data Policies
// Require providers that don't collect data
response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("anthropic/claude-3-opus"),
    openrouter.WithDataCollection("deny"), // or "allow"
)

// Require providers that support all parameters
response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("openai/gpt-4o"),
    openrouter.WithRequireParameters(true),
    openrouter.WithResponseFormat(openrouter.ResponseFormat{Type: "json_object"}),
)
Zero Data Retention (ZDR)

The library supports per-request Zero Data Retention enforcement. When enabled, requests will only be routed to endpoints with Zero Data Retention policies.

// For chat completions
response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("anthropic/claude-3-opus"),
    openrouter.WithZDR(true), // Enforce ZDR for this specific request
)

// For legacy completions
response, err := client.Complete(ctx, prompt,
    openrouter.WithModel("openai/gpt-3.5-turbo-instruct"),
    openrouter.WithCompletionZDR(true), // Enforce ZDR for this specific request
)

// With custom provider configuration
provider := openrouter.Provider{
    ZDR: &[]bool{true}[0], // Enable ZDR
}
response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("anthropic/claude-3-opus"),
    openrouter.WithProvider(provider),
)

Note: The request-level zdr parameter operates as an "OR" with your account-wide ZDR setting. If either is enabled, ZDR enforcement will be applied.

Image Inputs (Multimodal)

The library provides comprehensive support for sending images to vision models through the OpenRouter API. You can send images via URLs or base64-encoded data.

Single Image with URL
// Send a single image with text
messages := []openrouter.Message{
    openrouter.CreateUserMessageWithImage(
        "What's in this image?",
        "https://example.com/image.jpg",
    ),
}

response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("google/gemini-2.0-flash-thinking-exp:free"),
)
Multiple Images
// Send multiple images in a single request
messages := []openrouter.Message{
    openrouter.CreateUserMessageWithImages(
        "Compare these images. What are the similarities?",
        "https://example.com/image1.jpg",
        "https://example.com/image2.jpg",
        "https://example.com/image3.jpg",
    ),
}

response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("google/gemini-2.0-flash-thinking-exp:free"),
)
Image with Detail Level

Some models support detail level parameters for controlling image analysis quality:

// Request high-detail analysis (more expensive, more detailed)
messages := []openrouter.Message{
    openrouter.CreateUserMessageWithImageDetail(
        "Describe this image in detail.",
        "https://example.com/image.jpg",
        "high", // Options: "low", "high", or "auto"
    ),
}

response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("google/gemini-2.0-flash-thinking-exp:free"),
)

Detail level options:

  • "low" - Faster and cheaper, suitable for general understanding
  • "high" - More detailed analysis at higher cost
  • "auto" - Let the model decide based on image size (default)
Base64-Encoded Images

For local files or private images:

// Automatically encode and send a local image
message, err := openrouter.CreateUserMessageWithBase64Image(
    "What's in this image?",
    "path/to/image.jpg",
)
if err != nil {
    log.Fatal(err)
}

messages := []openrouter.Message{message}

response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("google/gemini-2.0-flash-thinking-exp:free"),
)

Multiple local images:

message, err := openrouter.CreateUserMessageWithBase64Images(
    "Compare these images",
    "path/to/image1.jpg",
    "path/to/image2.png",
)

Manual base64 encoding:

// Encode image file to base64 data URL
dataURL, err := openrouter.EncodeImageToBase64("path/to/image.jpg")
if err != nil {
    log.Fatal(err)
}

// Or encode bytes directly
imageBytes := []byte{...}
dataURL := openrouter.EncodeImageBytesToBase64(imageBytes, "image/jpeg")
Content Builder for Complex Messages

For messages with interleaved text and images:

content := openrouter.NewContentBuilder().
    AddText("Here's the first image:").
    AddImage("https://example.com/image1.jpg").
    AddText("And here's the second with high detail:").
    AddImageWithDetail("https://example.com/image2.jpg", "high").
    AddText("What are the differences?")

messages := []openrouter.Message{
    content.BuildMessage("user"),
}

response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("google/gemini-2.0-flash-thinking-exp:free"),
)
Supported Image Formats
  • PNG (image/png)
  • JPEG (image/jpeg)
  • WebP (image/webp)
  • GIF (image/gif)
Model Support

Most modern vision models support image inputs, including:

  • Google Gemini models (gemini-2.0-flash-thinking-exp, etc.)
  • OpenAI GPT-4 Vision models
  • Anthropic Claude 3 models
  • And many others

Check the OpenRouter models page for the latest list of vision-capable models.

Best Practices
  • Use URLs when possible - they're more efficient than base64 encoding
  • Image URLs must be publicly accessible
  • The number of images per request varies by model and provider
  • Some providers may have size limits on images
  • Pricing may vary based on image size and detail level
  • For production use, consider the OpenRouter documentation's recommendations about image placement in messages

See the image-inputs example for more comprehensive examples.

PDF Inputs (File Support)

The library provides comprehensive support for sending PDF files to models through the OpenRouter API. PDF files can be sent via URLs or base64-encoded data. This feature works with any model on OpenRouter, with automatic fallback to PDF parsing when models don't have native file support.

Basic PDF from URL
// Send a PDF via URL
messages := []openrouter.Message{
    openrouter.CreateUserMessageWithPDF(
        "What are the main points in this document?",
        "https://bitcoin.org/bitcoin.pdf",
        "bitcoin.pdf",
    ),
}

response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("anthropic/claude-sonnet-4"),
)
Local PDF Files
// Automatically encode and send a local PDF
message, err := openrouter.CreateUserMessageWithBase64PDF(
    "Summarize this document",
    "path/to/document.pdf",
    "document.pdf",
)
if err != nil {
    log.Fatal(err)
}

response, err := client.ChatComplete(ctx, []openrouter.Message{message},
    openrouter.WithModel("google/gemma-3-27b-it"),
)
PDF Parsing Engines

OpenRouter provides three PDF processing engines with different cost/quality tradeoffs:

message := openrouter.CreateUserMessageWithPDF(
    "Extract key concepts from this document",
    "https://example.com/document.pdf",
    "document.pdf",
)

// Configure the PDF parsing engine
plugin := openrouter.CreateFileParserPlugin("pdf-text")

response, err := client.ChatComplete(ctx, []openrouter.Message{message},
    openrouter.WithModel("google/gemma-3-27b-it"),
    openrouter.WithPlugins(plugin),
)

Available engines:

  • "pdf-text" - Free, best for well-structured PDFs with clear text content
  • "mistral-ocr" - $0.0004 per 1K pages, best for scanned documents with images/OCR needs
  • "native" - Uses model's native file support (charged as input tokens)
  • "" (empty) - Auto-selects native support first, then defaults to pdf-text
Reusing File Annotations

File annotations allow you to avoid re-parsing the same PDF in follow-up requests, saving processing time and costs:

// First request with PDF
firstMessage := openrouter.CreateUserMessageWithPDF(
    "What are the main concepts in this paper?",
    "https://example.com/document.pdf",
    "document.pdf",
)

resp1, err := client.ChatComplete(ctx, []openrouter.Message{firstMessage},
    openrouter.WithModel("google/gemma-3-27b-it"),
)

// Follow-up request - include the assistant's response with annotations
followUpMessages := []openrouter.Message{
    firstMessage,
    resp1.Choices[0].Message, // Contains file annotations
    openrouter.CreateUserMessage("Can you elaborate on the first point?"),
}

resp2, err := client.ChatComplete(ctx, followUpMessages,
    openrouter.WithModel("google/gemma-3-27b-it"),
)
// PDF is NOT re-parsed - saves processing time and costs!
Multiple Files

You can send multiple files (PDFs, images, etc.) in a single request:

files := []openrouter.File{
    {
        Filename: "document1.pdf",
        FileData: "https://example.com/doc1.pdf",
    },
    {
        Filename: "document2.pdf",
        FileData: "https://example.com/doc2.pdf",
    },
    {
        Filename: "chart.png",
        FileData: "https://example.com/chart.png",
    },
}

message := openrouter.CreateUserMessageWithFiles(
    "Compare these documents and analyze the chart",
    files,
)

response, err := client.ChatComplete(ctx, []openrouter.Message{message},
    openrouter.WithModel("anthropic/claude-sonnet-4"),
)
Content Builder with PDFs

For complex messages with PDFs, images, and text:

content := openrouter.NewContentBuilder().
    AddText("Analyze this document:").
    AddPDF("https://example.com/document.pdf", "document.pdf").
    AddText("And compare with this image:").
    AddImage("https://example.com/chart.png").
    Build()

message := openrouter.Message{
    Role:    "user",
    Content: content,
}

response, err := client.ChatComplete(ctx, []openrouter.Message{message},
    openrouter.WithModel("anthropic/claude-sonnet-4"),
)
Manual Base64 Encoding
// Encode PDF file to base64 data URL
dataURL, err := openrouter.EncodePDFToBase64("path/to/document.pdf")
if err != nil {
    log.Fatal(err)
}

// Or encode bytes directly
pdfBytes := []byte{...}
dataURL := openrouter.EncodePDFBytesToBase64(pdfBytes)
Best Practices
  • Use URLs when possible - More efficient than base64 encoding
  • Use pdf-text for digital PDFs - It's free and works well for most documents
  • Reuse file annotations - Include the assistant's response with annotations in follow-up requests
  • Use mistral-ocr only for scanned documents - More expensive but necessary for image-based PDFs
  • Check model support - Some models have native file support which may be more cost-effective
Supported File Types

While this section focuses on PDFs, the file input API supports:

  • PDFs (application/pdf)
  • Images (image/png, image/jpeg, etc.)
  • And potentially other file types as OpenRouter expands support

See the pdf-inputs example for more comprehensive examples.

Structured Outputs

The library supports structured outputs for compatible models, ensuring responses follow a specific JSON Schema format. This feature is useful when you need consistent, well-formatted responses that can be reliably parsed by your application.

Basic Structured Output
// Define a JSON schema for the expected response
weatherSchema := map[string]interface{}{
    "type": "object",
    "properties": map[string]interface{}{
        "location": map[string]interface{}{
            "type": "string",
            "description": "City or location name",
        },
        "temperature": map[string]interface{}{
            "type": "number",
            "description": "Temperature in Celsius",
        },
        "conditions": map[string]interface{}{
            "type": "string",
            "description": "Weather conditions",
        },
    },
    "required": []string{"location", "temperature", "conditions"},
    "additionalProperties": false,
}

// Use structured output with chat completion
response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("openai/gpt-4o"),
    openrouter.WithJSONSchema("weather", true, weatherSchema),
    openrouter.WithRequireParameters(true), // Ensure model supports structured outputs
)

// The response will be valid JSON matching your schema
var weatherData map[string]interface{}
json.Unmarshal([]byte(response.Choices[0].Message.Content.(string)), &weatherData)
Simplified JSON Mode
// For simpler cases, use JSON mode without a strict schema
response, err := client.ChatComplete(ctx, messages,
    openrouter.WithModel("openai/gpt-4o"),
    openrouter.WithJSONMode(), // Returns JSON without enforcing a schema
)
Streaming with Structured Output
// Structured outputs work with streaming too
stream, err := client.ChatCompleteStream(ctx, messages,
    openrouter.WithModel("openai/gpt-4o"),
    openrouter.WithJSONSchema("response", true, schema),
)

var fullContent string
for event := range stream.Events() {
    if len(event.Choices) > 0 && event.Choices[0].Delta != nil {
        if content, ok := event.Choices[0].Delta.Content.(string); ok {
            fullContent += content
        }
    }
}

// Parse the complete JSON response
var result map[string]interface{}
json.Unmarshal([]byte(fullContent), &result)
Model Support

Not all models support structured outputs. To ensure compatibility:

  1. Check the models page for support
  2. Use WithRequireParameters(true) to route only to compatible providers
  3. Models known to support structured outputs include:
    • OpenAI models (GPT-4o and later)
    • Many Fireworks-provided models
Best Practices
  • Always set strict: true in your JSON schema for exact compliance
  • Include clear descriptions in schema properties to guide the model
  • Use WithRequireParameters(true) to ensure routing to compatible providers
  • Test your schemas with the specific models you plan to use
  • Handle parsing errors gracefully as a fallback
Tool/Function Calling

The library provides full support for tool/function calling, allowing models to use external tools and functions during generation. This feature enables building powerful AI agents and assistants.

Basic Tool Calling
// Define a tool
tools := []openrouter.Tool{
    {
        Type: "function",
        Function: openrouter.Function{
            Name:        "get_weather",
            Description: "Get the current weather for a location",
            Parameters: map[string]interface{}{
                "type": "object",
                "properties": map[string]interface{}{
                    "location": map[string]interface{}{
                        "type":        "string",
                        "description": "City name or zip code",
                    },
                    "unit": map[string]interface{}{
                        "type":        "string",
                        "enum":        []string{"celsius", "fahrenheit"},
                        "description": "Temperature unit",
                    },
                },
                "required": []string{"location"},
            },
        },
    },
}

// Make a request with tools
messages := []openrouter.Message{
    {Role: "user", Content: "What's the weather in San Francisco?"},
}

response, err := client.ChatComplete(ctx,
    openrouter.WithModel("openai/gpt-4o"),
    openrouter.WithMessages(messages),
    openrouter.WithTools(tools),
)

// Check for tool calls in the response
if len(response.Choices[0].Message.ToolCalls) > 0 {
    // Process tool calls
    for _, toolCall := range response.Choices[0].Message.ToolCalls {
        // Parse arguments
        var args map[string]interface{}
        json.Unmarshal([]byte(toolCall.Function.Arguments), &args)

        // Execute the tool (your implementation)
        result := executeWeatherTool(args)

        // Add tool result to messages
        messages = append(messages, response.Choices[0].Message)
        messages = append(messages, openrouter.Message{
            Role:       "tool",
            Content:    result,
            ToolCallID: toolCall.ID,
        })
    }

    // Get final response with tool results
    finalResponse, _ := client.ChatComplete(ctx,
        openrouter.WithModel("openai/gpt-4o"),
        openrouter.WithMessages(messages),
        openrouter.WithTools(tools),
    )
}
Tool Choice Control
// Let the model decide (default)
response, _ := client.ChatComplete(ctx,
    openrouter.WithMessages(messages),
    openrouter.WithTools(tools),
    openrouter.WithToolChoice("auto"),
)

// Disable tool usage
response, _ := client.ChatComplete(ctx,
    openrouter.WithMessages(messages),
    openrouter.WithTools(tools),
    openrouter.WithToolChoice("none"),
)

// Force specific tool usage
response, _ := client.ChatComplete(ctx,
    openrouter.WithMessages(messages),
    openrouter.WithTools(tools),
    openrouter.WithToolChoice(map[string]interface{}{
        "type": "function",
        "function": map[string]interface{}{
            "name": "get_weather",
        },
    }),
)
Parallel Tool Calls

Control whether multiple tools can be called simultaneously:

// Disable parallel tool calls (sequential only)
parallelCalls := false
response, _ := client.ChatComplete(ctx,
    openrouter.WithMessages(messages),
    openrouter.WithTools(tools),
    openrouter.WithParallelToolCalls(&parallelCalls),
)
Streaming with Tool Calls

Tool calls are fully supported in streaming mode:

stream, err := client.ChatCompleteStream(ctx,
    openrouter.WithModel("openai/gpt-4o"),
    openrouter.WithMessages(messages),
    openrouter.WithTools(tools),
)

var toolCalls []openrouter.ToolCall
for event := range stream.Events() {
    // Parse streaming data
    var data map[string]interface{}
    json.Unmarshal([]byte(event.Data), &data)

    if choices, ok := data["choices"].([]interface{}); ok && len(choices) > 0 {
        choice := choices[0].(map[string]interface{})

        // Check for tool calls in delta
        if delta, ok := choice["delta"].(map[string]interface{}); ok {
            if toolCallsDelta, ok := delta["tool_calls"].([]interface{}); ok {
                // Accumulate tool call information
                // See examples/tool-calling/streaming.go for complete implementation
            }
        }

        // Check finish reason
        if finishReason, ok := choice["finish_reason"].(string); ok {
            if finishReason == "tool_calls" {
                // Process accumulated tool calls
            }
        }
    }
}
Multi-Tool Workflows

Design tools that work well together:

tools := []openrouter.Tool{
    {
        Type: "function",
        Function: openrouter.Function{
            Name:        "search_products",
            Description: "Search for products in the catalog",
            // Parameters...
        },
    },
    {
        Type: "function",
        Function: openrouter.Function{
            Name:        "check_inventory",
            Description: "Check inventory for a product",
            // Parameters...
        },
    },
    {
        Type: "function",
        Function: openrouter.Function{
            Name:        "place_order",
            Description: "Place an order for a product",
            // Parameters...
        },
    },
}

// The model can chain these tools naturally:
// search → check inventory → place order
Model Support

Tool calling is supported by many models. You can find compatible models by filtering on openrouter.ai/models?supported_parameters=tools.

Popular models with tool support include:

  • OpenAI GPT-4o and GPT-4o-mini
  • Anthropic Claude 3.5 Sonnet
  • Google Gemini models
  • Many open-source models via various providers
Best Practices for Tool Calling
  • Clear Descriptions: Provide detailed descriptions for tools and parameters
  • Error Handling: Always validate tool arguments before execution
  • Tool Results: Return structured, informative results from tools
  • Context Preservation: Maintain full conversation history including tool calls
  • Streaming: Handle tool calls appropriately when streaming responses
  • Testing: Test tool interactions with different models as behavior may vary

The library supports OpenRouter's web search feature for augmenting model responses with real-time web data. Web search can be enabled using the :online model suffix or by configuring the web plugin.

Quick Start with :online Suffix
// Simple web search using :online suffix
response, err := client.ChatComplete(ctx,
    openrouter.WithModel("openai/gpt-4o:online"),
    openrouter.WithMessages([]openrouter.Message{
        {Role: "user", Content: "What are the latest AI developments this week?"},
    }),
)
Using the Web Plugin
// Configure web search with the plugin
webPlugin := openrouter.NewWebPlugin() // Uses defaults: auto engine, 5 results

response, err := client.ChatComplete(ctx,
    openrouter.WithModel("openai/gpt-4o"),
    openrouter.WithPlugins(webPlugin),
    openrouter.WithMessages(messages),
)

// Custom web plugin configuration
webPlugin := openrouter.NewWebPluginWithOptions(
    openrouter.WebSearchEngineExa,    // Force Exa search
    10,                                // Get 10 results
    "Recent web results for context:", // Custom prompt
)

response, err := client.ChatComplete(ctx,
    openrouter.WithModel("anthropic/claude-3.5-sonnet"),
    openrouter.WithPlugins(webPlugin),
    openrouter.WithMessages(messages),
)
Search Engine Options
  • Native: Uses the provider's built-in web search (OpenAI, Anthropic)
  • Exa: Uses Exa's neural search API (works with all models)
  • Auto (default): Automatically selects the best available engine
// Force native search for supported models
webPlugin := openrouter.Plugin{
    ID:     "web",
    Engine: string(openrouter.WebSearchEngineNative),
}

// Force Exa search for all models
webPlugin := openrouter.Plugin{
    ID:         "web",
    Engine:     string(openrouter.WebSearchEngineExa),
    MaxResults: 3,
}
Search Context Size (Native Only)

For models with native search support, control the search context depth:

response, err := client.ChatComplete(ctx,
    openrouter.WithModel("openai/gpt-4o"),
    openrouter.WithPlugins(openrouter.NewWebPlugin()),
    openrouter.WithWebSearchOptions(&openrouter.WebSearchOptions{
        SearchContextSize: string(openrouter.WebSearchContextHigh), // low, medium, high
    }),
    openrouter.WithMessages(messages),
)
Parsing Search Annotations

Web search results are included in the response annotations:

response, err := client.ChatComplete(ctx,
    openrouter.WithModel("openai/gpt-4o:online"),
    openrouter.WithMessages(messages),
)

// Extract URL citations from the response
citations := openrouter.ParseAnnotations(response.Choices[0].Message.Annotations)
for _, citation := range citations {
    fmt.Printf("Source: %s\n", citation.Title)
    fmt.Printf("URL: %s\n", citation.URL)
    fmt.Printf("Content: %s\n\n", citation.Content)
}
Pricing
  • Exa Search: $4 per 1000 results (default 5 results = $0.02 per request)
  • Native Search (OpenAI):
    • GPT-4o models: $30-50 per 1000 requests depending on context size
    • GPT-4o-mini models: $25-30 per 1000 requests
  • Native Search (Perplexity):
    • Sonar models: $5-12 per 1000 requests
    • SonarPro models: $6-14 per 1000 requests
Best Practices
  • Use :online suffix for simple cases with default settings
  • Configure the web plugin for fine-grained control over search behavior
  • Consider search costs when choosing between native and Exa engines
  • Parse annotations to display sources and improve transparency
  • Use higher search context for research tasks, lower for quick facts

Examples

The examples/ directory contains comprehensive examples:

  • basic/ - Simple usage examples for common tasks
  • streaming/ - Real-time streaming response handling
  • list-models/ - List and discover available models with filtering
  • model-endpoints/ - Inspect model endpoints with pricing and provider details
  • list-providers/ - List available providers with policy information
  • structured-output/ - JSON schema validation and structured responses
  • tool-calling/ - Complete tool/function calling examples with streaming
  • transforms/ - Message transforms for context window management
  • web_search/ - Web search plugin examples with various configurations
  • advanced/ - Advanced features like rate limiting and custom configuration

To run an example:

# Set your API key
export OPENROUTER_API_KEY="your-api-key"

# Run basic examples
go run examples/basic/main.go

# Run streaming examples
go run examples/streaming/main.go

# Run list models examples
go run examples/list-models/main.go

# Run model endpoints examples
go run examples/model-endpoints/main.go

# Run list providers examples
go run examples/list-providers/main.go

# Run advanced examples
go run examples/advanced/main.go

# Run structured output examples
go run examples/structured-output/main.go

# Run tool calling examples
go run examples/tool-calling/main.go

# Run streaming tool calling example
go run examples/tool-calling/streaming.go

# Run transforms examples
go run examples/transforms/main.go

# Run web search examples
go run examples/web_search/main.go

Documentation

For detailed API documentation and usage examples, see DOCUMENTATION.md.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Documentation

Overview

Package openrouter provides Go bindings for the OpenRouter API.

Index

Constants

This section is empty.

Variables

View Source 
var ErrNoAPIKey = &ValidationError{Field: "apiKey", Message: "API key is required"}

ErrNoAPIKey is returned when no API key is provided.

View Source 
var ErrNoMessages = &ValidationError{Field: "messages", Message: "at least one message is required"}

ErrNoMessages is returned when no messages are provided for chat completion.

View Source 
var ErrNoModel = &ValidationError{Field: "model", Message: "model is required"}

ErrNoModel is returned when no model is specified.

View Source 
var ErrNoPrompt = &ValidationError{Field: "prompt", Message: "prompt is required"}

ErrNoPrompt is returned when no prompt is provided for completion.

Functions

func ConcatenateChatStreamResponses 

func ConcatenateChatStreamResponses(responses []ChatCompletionResponse) string

Helper function to concatenate streaming chat responses.

func ConcatenateCompletionStreamResponses 

func ConcatenateCompletionStreamResponses(responses []CompletionResponse) string

Helper function to concatenate streaming completion responses.

func DefaultWebSearchPrompt 

func DefaultWebSearchPrompt(date string) string

DefaultWebSearchPrompt returns the default search prompt template. The date should be substituted with the current date when used.

func EncodeAudioBytesToBase64 added in v1.1.0 

func EncodeAudioBytesToBase64(audioData []byte, format string) (string, error)

EncodeAudioBytesToBase64 encodes audio bytes to base64. The format should be one of: "wav", "mp3"

func EncodeAudioToBase64 added in v1.1.0 

func EncodeAudioToBase64(audioPath string) (string, string, error)

EncodeAudioToBase64 reads an audio file and encodes it to base64. It automatically detects the audio format based on the file extension. Supported formats: wav, mp3 Note: Audio must be base64-encoded; direct URLs are not supported.

func EncodeImageBytesToBase64 added in v1.1.0 

func EncodeImageBytesToBase64(imageData []byte, contentType string) string

EncodeImageBytesToBase64 encodes image bytes to a base64 data URL. The contentType should be one of: "image/png", "image/jpeg", "image/webp", "image/gif"

func EncodeImageToBase64 added in v1.1.0 

func EncodeImageToBase64(imagePath string) (string, error)

EncodeImageToBase64 reads an image file and encodes it to a base64 data URL. It automatically detects the image format based on the file extension. Supported formats: png, jpg, jpeg, webp, gif

func EncodePDFBytesToBase64 added in v1.1.0 

func EncodePDFBytesToBase64(pdfData []byte) string

EncodePDFBytesToBase64 encodes PDF bytes to a base64 data URL.

func EncodePDFToBase64 added in v1.1.0 

func EncodePDFToBase64(pdfPath string) (string, error)

EncodePDFToBase64 reads a PDF file and encodes it to a base64 data URL.

func RetryWithBackoff 

func RetryWithBackoff(ctx context.Context, config *RetryConfig, fn func() error) error

RetryWithBackoff executes a function with exponential backoff retry logic.

func WithOnlineModel 

func WithOnlineModel(model string) string

WithOnlineModel appends ":online" to a model name to enable web search. This is a shortcut for using the web plugin.

Types

type APIError 

type APIError struct {
	Message  string                 `json:"message"`
	Type     string                 `json:"type"`
	Code     string                 `json:"code,omitempty"`
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

APIError represents the error details in an error response.

type APIKey 

type APIKey struct {
	Name      string  `json:"name"`
	Label     string  `json:"label"`
	Limit     float64 `json:"limit"`
	Disabled  bool    `json:"disabled"`
	CreatedAt string  `json:"created_at"`
	UpdatedAt string  `json:"updated_at"`
	Hash      string  `json:"hash"`
}

APIKey represents an API key in the list keys response.

type ActivityData 

type ActivityData struct {
	Date               string  `json:"date"`
	Model              string  `json:"model"`
	ModelPermaslug     string  `json:"model_permaslug"`
	EndpointID         string  `json:"endpoint_id"`
	ProviderName       string  `json:"provider_name"`
	Usage              float64 `json:"usage"`
	BYOKUsageInference float64 `json:"byok_usage_inference"`
	Requests           float64 `json:"requests"`
	PromptTokens       float64 `json:"prompt_tokens"`
	CompletionTokens   float64 `json:"completion_tokens"`
	ReasoningTokens    float64 `json:"reasoning_tokens"`
}

ActivityData represents daily user activity data grouped by model endpoint.

type ActivityOptions 

type ActivityOptions struct {
	// Date filters by a single UTC date in the last 30 days (YYYY-MM-DD format).
	// Example: "2024-01-15"
	// Note: The API returns dates with timestamps (e.g., "2024-01-15 00:00:00") but expects
	// the filter parameter in YYYY-MM-DD format.
	Date string
}

ActivityOptions contains optional parameters for retrieving activity data.

type ActivityResponse 

type ActivityResponse struct {
	Data []ActivityData `json:"data"`
}

ActivityResponse represents the response from the activity endpoint.

type Annotation 

type Annotation struct {
	// Type of annotation (e.g., "url_citation", "file")
	Type string `json:"type"`
	// URLCitation contains details for URL citation annotations
	URLCitation *URLCitation `json:"url_citation,omitempty"`
	// FileAnnotation contains details for file annotations (parsed file metadata)
	FileAnnotation *FileAnnotation `json:"file,omitempty"`
}

Annotation represents an annotation in a message response.

type ChatCompletionOption 

type ChatCompletionOption func(*ChatCompletionRequest)

ChatCompletionOption is a functional option for chat completion requests.

func WithAllowFallbacks 

func WithAllowFallbacks(allow bool) ChatCompletionOption

WithAllowFallbacks controls whether to allow backup providers. When set to false, the request will fail if primary providers are unavailable.

func WithDataCollection 

func WithDataCollection(policy string) ChatCompletionOption

WithDataCollection controls whether to use providers that may store data. Use "allow" to allow data collection, "deny" to prevent it.

func WithFloorPrice 

func WithFloorPrice() ChatCompletionOption

WithFloorPrice is a shortcut for sorting by price. Equivalent to WithProviderSort("price").

func WithFrequencyPenalty 

func WithFrequencyPenalty(penalty float64) ChatCompletionOption

WithFrequencyPenalty sets the frequency penalty.

func WithIgnoreProviders 

func WithIgnoreProviders(providers ...string) ChatCompletionOption

WithIgnoreProviders specifies providers to skip for this request.

func WithJSONMode 

func WithJSONMode() ChatCompletionOption

WithJSONMode sets the response format to return JSON without a specific schema. Note: This is less strict than WithJSONSchema and doesn't enforce a specific structure.

func WithJSONSchema 

func WithJSONSchema(name string, strict bool, schema map[string]interface{}) ChatCompletionOption

WithJSONSchema sets the response format to use a specific JSON schema for structured outputs. This ensures the model response follows the provided schema exactly.

func WithLogProbs 

func WithLogProbs(topLogProbs int) ChatCompletionOption

WithLogProbs enables log probabilities in the response.

func WithMaxPrice 

func WithMaxPrice(maxPrice MaxPrice) ChatCompletionOption

WithMaxPrice sets maximum pricing constraints for the request.

func WithMaxTokens 

func WithMaxTokens(maxTokens int) ChatCompletionOption

WithMaxTokens sets the max_tokens parameter.

func WithMessages 

func WithMessages(messages []Message) ChatCompletionOption

WithMessages sets the messages for the chat completion request.

func WithMetadata 

func WithMetadata(metadata map[string]interface{}) ChatCompletionOption

WithMetadata sets metadata headers for the request.

func WithModel 

func WithModel(model string) ChatCompletionOption

WithModel sets the model for the request.

func WithModels 

func WithModels(models ...string) ChatCompletionOption

WithModels sets the models for fallback.

func WithNitro 

func WithNitro() ChatCompletionOption

WithNitro is a shortcut for sorting by throughput. Equivalent to WithProviderSort("throughput").

func WithOnlyProviders 

func WithOnlyProviders(providers ...string) ChatCompletionOption

WithOnlyProviders restricts the request to only use specified providers.

func WithParallelToolCalls 

func WithParallelToolCalls(parallel *bool) ChatCompletionOption

WithParallelToolCalls controls whether multiple tools can be called in parallel. Default is true for most models that support tool calling.

func WithPlugins 

func WithPlugins(plugins ...Plugin) ChatCompletionOption

WithPlugins adds plugin configurations to the request.

func WithPresencePenalty 

func WithPresencePenalty(penalty float64) ChatCompletionOption

WithPresencePenalty sets the presence penalty.

func WithProvider 

func WithProvider(provider Provider) ChatCompletionOption

WithProvider sets provider-specific parameters.

func WithProviderOrder 

func WithProviderOrder(providers ...string) ChatCompletionOption

WithProviderOrder sets the order of providers to try. The router will prioritize providers in this list, and in this order.

func WithProviderSort 

func WithProviderSort(sort string) ChatCompletionOption

WithProviderSort sorts providers by the specified attribute. Valid values: "price" (lowest cost), "throughput" (highest), "latency" (lowest)

func WithQuantizations 

func WithQuantizations(quantizations ...string) ChatCompletionOption

WithQuantizations filters providers by quantization levels. Valid values: "int4", "int8", "fp4", "fp6", "fp8", "fp16", "bf16", "fp32", "unknown"

func WithRepetitionPenalty 

func WithRepetitionPenalty(penalty float64) ChatCompletionOption

WithRepetitionPenalty sets the repetition penalty.

func WithRequireParameters 

func WithRequireParameters(require bool) ChatCompletionOption

WithRequireParameters only routes to providers that support all request parameters.

func WithResponseFormat 

func WithResponseFormat(format ResponseFormat) ChatCompletionOption

WithResponseFormat sets the response format.

func WithRoute 

func WithRoute(route string) ChatCompletionOption

WithRoute sets the routing preference.

func WithSeed 

func WithSeed(seed int) ChatCompletionOption

WithSeed sets the random seed.

func WithStop 

func WithStop(stop ...string) ChatCompletionOption

WithStop sets the stop sequences.

func WithTemperature 

func WithTemperature(temperature float64) ChatCompletionOption

WithTemperature sets the temperature parameter.

func WithToolChoice 

func WithToolChoice(toolChoice interface{}) ChatCompletionOption

WithToolChoice sets the tool choice strategy.

func WithTools 

func WithTools(tools ...Tool) ChatCompletionOption

WithTools sets the available tools/functions.

func WithTopK 

func WithTopK(topK int) ChatCompletionOption

WithTopK sets the top_k parameter.

func WithTopP 

func WithTopP(topP float64) ChatCompletionOption

WithTopP sets the top_p parameter.

func WithTransforms 

func WithTransforms(transforms ...string) ChatCompletionOption

WithTransforms sets the transforms to apply.

func WithWebSearchOptions 

func WithWebSearchOptions(options *WebSearchOptions) ChatCompletionOption

WithWebSearchOptions sets web search options for the request.

func WithZDR 

func WithZDR(enabled bool) ChatCompletionOption

WithZDR enables Zero Data Retention for the request. This ensures the request is only routed to endpoints with Zero Data Retention policy.

type ChatCompletionRequest 

type ChatCompletionRequest struct {
	Model    string    `json:"model"`
	Messages []Message `json:"messages"`

	// Optional parameters
	Temperature       *float64               `json:"temperature,omitempty"`
	TopP              *float64               `json:"top_p,omitempty"`
	TopK              *int                   `json:"top_k,omitempty"`
	FrequencyPenalty  *float64               `json:"frequency_penalty,omitempty"`
	PresencePenalty   *float64               `json:"presence_penalty,omitempty"`
	RepetitionPenalty *float64               `json:"repetition_penalty,omitempty"`
	MaxTokens         *int                   `json:"max_tokens,omitempty"`
	MinP              *float64               `json:"min_p,omitempty"`
	TopA              *float64               `json:"top_a,omitempty"`
	Seed              *int                   `json:"seed,omitempty"`
	Stop              []string               `json:"stop,omitempty"`
	Stream            bool                   `json:"stream,omitempty"`
	LogProbs          *bool                  `json:"logprobs,omitempty"`
	TopLogProbs       *int                   `json:"top_logprobs,omitempty"`
	ResponseFormat    *ResponseFormat        `json:"response_format,omitempty"`
	Tools             []Tool                 `json:"tools,omitempty"`
	ToolChoice        interface{}            `json:"tool_choice,omitempty"`
	ParallelToolCalls *bool                  `json:"parallel_tool_calls,omitempty"`
	Provider          *Provider              `json:"provider,omitempty"`
	Transforms        []string               `json:"transforms,omitempty"`
	Models            []string               `json:"models,omitempty"`
	Route             string                 `json:"route,omitempty"`
	Plugins           []Plugin               `json:"plugins,omitempty"`
	WebSearchOptions  *WebSearchOptions      `json:"web_search_options,omitempty"`
	Metadata          map[string]interface{} `json:"-"` // Used for headers
}

ChatCompletionRequest represents a chat completion request to the OpenRouter API.

func (*ChatCompletionRequest) GetMetadata 

func (r *ChatCompletionRequest) GetMetadata() map[string]interface{}

GetMetadata helper methods for request types

type ChatCompletionResponse 

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

ChatCompletionResponse represents a chat completion response from the OpenRouter API.

type ChatStream 

type ChatStream = Stream[ChatCompletionResponse]

ChatStream represents a streaming chat completion response.

type Choice 

type Choice struct {
	Index        int       `json:"index"`
	Message      Message   `json:"message"`
	FinishReason string    `json:"finish_reason"`
	LogProbs     *LogProbs `json:"logprobs,omitempty"`
	Delta        *Message  `json:"delta,omitempty"` // For streaming
}

Choice represents a choice in the chat completion response.

type Client 

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

Client is the main client for interacting with the OpenRouter API.

func NewClient 

func NewClient(opts ...ClientOption) *Client

NewClient creates a new OpenRouter API client. The API key can be provided either as the first argument (for backwards compatibility) or via WithAPIKey option. If both are provided, the option takes precedence.

func (*Client) ChatComplete 

func (c *Client) ChatComplete(ctx context.Context, messages []Message, opts ...ChatCompletionOption) (*ChatCompletionResponse, error)

ChatComplete sends a chat completion request to the OpenRouter API.

func (*Client) ChatCompleteStream 

func (c *Client) ChatCompleteStream(ctx context.Context, messages []Message, opts ...ChatCompletionOption) (*ChatStream, error)

ChatCompleteStream sends a streaming chat completion request to the OpenRouter API. This method returns a stream that can be used to receive events as they arrive.

func (*Client) Complete 

func (c *Client) Complete(ctx context.Context, prompt string, opts ...CompletionOption) (*CompletionResponse, error)

Complete sends a legacy completion request to the OpenRouter API.

func (*Client) CompleteStream 

func (c *Client) CompleteStream(ctx context.Context, prompt string, opts ...CompletionOption) (*CompletionStream, error)

CompleteStream sends a streaming completion request to the OpenRouter API. This method returns a stream that can be used to receive events as they arrive.

func (*Client) CompleteWithContext 

func (c *Client) CompleteWithContext(ctx context.Context, contextPrompt, userPrompt string, opts ...CompletionOption) (*CompletionResponse, error)

CompleteWithContext is a convenience method that combines prompt completion with context.

func (*Client) CompleteWithExamples 

func (c *Client) CompleteWithExamples(ctx context.Context, instruction string, examples []string, prompt string, opts ...CompletionOption) (*CompletionResponse, error)

CompleteWithExamples is a convenience method for few-shot prompting.

func (*Client) CreateEmbedding added in v1.2.0 

func (c *Client) CreateEmbedding(ctx context.Context, input interface{}, model string, opts ...EmbeddingOption) (*EmbeddingResponse, error)

CreateEmbedding sends an embedding request to the OpenRouter API. The input can be a string or []string for text embeddings.

func (*Client) CreateEmbeddings added in v1.2.0 

func (c *Client) CreateEmbeddings(ctx context.Context, inputs []string, model string, opts ...EmbeddingOption) (*EmbeddingResponse, error)

CreateEmbeddings is an alias for CreateEmbedding that emphasizes batch embedding. The input should be a []string for batch text embeddings.

func (*Client) CreateKey 

func (c *Client) CreateKey(ctx context.Context, request *CreateKeyRequest) (*CreateKeyResponse, error)

CreateKey creates a new API key with the specified name and optional limit. Requires a Provisioning API key (not a regular inference API key).

IMPORTANT: The response contains the actual API key value in the Key field. This is the ONLY time the key value will be returned. Store it securely!

Example: 

ctx := context.Background()
limit := 100.0
includeBYOK := true
keyResp, err := client.CreateKey(ctx, &openrouter.CreateKeyRequest{
    Name:               "Production API Key",
    Limit:              &limit,
    IncludeBYOKInLimit: &includeBYOK,
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("New API Key: %s\n", keyResp.Key) // SAVE THIS!
fmt.Printf("Label: %s\n", keyResp.Data.Label)
fmt.Printf("Limit: $%.2f\n", keyResp.Data.Limit)

func (*Client) DeleteKey 

func (c *Client) DeleteKey(ctx context.Context, hash string) (*DeleteKeyResponse, error)

DeleteKey deletes an API key by its hash. Requires a Provisioning API key (not a regular inference API key).

WARNING: This operation is irreversible! The API key will be permanently deleted.

Example: 

ctx := context.Background()
// Get the hash from ListKeys or from key creation
hash := "abc123hash"
result, err := client.DeleteKey(ctx, hash)
if err != nil {
    log.Fatal(err)
}
if result.Data.Success {
    fmt.Println("API key successfully deleted")
}

func (*Client) GetActivity 

func (c *Client) GetActivity(ctx context.Context, opts *ActivityOptions) (*ActivityResponse, error)

GetActivity retrieves daily user activity data grouped by model endpoint for the last 30 (completed) UTC days.

If ingesting on a schedule, it is recommended to wait for ~30 minutes after the UTC boundary to request the previous day, because events are aggregated by request start time, and some reasoning models may take a few minutes to complete.

Note: A provisioning key is required to access this endpoint, to ensure that your historic usage is not accessible to just anyone in your org with an inference API key.

Example: 

ctx := context.Background()
// Get all activity
activity, err := client.GetActivity(ctx, nil)
if err != nil {
    log.Fatal(err)
}

// Filter by date
activity, err := client.GetActivity(ctx, &openrouter.ActivityOptions{
    Date: "2024-01-15",
})
if err != nil {
    log.Fatal(err)
}

for _, data := range activity.Data {
    fmt.Printf("%s - %s: %.2f requests, $%.4f usage\n",
        data.Date, data.Model, data.Requests, data.Usage)
}

func (*Client) GetCredits 

func (c *Client) GetCredits(ctx context.Context) (*CreditsResponse, error)

GetCredits retrieves the total credits purchased and used for the authenticated user.

Example: 

ctx := context.Background()
credits, err := client.GetCredits(ctx)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Credits: %.2f, Usage: %.2f, Remaining: %.2f\n",
    credits.Data.TotalCredits,
    credits.Data.TotalUsage,
    credits.Data.TotalCredits - credits.Data.TotalUsage)

func (*Client) GetKey 

func (c *Client) GetKey(ctx context.Context) (*KeyResponse, error)

GetKey retrieves information about the current API key including usage, limits, and rate limit information for the authenticated user.

Example: 

ctx := context.Background()
keyInfo, err := client.GetKey(ctx)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Label: %s\n", keyInfo.Data.Label)
if keyInfo.Data.Limit != nil {
    fmt.Printf("Limit: $%.2f\n", *keyInfo.Data.Limit)
}
fmt.Printf("Usage: $%.4f\n", keyInfo.Data.Usage)
if keyInfo.Data.LimitRemaining != nil {
    fmt.Printf("Remaining: $%.4f\n", *keyInfo.Data.LimitRemaining)
}

func (*Client) GetKeyByHash 

func (c *Client) GetKeyByHash(ctx context.Context, hash string) (*GetKeyByHashResponse, error)

GetKeyByHash retrieves details about a specific API key by its hash. Requires a Provisioning API key (not a regular inference API key).

Example: 

ctx := context.Background()
// Get the hash from ListKeys or from key creation
hash := "abc123hash"
keyDetails, err := client.GetKeyByHash(ctx, hash)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Label: %s\n", keyDetails.Data.Label)
fmt.Printf("Limit: $%.2f\n", keyDetails.Data.Limit)
fmt.Printf("Disabled: %v\n", keyDetails.Data.Disabled)

func (*Client) ListEmbeddingsModels added in v1.2.0 

func (c *Client) ListEmbeddingsModels(ctx context.Context) (*EmbeddingsModelsResponse, error)

ListEmbeddingsModels retrieves a list of available embedding models.

func (*Client) ListKeys 

func (c *Client) ListKeys(ctx context.Context, options *ListKeysOptions) (*ListKeysResponse, error)

ListKeys returns a list of all API keys associated with the account. Requires a Provisioning API key (not a regular inference API key).

Example: 

ctx := context.Background()
keys, err := client.ListKeys(ctx, nil)
if err != nil {
    log.Fatal(err)
}
for _, key := range keys.Data {
    fmt.Printf("Label: %s, Disabled: %v\n", key.Label, key.Disabled)
}

With options: 

offset := 10
includeDisabled := true
keys, err := client.ListKeys(ctx, &openrouter.ListKeysOptions{
    Offset: &offset,
    IncludeDisabled: &includeDisabled,
})

func (*Client) ListModelEndpoints 

func (c *Client) ListModelEndpoints(ctx context.Context, author, slug string) (*ModelEndpointsResponse, error)

ListModelEndpoints retrieves the list of endpoints for a specific model. The model is specified by its author and slug (e.g., author="openai", slug="gpt-4"). This endpoint provides detailed information about each provider offering the model, including pricing, context length, supported parameters, and uptime statistics.

func (*Client) ListModels 

func (c *Client) ListModels(ctx context.Context, opts *ListModelsOptions) (*ModelsResponse, error)

ListModels retrieves a list of models available through the OpenRouter API. Note: supported_parameters is a union of all parameters supported by all providers for each model. There may not be a single provider which offers all of the listed parameters for a model.

func (*Client) ListProviders 

func (c *Client) ListProviders(ctx context.Context) (*ProvidersResponse, error)

ListProviders retrieves a list of all providers available through the OpenRouter API. Returns provider information including name, slug, and policy URLs.

Example: 

ctx := context.Background()
providers, err := client.ListProviders(ctx)
if err != nil {
    log.Fatal(err)
}
for _, provider := range providers.Data {
    fmt.Printf("%s (%s)\n", provider.Name, provider.Slug)
}

func (*Client) UpdateKey 

func (c *Client) UpdateKey(ctx context.Context, hash string, request *UpdateKeyRequest) (*UpdateKeyResponse, error)

UpdateKey updates an existing API key by its hash. Requires a Provisioning API key (not a regular inference API key).

All fields in the request are optional - only include the fields you want to update.

Example: 

ctx := context.Background()
hash := "abc123hash"

// Update just the name
newName := "Updated Key Name"
result, err := client.UpdateKey(ctx, hash, &openrouter.UpdateKeyRequest{
    Name: &newName,
})

// Disable a key
disabled := true
result, err := client.UpdateKey(ctx, hash, &openrouter.UpdateKeyRequest{
    Disabled: &disabled,
})

// Update limit
newLimit := 200.0
result, err := client.UpdateKey(ctx, hash, &openrouter.UpdateKeyRequest{
    Limit: &newLimit,
})

type ClientOption 

type ClientOption func(*Client)

ClientOption is a functional option for configuring the Client.

func WithAPIKey 

func WithAPIKey(apiKey string) ClientOption

WithAPIKey sets the API key for the client.

func WithAppName 

func WithAppName(appName string) ClientOption

WithAppName sets the X-Title header for requests.

func WithBaseURL 

func WithBaseURL(baseURL string) ClientOption

WithBaseURL sets a custom base URL for the API.

func WithDefaultModel 

func WithDefaultModel(model string) ClientOption

WithDefaultModel sets a default model to use for requests.

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) ClientOption

WithHTTPClient sets a custom HTTP client.

func WithHeader 

func WithHeader(key, value string) ClientOption

WithHeader adds a custom header to all requests.

func WithReferer 

func WithReferer(referer string) ClientOption

WithReferer sets the HTTP-Referer header for requests.

func WithRetry 

func WithRetry(maxRetries int, retryDelay time.Duration) ClientOption

WithRetry configures retry behavior.

func WithTimeout 

func WithTimeout(timeout time.Duration) ClientOption

WithTimeout sets the HTTP client timeout.

type CompletionChoice 

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

CompletionChoice represents a choice in the legacy completion response.

type CompletionOption 

type CompletionOption func(*CompletionRequest)

CompletionOption is a functional option for completion requests.

func WithCompletionAllowFallbacks 

func WithCompletionAllowFallbacks(allow bool) CompletionOption

WithCompletionAllowFallbacks controls whether to allow backup providers for completion requests.

func WithCompletionBestOf 

func WithCompletionBestOf(bestOf int) CompletionOption

WithCompletionBestOf sets the number of completions to generate server-side.

func WithCompletionDataCollection 

func WithCompletionDataCollection(policy string) CompletionOption

WithCompletionDataCollection controls whether to use providers that may store data.

func WithCompletionEcho 

func WithCompletionEcho(echo bool) CompletionOption

WithCompletionEcho enables echoing the prompt in the response.

func WithCompletionFloorPrice 

func WithCompletionFloorPrice() CompletionOption

WithCompletionFloorPrice is a shortcut for sorting by price for completion requests.

func WithCompletionIgnoreProviders 

func WithCompletionIgnoreProviders(providers ...string) CompletionOption

WithCompletionIgnoreProviders specifies providers to skip for this request.

func WithCompletionJSONMode 

func WithCompletionJSONMode() CompletionOption

WithCompletionJSONMode sets the response format to return JSON for completion requests.

func WithCompletionJSONSchema 

func WithCompletionJSONSchema(name string, strict bool, schema map[string]interface{}) CompletionOption

WithCompletionJSONSchema sets the response format to use a specific JSON schema for completion requests.

func WithCompletionLogProbs 

func WithCompletionLogProbs(logProbs int) CompletionOption

WithCompletionLogProbs sets the number of log probabilities to return.

func WithCompletionMaxPrice 

func WithCompletionMaxPrice(maxPrice MaxPrice) CompletionOption

WithCompletionMaxPrice sets maximum pricing constraints for the completion request.

func WithCompletionMaxTokens 

func WithCompletionMaxTokens(maxTokens int) CompletionOption

WithCompletionMaxTokens sets the max_tokens for completion.

func WithCompletionMetadata 

func WithCompletionMetadata(metadata map[string]interface{}) CompletionOption

WithCompletionMetadata sets metadata headers for the completion request.

func WithCompletionModel 

func WithCompletionModel(model string) CompletionOption

WithCompletionModel sets the model for the completion request.

func WithCompletionModels 

func WithCompletionModels(models ...string) CompletionOption

WithCompletionModels sets the models for fallback in completion requests.

func WithCompletionN 

func WithCompletionN(n int) CompletionOption

WithCompletionN sets the number of completions to generate.

func WithCompletionNitro 

func WithCompletionNitro() CompletionOption

WithCompletionNitro is a shortcut for sorting by throughput for completion requests.

func WithCompletionOnlyProviders 

func WithCompletionOnlyProviders(providers ...string) CompletionOption

WithCompletionOnlyProviders restricts the request to only use specified providers.

func WithCompletionPlugins 

func WithCompletionPlugins(plugins ...Plugin) CompletionOption

WithCompletionPlugins adds plugin configurations to the completion request.

func WithCompletionProvider 

func WithCompletionProvider(provider Provider) CompletionOption

WithCompletionProvider sets provider-specific parameters for completion.

func WithCompletionProviderOrder 

func WithCompletionProviderOrder(providers ...string) CompletionOption

WithCompletionProviderOrder sets the order of providers to try for completion requests.

func WithCompletionProviderSort 

func WithCompletionProviderSort(sort string) CompletionOption

WithCompletionProviderSort sorts providers by the specified attribute.

func WithCompletionQuantizations 

func WithCompletionQuantizations(quantizations ...string) CompletionOption

WithCompletionQuantizations filters providers by quantization levels.

func WithCompletionRequireParameters 

func WithCompletionRequireParameters(require bool) CompletionOption

WithCompletionRequireParameters only routes to providers that support all request parameters.

func WithCompletionResponseFormat 

func WithCompletionResponseFormat(format ResponseFormat) CompletionOption

WithCompletionResponseFormat sets the response format for completion requests.

func WithCompletionRoute 

func WithCompletionRoute(route string) CompletionOption

WithCompletionRoute sets the routing preference for completion requests.

func WithCompletionStop 

func WithCompletionStop(stop ...string) CompletionOption

WithCompletionStop sets stop sequences for completion.

func WithCompletionSuffix 

func WithCompletionSuffix(suffix string) CompletionOption

WithCompletionSuffix sets the suffix to append after the completion.

func WithCompletionTemperature 

func WithCompletionTemperature(temperature float64) CompletionOption

WithCompletionTemperature sets the temperature for completion.

func WithCompletionTopP 

func WithCompletionTopP(topP float64) CompletionOption

WithCompletionTopP sets the top_p for completion.

func WithCompletionTransforms 

func WithCompletionTransforms(transforms ...string) CompletionOption

WithCompletionTransforms sets the transforms to apply to completion requests.

func WithCompletionWebSearchOptions 

func WithCompletionWebSearchOptions(options *WebSearchOptions) CompletionOption

WithCompletionWebSearchOptions sets web search options for the completion request.

func WithCompletionZDR 

func WithCompletionZDR(enabled bool) CompletionOption

WithCompletionZDR enables Zero Data Retention for the completion request. This ensures the request is only routed to endpoints with Zero Data Retention policy.

type CompletionRequest 

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

	// Optional parameters
	Temperature       *float64               `json:"temperature,omitempty"`
	TopP              *float64               `json:"top_p,omitempty"`
	TopK              *int                   `json:"top_k,omitempty"`
	FrequencyPenalty  *float64               `json:"frequency_penalty,omitempty"`
	PresencePenalty   *float64               `json:"presence_penalty,omitempty"`
	RepetitionPenalty *float64               `json:"repetition_penalty,omitempty"`
	MaxTokens         *int                   `json:"max_tokens,omitempty"`
	MinP              *float64               `json:"min_p,omitempty"`
	TopA              *float64               `json:"top_a,omitempty"`
	Seed              *int                   `json:"seed,omitempty"`
	Stop              []string               `json:"stop,omitempty"`
	Stream            bool                   `json:"stream,omitempty"`
	LogProbs          *int                   `json:"logprobs,omitempty"`
	Echo              *bool                  `json:"echo,omitempty"`
	N                 *int                   `json:"n,omitempty"`
	BestOf            *int                   `json:"best_of,omitempty"`
	Suffix            *string                `json:"suffix,omitempty"`
	ResponseFormat    *ResponseFormat        `json:"response_format,omitempty"`
	Provider          *Provider              `json:"provider,omitempty"`
	Transforms        []string               `json:"transforms,omitempty"`
	Models            []string               `json:"models,omitempty"`
	Route             string                 `json:"route,omitempty"`
	Plugins           []Plugin               `json:"plugins,omitempty"`
	WebSearchOptions  *WebSearchOptions      `json:"web_search_options,omitempty"`
	Metadata          map[string]interface{} `json:"-"` // Used for headers
}

CompletionRequest represents a legacy completion request to the OpenRouter API.

func (*CompletionRequest) GetMetadata 

func (r *CompletionRequest) GetMetadata() map[string]interface{}

type CompletionResponse 

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

CompletionResponse represents a legacy completion response from the OpenRouter API.

type CompletionStream 

type CompletionStream = Stream[CompletionResponse]

CompletionStream represents a streaming completion response.

type ContentBuilder added in v1.1.0 

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

CreateContentParts is a helper to build custom content part arrays.

func NewContentBuilder added in v1.1.0 

func NewContentBuilder() *ContentBuilder

NewContentBuilder creates a new content builder.

func (*ContentBuilder) AddAudio added in v1.1.0 

func (cb *ContentBuilder) AddAudio(audioData string, format string) *ContentBuilder

AddAudio adds an audio input to the content builder. The audioData should be base64-encoded audio data. The format should be one of: "wav", "mp3"

func (*ContentBuilder) AddBase64Audio added in v1.1.0 

func (cb *ContentBuilder) AddBase64Audio(audioPath string) (*ContentBuilder, error)

AddBase64Audio reads and encodes an audio file, then adds it to the content builder.

func (*ContentBuilder) AddBase64PDF added in v1.1.0 

func (cb *ContentBuilder) AddBase64PDF(pdfPath string, filename string) (*ContentBuilder, error)

AddBase64PDF reads and encodes a PDF file, then adds it to the content builder.

func (*ContentBuilder) AddFile added in v1.1.0 

func (cb *ContentBuilder) AddFile(filename string, fileData string) *ContentBuilder

AddFile adds a file to the content builder.

func (*ContentBuilder) AddImage added in v1.1.0 

func (cb *ContentBuilder) AddImage(imageURL string) *ContentBuilder

AddImage adds an image content part.

func (*ContentBuilder) AddImageWithDetail added in v1.1.0 

func (cb *ContentBuilder) AddImageWithDetail(imageURL string, detail string) *ContentBuilder

AddImageWithDetail adds an image content part with a detail level.

func (*ContentBuilder) AddPDF added in v1.1.0 

func (cb *ContentBuilder) AddPDF(pdfURL string, filename string) *ContentBuilder

AddPDF adds a PDF file to the content builder. The pdfURL can be either a direct URL or a base64-encoded data URL.

func (*ContentBuilder) AddText added in v1.1.0 

func (cb *ContentBuilder) AddText(text string) *ContentBuilder

AddText adds a text content part.

func (*ContentBuilder) Build added in v1.1.0 

func (cb *ContentBuilder) Build() []ContentPart

Build returns the content parts array.

func (*ContentBuilder) BuildMessage added in v1.1.0 

func (cb *ContentBuilder) BuildMessage(role string) Message

BuildMessage creates a message with the builder's content.

type ContentPart 

type ContentPart struct {
	Type       string      `json:"type"`
	Text       string      `json:"text,omitempty"`
	ImageURL   *ImageURL   `json:"image_url,omitempty"`
	File       *File       `json:"file,omitempty"`
	InputAudio *InputAudio `json:"input_audio,omitempty"`
}

ContentPart represents a part of message content (text, image, file, or audio).

type CreateKeyRequest 

type CreateKeyRequest struct {
	// Name is the required name/label for the API key
	Name string `json:"name"`
	// Limit is the optional credit limit for the API key
	Limit *float64 `json:"limit,omitempty"`
	// IncludeBYOKInLimit controls whether BYOK usage counts toward the limit
	IncludeBYOKInLimit *bool `json:"include_byok_in_limit,omitempty"`
}

CreateKeyRequest represents a request to create a new API key.

type CreateKeyResponse 

type CreateKeyResponse struct {
	Data APIKey `json:"data"`
	// Key contains the actual API key value (only returned on creation)
	Key string `json:"key,omitempty"`
}

CreateKeyResponse represents the response from creating a new API key.

type CreditsData 

type CreditsData struct {
	TotalCredits float64 `json:"total_credits"`
	TotalUsage   float64 `json:"total_usage"`
}

CreditsData contains credit balance information for the authenticated user.

type CreditsResponse 

type CreditsResponse struct {
	Data CreditsData `json:"data"`
}

CreditsResponse represents the response from the credits endpoint.

type DeleteKeyData 

type DeleteKeyData struct {
	Success bool `json:"success"`
}

DeleteKeyData contains the result of a delete operation.

type DeleteKeyResponse 

type DeleteKeyResponse struct {
	Data DeleteKeyData `json:"data"`
}

DeleteKeyResponse represents the response from deleting an API key.

type EmbeddingContentPart added in v1.2.0 

type EmbeddingContentPart struct {
	// Type specifies the type of content ("text" or "image_url").
	Type string `json:"type"`
	// Text is the text content (when Type is "text").
	Text string `json:"text,omitempty"`
	// ImageURL contains the image URL (when Type is "image_url").
	ImageURL *EmbeddingImageURL `json:"image_url,omitempty"`
}

EmbeddingContentPart represents a content part for multimodal embedding input.

type EmbeddingData added in v1.2.0 

type EmbeddingData struct {
	// Object is the object type, always "embedding".
	Object string `json:"object"`
	// Embedding is the embedding vector. Can be []float64 or base64 string depending on encoding_format.
	Embedding interface{} `json:"embedding"`
	// Index is the index of this embedding in the input list.
	Index int `json:"index"`
}

EmbeddingData represents a single embedding in the response.

func (*EmbeddingData) GetEmbeddingBase64 added in v1.2.0 

func (e *EmbeddingData) GetEmbeddingBase64() string

GetEmbeddingBase64 extracts the embedding as a base64 string from an EmbeddingData. Returns empty string if the embedding is not in base64 format.

func (*EmbeddingData) GetEmbeddingVector added in v1.2.0 

func (e *EmbeddingData) GetEmbeddingVector() []float64

GetEmbeddingVector extracts the embedding vector as []float64 from an EmbeddingData. Returns nil if the embedding is not in float format or conversion fails.

type EmbeddingImageURL added in v1.2.0 

type EmbeddingImageURL struct {
	// URL is the image URL.
	URL string `json:"url"`
}

EmbeddingImageURL represents an image URL for multimodal embedding input.

type EmbeddingMultimodalInput added in v1.2.0 

type EmbeddingMultimodalInput struct {
	// Content is the array of content parts.
	Content []EmbeddingContentPart `json:"content"`
}

EmbeddingMultimodalInput represents multimodal input for embeddings.

type EmbeddingOption added in v1.2.0 

type EmbeddingOption func(*EmbeddingRequest)

EmbeddingOption is a functional option for embedding requests.

func WithEmbeddingAllowFallbacks added in v1.2.0 

func WithEmbeddingAllowFallbacks(allow bool) EmbeddingOption

WithEmbeddingAllowFallbacks controls whether to allow backup providers.

func WithEmbeddingDataCollection added in v1.2.0 

func WithEmbeddingDataCollection(policy string) EmbeddingOption

WithEmbeddingDataCollection controls whether to use providers that may store data. Use "allow" to allow data collection, "deny" to prevent it.

func WithEmbeddingDimensions added in v1.2.0 

func WithEmbeddingDimensions(dimensions int) EmbeddingOption

WithEmbeddingDimensions sets the number of dimensions for the output embeddings. Only supported by some models.

func WithEmbeddingEncodingFormat added in v1.2.0 

func WithEmbeddingEncodingFormat(format string) EmbeddingOption

WithEmbeddingEncodingFormat sets the encoding format for the embeddings. Valid values are "float" (default) or "base64".

func WithEmbeddingIgnoreProviders added in v1.2.0 

func WithEmbeddingIgnoreProviders(providers ...string) EmbeddingOption

WithEmbeddingIgnoreProviders specifies providers to skip for this request.

func WithEmbeddingInputType added in v1.2.0 

func WithEmbeddingInputType(inputType string) EmbeddingOption

WithEmbeddingInputType sets the input type for the embeddings. Some models distinguish between document and query embeddings.

func WithEmbeddingOnlyProviders added in v1.2.0 

func WithEmbeddingOnlyProviders(providers ...string) EmbeddingOption

WithEmbeddingOnlyProviders restricts the request to only use specified providers.

func WithEmbeddingProvider added in v1.2.0 

func WithEmbeddingProvider(provider Provider) EmbeddingOption

WithEmbeddingProvider sets provider-specific routing parameters.

func WithEmbeddingProviderOrder added in v1.2.0 

func WithEmbeddingProviderOrder(providers ...string) EmbeddingOption

WithEmbeddingProviderOrder sets the order of providers to try.

func WithEmbeddingProviderSort added in v1.2.0 

func WithEmbeddingProviderSort(sort string) EmbeddingOption

WithEmbeddingProviderSort sorts providers by the specified attribute. Valid values: "price" (lowest cost), "throughput" (highest), "latency" (lowest)

func WithEmbeddingUser added in v1.2.0 

func WithEmbeddingUser(user string) EmbeddingOption

WithEmbeddingUser sets an optional unique identifier for the end-user.

type EmbeddingRequest added in v1.2.0 

type EmbeddingRequest struct {
	// Input is the text or texts to embed. Can be a string, array of strings,
	// array of integers, array of integer arrays, or array of multimodal content parts.
	Input interface{} `json:"input"`
	// Model specifies the embedding model to use (required).
	Model string `json:"model"`
	// EncodingFormat specifies the format for the returned embeddings ("float" or "base64").
	EncodingFormat string `json:"encoding_format,omitempty"`
	// Dimensions specifies the number of dimensions for the output embeddings.
	Dimensions *int `json:"dimensions,omitempty"`
	// User is an optional unique identifier for the end-user.
	User string `json:"user,omitempty"`
	// Provider contains provider-specific routing parameters.
	Provider *Provider `json:"provider,omitempty"`
	// InputType specifies the type of input (e.g., for search vs. document embeddings).
	InputType string `json:"input_type,omitempty"`
}

EmbeddingRequest represents a request to create embeddings.

type EmbeddingResponse added in v1.2.0 

type EmbeddingResponse struct {
	// ID is the unique identifier for this embeddings request.
	ID string `json:"id,omitempty"`
	// Object is the object type, always "list".
	Object string `json:"object"`
	// Data contains the list of embedding objects.
	Data []EmbeddingData `json:"data"`
	// Model is the model used to generate the embeddings.
	Model string `json:"model"`
	// Usage contains token usage information for the request.
	Usage *EmbeddingUsage `json:"usage,omitempty"`
}

EmbeddingResponse represents the response from an embeddings request.

type EmbeddingUsage added in v1.2.0 

type EmbeddingUsage struct {
	// PromptTokens is the number of tokens in the input.
	PromptTokens int `json:"prompt_tokens"`
	// TotalTokens is the total number of tokens used.
	TotalTokens int `json:"total_tokens"`
	// Cost is the cost of the request (if available).
	Cost *float64 `json:"cost,omitempty"`
}

EmbeddingUsage contains token usage information for an embeddings request.

type EmbeddingsModelsResponse added in v1.2.0 

type EmbeddingsModelsResponse struct {
	Data []Model `json:"data"`
}

EmbeddingsModelsResponse represents the response from the list embeddings models endpoint.

type ErrorResponse 

type ErrorResponse struct {
	Error APIError `json:"error"`
}

ErrorResponse represents an error response from the OpenRouter API.

type File added in v1.1.0 

type File struct {
	// Filename is the name of the file (e.g., "document.pdf")
	Filename string `json:"filename"`
	// FileData can be either a URL or a base64-encoded data URL
	FileData string `json:"file_data"`
}

File represents a file attachment in the message content. Supports both URLs and base64-encoded data URLs.

type FileAnnotation added in v1.1.0 

type FileAnnotation struct {
	// Filename is the name of the file
	Filename string `json:"filename"`
	// ContentType is the MIME type of the file (e.g., "application/pdf")
	ContentType string `json:"content_type,omitempty"`
	// ParsedContent contains the extracted text/data from the file
	ParsedContent string `json:"parsed_content,omitempty"`
	// Metadata contains additional file information
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

FileAnnotation represents metadata about a parsed file. Can be sent back in subsequent requests to avoid re-parsing costs.

type Function 

type Function struct {
	Name        string                 `json:"name"`
	Description string                 `json:"description,omitempty"`
	Parameters  map[string]interface{} `json:"parameters,omitempty"`
}

Function represents a callable function.

type FunctionCall 

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

FunctionCall represents a function call made by the model.

type GetKeyByHashResponse 

type GetKeyByHashResponse struct {
	Data APIKey `json:"data"`
}

GetKeyByHashResponse represents the response from getting an API key by hash.

type ImageURL 

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

ImageURL represents an image URL in the message content.

type InputAudio added in v1.1.0 

type InputAudio struct {
	// Data is the base64-encoded audio data
	Data string `json:"data"`
	// Format specifies the audio format (e.g., "wav", "mp3")
	Format string `json:"format"`
}

InputAudio represents an audio input in the message content. Audio files must be base64-encoded - direct URLs are not supported.

type JSONSchema 

type JSONSchema struct {
	Name   string                 `json:"name"`
	Strict bool                   `json:"strict"`
	Schema map[string]interface{} `json:"schema"`
}

JSONSchema defines the structure for structured output format.

type KeyData 

type KeyData struct {
	Label             string        `json:"label"`
	Limit             *float64      `json:"limit"`
	Usage             float64       `json:"usage"`
	IsFreeTier        bool          `json:"is_free_tier"`
	LimitRemaining    *float64      `json:"limit_remaining"`
	IsProvisioningKey bool          `json:"is_provisioning_key"`
	RateLimit         *KeyRateLimit `json:"rate_limit,omitempty"`
}

KeyData contains information about an API key.

type KeyRateLimit 

type KeyRateLimit struct {
	Interval string  `json:"interval"`
	Requests float64 `json:"requests"`
}

KeyRateLimit contains rate limit information for an API key.

type KeyResponse 

type KeyResponse struct {
	Data KeyData `json:"data"`
}

KeyResponse represents the response from the get current API key endpoint.

type ListKeysOptions 

type ListKeysOptions struct {
	// Offset for pagination
	Offset *int `json:"offset,omitempty"`
	// IncludeDisabled controls whether to include disabled API keys
	IncludeDisabled *bool `json:"include_disabled,omitempty"`
}

ListKeysOptions contains optional parameters for listing API keys.

type ListKeysResponse 

type ListKeysResponse struct {
	Data []APIKey `json:"data"`
}

ListKeysResponse represents the response from the list API keys endpoint.

type ListModelsOptions 

type ListModelsOptions struct {
	// Category filters models by category (e.g. "programming"). Sorted from most to least used.
	Category string
}

ListModelsOptions contains optional parameters for listing models.

type LogProbContent 

type LogProbContent struct {
	Token       string       `json:"token"`
	LogProb     float64      `json:"logprob"`
	Bytes       []int        `json:"bytes,omitempty"`
	TopLogProbs []TopLogProb `json:"top_logprobs,omitempty"`
}

LogProbContent represents log probability content.

type LogProbs 

type LogProbs struct {
	Content []LogProbContent `json:"content,omitempty"`
}

LogProbs represents log probability information.

type MaxPrice 

type MaxPrice struct {
	// Prompt specifies max price per million prompt tokens
	Prompt float64 `json:"prompt,omitempty"`
	// Completion specifies max price per million completion tokens
	Completion float64 `json:"completion,omitempty"`
	// Request specifies max price per request (for providers with per-request pricing)
	Request float64 `json:"request,omitempty"`
	// Image specifies max price per image
	Image float64 `json:"image,omitempty"`
}

MaxPrice represents maximum pricing constraints for a request.

type Message 

type Message struct {
	Role        string         `json:"role"`
	Content     MessageContent `json:"content"`
	Name        string         `json:"name,omitempty"`
	ToolCalls   []ToolCall     `json:"tool_calls,omitempty"`
	ToolCallID  string         `json:"tool_call_id,omitempty"`
	Annotations []Annotation   `json:"annotations,omitempty"`
}

Message represents a message in the chat completion request.

func CreateAssistantMessage 

func CreateAssistantMessage(content string) Message

CreateAssistantMessage creates an assistant message.

func CreateChatMessage 

func CreateChatMessage(role string, content string) Message

CreateChatMessage is a helper function to create a chat message.

func CreateMultiModalMessage 

func CreateMultiModalMessage(role string, text string, imageURL string) Message

CreateMultiModalMessage creates a message with text and image content.

func CreateSystemMessage 

func CreateSystemMessage(content string) Message

CreateSystemMessage creates a system message.

func CreateToolMessage 

func CreateToolMessage(content string, toolCallID string) Message

CreateToolMessage creates a tool message.

func CreateUserMessage 

func CreateUserMessage(content string) Message

CreateUserMessage creates a user message.

func CreateUserMessageWithAudio added in v1.1.0 

func CreateUserMessageWithAudio(text string, audioData string, format string) Message

CreateUserMessageWithAudio creates a user message with text and an audio input. The audioData should be base64-encoded audio data. The format should be one of: "wav", "mp3"

func CreateUserMessageWithBase64Audio added in v1.1.0 

func CreateUserMessageWithBase64Audio(text string, audioPath string) (Message, error)

CreateUserMessageWithBase64Audio creates a user message with a base64-encoded audio file. This is a convenience function that combines EncodeAudioToBase64 and CreateUserMessageWithAudio.

func CreateUserMessageWithBase64Image added in v1.1.0 

func CreateUserMessageWithBase64Image(text string, imagePath string) (Message, error)

CreateUserMessageWithBase64Image creates a user message with a base64-encoded image. This is a convenience function that combines EncodeImageToBase64 and CreateUserMessageWithImage.

func CreateUserMessageWithBase64Images added in v1.1.0 

func CreateUserMessageWithBase64Images(text string, imagePaths ...string) (Message, error)

CreateUserMessageWithBase64Images creates a user message with multiple base64-encoded images. This is a convenience function that combines EncodeImageToBase64 and CreateUserMessageWithImages.

func CreateUserMessageWithBase64PDF added in v1.1.0 

func CreateUserMessageWithBase64PDF(text string, pdfPath string, filename string) (Message, error)

CreateUserMessageWithBase64PDF creates a user message with a base64-encoded PDF. This is a convenience function that combines EncodePDFToBase64 and CreateUserMessageWithPDF.

func CreateUserMessageWithFiles added in v1.1.0 

func CreateUserMessageWithFiles(text string, files []File) Message

CreateUserMessageWithFiles creates a user message with text and multiple files. Files can be PDFs, images, or other supported file types.

func CreateUserMessageWithImage added in v1.1.0 

func CreateUserMessageWithImage(text string, imageURL string) Message

CreateUserMessageWithImage creates a user message with text and a single image.

func CreateUserMessageWithImageDetail added in v1.1.0 

func CreateUserMessageWithImageDetail(text string, imageURL string, detail string) Message

CreateUserMessageWithImageDetail creates a user message with an image and detail level. The detail parameter can be "auto", "low", or "high". - "low" is faster and cheaper, suitable for understanding general content - "high" provides more detailed analysis at higher cost - "auto" lets the model decide based on image size (default)

func CreateUserMessageWithImages added in v1.1.0 

func CreateUserMessageWithImages(text string, imageURLs ...string) Message

CreateUserMessageWithImages creates a user message with text and multiple images.

func CreateUserMessageWithPDF added in v1.1.0 

func CreateUserMessageWithPDF(text string, pdfURL string, filename string) Message

CreateUserMessageWithPDF creates a user message with text and a PDF file. The pdfURL can be either a direct URL to a publicly accessible PDF or a base64-encoded data URL (use EncodePDFToBase64 to encode local files).

type MessageContent 

type MessageContent interface{}

MessageContent can be either a string or an array of content parts.

type Model 

type Model struct {
	ID                  string                  `json:"id"`
	Name                string                  `json:"name"`
	CanonicalSlug       *string                 `json:"canonical_slug"`
	Created             float64                 `json:"created"`
	Description         string                  `json:"description"`
	ContextLength       *float64                `json:"context_length"`
	HuggingFaceID       *string                 `json:"hugging_face_id"`
	Architecture        ModelArchitecture       `json:"architecture"`
	TopProvider         ModelTopProvider        `json:"top_provider"`
	PerRequestLimits    *ModelPerRequestLimits  `json:"per_request_limits"`
	SupportedParameters []string                `json:"supported_parameters,omitempty"`
	DefaultParameters   *ModelDefaultParameters `json:"default_parameters"`
	Pricing             ModelPricing            `json:"pricing"`
}

Model represents a model available on OpenRouter.

type ModelArchitecture 

type ModelArchitecture struct {
	InputModalities  []string `json:"input_modalities"`
	OutputModalities []string `json:"output_modalities"`
	Tokenizer        string   `json:"tokenizer"`
	InstructType     *string  `json:"instruct_type"`
}

ModelArchitecture contains information about a model's architecture.

type ModelDefaultParameters 

type ModelDefaultParameters struct {
	Temperature      *float64 `json:"temperature"`
	TopP             *float64 `json:"top_p"`
	FrequencyPenalty *float64 `json:"frequency_penalty"`
}

ModelDefaultParameters contains default generation parameters for a model.

type ModelEndpoint 

type ModelEndpoint struct {
	Name                string               `json:"name"`
	ContextLength       float64              `json:"context_length"`
	Pricing             ModelEndpointPricing `json:"pricing"`
	ProviderName        string               `json:"provider_name"`
	Quantization        *string              `json:"quantization"`
	MaxCompletionTokens *float64             `json:"max_completion_tokens"`
	MaxPromptTokens     *float64             `json:"max_prompt_tokens"`
	SupportedParameters []string             `json:"supported_parameters"`
	Status              float64              `json:"status"`
	UptimeLast30m       *float64             `json:"uptime_last_30m"`
}

ModelEndpoint represents a single endpoint for a model.

type ModelEndpointPricing 

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

ModelEndpointPricing contains pricing information for a specific endpoint.

type ModelEndpointsArchitecture 

type ModelEndpointsArchitecture struct {
	Tokenizer        *string  `json:"tokenizer"`
	InstructType     *string  `json:"instruct_type"`
	InputModalities  []string `json:"input_modalities"`
	OutputModalities []string `json:"output_modalities"`
}

ModelEndpointsArchitecture contains architecture information for a model's endpoints.

type ModelEndpointsData 

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

ModelEndpointsData contains details about a model and its endpoints.

type ModelEndpointsResponse 

type ModelEndpointsResponse struct {
	Data ModelEndpointsData `json:"data"`
}

ModelEndpointsResponse represents the response from the model endpoints endpoint.

type ModelPerRequestLimits 

type ModelPerRequestLimits struct {
}

ModelPerRequestLimits contains per-request limits for a model.

type ModelPricing 

type ModelPricing struct {
	Prompt            string  `json:"prompt"`
	Completion        string  `json:"completion"`
	Image             string  `json:"image"`
	Request           string  `json:"request"`
	InputCacheRead    *string `json:"input_cache_read"`
	InputCacheWrite   *string `json:"input_cache_write"`
	WebSearch         string  `json:"web_search"`
	InternalReasoning string  `json:"internal_reasoning"`
}

ModelPricing contains pricing information for a model.

type ModelTopProvider 

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

ModelTopProvider contains information about the top provider for a model.

type ModelsResponse 

type ModelsResponse struct {
	Data []Model `json:"data"`
}

ModelsResponse represents the response from the list models endpoint.

type PDFParserConfig added in v1.1.0 

type PDFParserConfig struct {
	// Engine specifies the PDF parsing engine to use.
	// Options:
	// - "pdf-text": Best for well-structured PDFs with clear text content (Free)
	// - "mistral-ocr": Best for scanned documents or PDFs with images ($0.0004 per 1,000 pages)
	// - "native": Only for models with native file support (charged as input tokens)
	// If not specified, defaults to model's native support, then "pdf-text"
	Engine string `json:"engine,omitempty"`
}

PDFParserConfig configures PDF file parsing behavior.

type Plugin 

type Plugin struct {
	// ID is the plugin identifier (e.g., "web" for web search, "file-parser" for file parsing)
	ID string `json:"id"`
	// Engine specifies which search engine to use ("native", "exa", or undefined for auto)
	Engine string `json:"engine,omitempty"`
	// MaxResults specifies the maximum number of search results (defaults to 5)
	MaxResults int `json:"max_results,omitempty"`
	// SearchPrompt customizes the prompt used to attach search results
	SearchPrompt string `json:"search_prompt,omitempty"`
	// PDF contains configuration for PDF file parsing (when ID is "file-parser")
	PDF *PDFParserConfig `json:"pdf,omitempty"`
}

Plugin represents a plugin configuration for enhancing model responses.

func CreateFileParserPlugin added in v1.1.0 

func CreateFileParserPlugin(engine string) Plugin

CreateFileParserPlugin creates a file parser plugin configuration. The engine parameter can be:

  • "pdf-text": Best for well-structured PDFs with clear text content (Free)
  • "mistral-ocr": Best for scanned documents or PDFs with images ($0.0004 per 1,000 pages)
  • "native": Only for models with native file support (charged as input tokens)
  • "" (empty): Defaults to model's native support, then "pdf-text"

func NewWebPlugin 

func NewWebPlugin() Plugin

NewWebPlugin creates a new web search plugin configuration. By default, uses automatic engine selection and 5 max results.

func NewWebPluginWithOptions 

func NewWebPluginWithOptions(engine WebSearchEngine, maxResults int, searchPrompt string) Plugin

NewWebPluginWithOptions creates a web search plugin with custom options.

type Provider 

type Provider struct {
	// Order specifies provider slugs to try in order (e.g. ["anthropic", "openai"])
	Order []string `json:"order,omitempty"`
	// RequireParameters only uses providers that support all parameters in the request
	RequireParameters *bool `json:"require_parameters,omitempty"`
	// DataCollection controls whether to use providers that may store data ("allow" or "deny")
	DataCollection string `json:"data_collection,omitempty"`
	// AllowFallbacks allows backup providers when the primary is unavailable
	AllowFallbacks *bool `json:"allow_fallbacks,omitempty"`
	// Ignore specifies provider slugs to skip for this request
	Ignore []string `json:"ignore,omitempty"`
	// Quantizations filters providers by quantization levels (e.g. ["int4", "int8"])
	Quantizations []string `json:"quantizations,omitempty"`
	// ZDR restricts routing to only Zero Data Retention endpoints
	ZDR *bool `json:"zdr,omitempty"`
	// Only specifies provider slugs to allow for this request
	Only []string `json:"only,omitempty"`
	// Sort providers by "price", "throughput", or "latency"
	Sort string `json:"sort,omitempty"`
	// MaxPrice specifies maximum pricing constraints for the request
	MaxPrice *MaxPrice `json:"max_price,omitempty"`

	// Deprecated: Use Ignore instead
	IgnoreProviders []string `json:"-"`
	// Deprecated: Use Quantizations instead
	QuantizationFallback map[string]string `json:"-"`
	// Internal provider parameters
	ProviderParams map[string]interface{} `json:"-"`
}

Provider represents provider-specific parameters for routing requests.

type ProviderInfo 

type ProviderInfo struct {
	Name              string  `json:"name"`
	Slug              string  `json:"slug"`
	PrivacyPolicyURL  *string `json:"privacy_policy_url"`
	TermsOfServiceURL *string `json:"terms_of_service_url"`
	StatusPageURL     *string `json:"status_page_url"`
}

ProviderInfo represents information about a provider available on OpenRouter.

type ProvidersResponse 

type ProvidersResponse struct {
	Data []ProviderInfo `json:"data"`
}

ProvidersResponse represents the response from the list providers endpoint.

type RateLimiter 

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

RateLimiter provides rate limiting functionality.

func NewRateLimiter 

func NewRateLimiter(requestsPerSecond float64, burst int) *RateLimiter

NewRateLimiter creates a new rate limiter.

func (*RateLimiter) Close 

func (rl *RateLimiter) Close()

Close stops the rate limiter.

func (*RateLimiter) Wait 

func (rl *RateLimiter) Wait(ctx context.Context) error

Wait blocks until a token is available or the context is cancelled.

type RequestConfig 

type RequestConfig interface {
	*ChatCompletionRequest | *CompletionRequest
}

RequestConfig is an interface that both ChatCompletionRequest and CompletionRequest satisfy. It provides access to common fields for generic option functions.

type RequestError 

type RequestError struct {
	StatusCode int
	Message    string
	Type       string
	Code       string
}

RequestError represents an error returned by the OpenRouter API.

func IsRequestError 

func IsRequestError(err error) (*RequestError, bool)

IsRequestError checks if an error is a RequestError and returns it.

func (*RequestError) Error 

func (e *RequestError) Error() string

Error implements the error interface.

func (*RequestError) IsAuthenticationError 

func (e *RequestError) IsAuthenticationError() bool

IsAuthenticationError returns true if the error is an authentication error.

func (*RequestError) IsNotFoundError 

func (e *RequestError) IsNotFoundError() bool

IsNotFoundError returns true if the error is a not found error.

func (*RequestError) IsPermissionError 

func (e *RequestError) IsPermissionError() bool

IsPermissionError returns true if the error is a permission error.

func (*RequestError) IsRateLimitError 

func (e *RequestError) IsRateLimitError() bool

IsRateLimitError returns true if the error is a rate limit error.

func (*RequestError) IsServerError 

func (e *RequestError) IsServerError() bool

IsServerError returns true if the error is a server error.

type RequestWithProvider 

type RequestWithProvider interface {
	*ChatCompletionRequest | *CompletionRequest
}

RequestWithProvider is a type constraint for requests that have provider settings. This constraint allows generic functions to work with both ChatCompletionRequest and CompletionRequest in a type-safe manner.

type ResponseFormat 

type ResponseFormat struct {
	Type       string      `json:"type"`
	JSONSchema *JSONSchema `json:"json_schema,omitempty"`
}

ResponseFormat specifies the format of the response.

type RetryConfig 

type RetryConfig struct {
	MaxRetries     int
	InitialDelay   time.Duration
	MaxDelay       time.Duration
	Multiplier     float64
	Jitter         bool
	RetryableError func(error) bool
}

RetryConfig configures retry behavior for API requests.

func DefaultRetryConfig 

func DefaultRetryConfig() *RetryConfig

DefaultRetryConfig returns the default retry configuration.

type Stream 

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

Stream represents a generic streaming response wrapper.

func (*Stream[T]) Close 

func (s *Stream[T]) Close() error

Close closes the stream.

func (*Stream[T]) Err 

func (s *Stream[T]) Err() error

Err returns any error that occurred during streaming.

func (*Stream[T]) Events 

func (s *Stream[T]) Events() <-chan T

Events returns a channel that receives streaming events.

type StreamError 

type StreamError struct {
	Err     error
	Message string
}

StreamError represents an error that occurs during streaming.

func IsStreamError 

func IsStreamError(err error) (*StreamError, bool)

IsStreamError checks if an error is a StreamError and returns it.

func (*StreamError) Error 

func (e *StreamError) Error() string

Error implements the error interface.

func (*StreamError) Unwrap 

func (e *StreamError) Unwrap() error

Unwrap returns the underlying error.

type StreamEvent 

type StreamEvent struct {
	ID    string
	Event string
	Data  string
	Retry *time.Duration
}

StreamEvent represents a server-sent event for streaming responses.

type Tool 

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

Tool represents a tool/function that can be called.

type ToolCall 

type ToolCall struct {
	ID       string       `json:"id"`
	Type     string       `json:"type"`
	Function FunctionCall `json:"function"`
}

ToolCall represents a tool call made by the model.

type TopLogProb 

type TopLogProb struct {
	Token   string  `json:"token"`
	LogProb float64 `json:"logprob"`
	Bytes   []int   `json:"bytes,omitempty"`
}

TopLogProb represents top log probability information.

type URLCitation 

type URLCitation struct {
	// URL of the cited source
	URL string `json:"url"`
	// Title of the web search result
	Title string `json:"title"`
	// Content of the web search result
	Content string `json:"content,omitempty"`
	// StartIndex is the index of the first character of the citation in the message
	StartIndex int `json:"start_index"`
	// EndIndex is the index of the last character of the citation in the message
	EndIndex int `json:"end_index"`
}

URLCitation represents a URL citation in a message annotation.

func ParseAnnotations 

func ParseAnnotations(annotations []Annotation) []URLCitation

ParseAnnotations extracts URL citations from message annotations.

type UpdateKeyRequest 

type UpdateKeyRequest struct {
	// Name is the new name/label for the API key
	Name *string `json:"name,omitempty"`
	// Disabled controls whether the API key is disabled
	Disabled *bool `json:"disabled,omitempty"`
	// Limit is the new credit limit for the API key
	Limit *float64 `json:"limit,omitempty"`
	// IncludeBYOKInLimit controls whether BYOK usage counts toward the limit
	IncludeBYOKInLimit *bool `json:"include_byok_in_limit,omitempty"`
}

UpdateKeyRequest represents a request to update an existing API key. All fields are optional - only include fields you want to update.

type UpdateKeyResponse 

type UpdateKeyResponse struct {
	Data APIKey `json:"data"`
}

UpdateKeyResponse represents the response from updating an API key.

type Usage 

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

Usage represents token usage information.

type ValidationError 

type ValidationError struct {
	Field   string
	Message string
}

ValidationError represents a validation error for request parameters.

func IsValidationError 

func IsValidationError(err error) (*ValidationError, bool)

IsValidationError checks if an error is a ValidationError and returns it.

func (*ValidationError) Error 

func (e *ValidationError) Error() string

Error implements the error interface.

type WebSearchContextSize 

type WebSearchContextSize string

WebSearchContextSize represents the amount of search context to retrieve. 

const (
	// WebSearchContextLow provides minimal search context
	WebSearchContextLow WebSearchContextSize = "low"
	// WebSearchContextMedium provides moderate search context
	WebSearchContextMedium WebSearchContextSize = "medium"
	// WebSearchContextHigh provides extensive search context
	WebSearchContextHigh WebSearchContextSize = "high"
)

type WebSearchEngine 

type WebSearchEngine string

WebSearchEngine represents the search engine options for the web plugin. 

const (
	// WebSearchEngineNative uses the model provider's built-in web search
	WebSearchEngineNative WebSearchEngine = "native"
	// WebSearchEngineExa uses Exa's search API for web results
	WebSearchEngineExa WebSearchEngine = "exa"
	// WebSearchEngineAuto automatically selects the best available engine
	WebSearchEngineAuto WebSearchEngine = ""
)

type WebSearchOptions 

type WebSearchOptions struct {
	// SearchContextSize determines the amount of search context ("low", "medium", or "high")
	SearchContextSize string `json:"search_context_size,omitempty"`
}

WebSearchOptions configures native web search behavior for supported models.

Source Files

View all Source files

Directories

Path Synopsis
cmd
openrouter-test command
openrouter-test/tests
openrouter-test/tools/test_local_audio command
openrouter-test/tools/test_local_image command
openrouter-test/tools/verify_image command
examples
activity command
advanced command
app-attribution command
audio-inputs command
basic command
create-key command
embeddings command
get-credits command
image-inputs command
key command
list-keys command
list-models command
list-providers command
model-endpoints command
pdf-inputs command
streaming command
structured-output command
tool-calling command
Package main demonstrates tool calling with the OpenRouter API.
 Package main demonstrates tool calling with the OpenRouter API.
transforms command
Package main demonstrates the use of message transforms in the OpenRouter Go client.
 Package main demonstrates the use of message transforms in the OpenRouter Go client.
web_search command
internal
sse
Package sse provides Server-Sent Events parsing functionality.
 Package sse provides Server-Sent Events parsing functionality.

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.