openrouter

README

openrouter-go

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
• ✅ MCP (Model Context Protocol) tool conversion utilities
• ✅ 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
• ⚠️ [BETA] Responses API with reasoning, tool calling, web search, and streaming

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
├── mcp.go               # MCP tool conversion utilities
├── responses.go         # [BETA] Responses API endpoint methods
├── responses_models.go  # [BETA] Responses API type definitions
├── responses_options.go # [BETA] Responses API functional options
├── examples/
│   ├── basic/             # Basic usage examples
│   ├── streaming/         # Streaming examples
│   ├── structured-output/ # Structured outputs with JSON schema
│   ├── tool-calling/      # Tool/function calling examples
│   ├── mcp-tools/         # MCP tool conversion 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
│   ├── responses/         # [BETA] Responses API 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.

Text File Inputs

Send text-based files (code, configuration, documentation) to models using inline content. Text files are sent directly as UTF-8 text, not base64-encoded, for efficiency and token optimization.

Single Text File

// Send a code file for review
message, err := openrouter.CreateUserMessageWithTextFile(
    "Review this code for bugs:",
    "/path/to/code.py",
)
if err != nil {
    log.Fatal(err)
}

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

Multiple Text Files

// Compare or analyze multiple files
message, err := openrouter.CreateUserMessageWithTextFiles(
    "Compare these configuration files and identify differences:",
    "/path/to/config1.yaml",
    "/path/to/config2.yaml",
)
if err != nil {
    log.Fatal(err)
}

response, err := client.ChatComplete(ctx, []openrouter.Message{message},
    openrouter.WithModel("openai/gpt-4"),
)

Content Builder with Text Files

// Build complex messages with multiple text files
builder := openrouter.NewContentBuilder()
builder.AddText("I have several files to review:")

builder, err := builder.AddTextFile("/path/to/main.go")
if err != nil {
    log.Fatal(err)
}

builder.AddText("And here's the test file:")
builder, err = builder.AddTextFile("/path/to/main_test.go")
if err != nil {
    log.Fatal(err)
}

builder.AddText("Do these files work together correctly?")

message := builder.BuildMessage("user")
response, err := client.ChatComplete(ctx, []openrouter.Message{message},
    openrouter.WithModel("anthropic/claude-sonnet-4"),
)

Direct Text Content (Without File I/O)

// Send text content directly without reading from a file
message := openrouter.CreateUserMessageWithTextContent(
    "Analyze this JSON structure:",
    `{
  "name": "example",
  "version": "1.0.0",
  "dependencies": {}
}`,
    "package.json",
)

response, err := client.ChatComplete(ctx, []openrouter.Message{message},
    openrouter.WithModel("openai/gpt-4o-mini"),
)

Supported File Formats

Common text formats

• .txt - Plain text
• .md - Markdown
• .json - JSON files
• .csv - CSV files

Code files

• .js, .jsx - JavaScript
• .ts, .tsx - TypeScript
• .py - Python
• .go - Go
• .java - Java
• .rs - Rust
• .c, .cpp, .h - C/C++
• .rb - Ruby
• .php - PHP
• .swift - Swift
• .kt - Kotlin

Configuration files

• .yaml, .yml - YAML
• .toml - TOML
• .xml - XML
• .ini - INI
• .env - Environment files

And many more! See text-file-inputs example for complete details.

Key Features

• Inline delivery - Text sent directly (not base64), optimizing tokens
• UTF-8 validation - All files must contain valid UTF-8 text
• Filename context - Files are sent with filename headers for context
• All models supported - Works with any text-capable model on OpenRouter
• Format validation - Unsupported formats rejected with clear errors
• Builder integration - Seamlessly mix text files with other content types

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

MCP Tool Conversion

The library provides utilities for converting MCP (Model Context Protocol) tool definitions to OpenRouter's OpenAI-compatible format. This enables seamless integration with MCP servers and clients.

Converting MCP Tools

// Define MCP tools (as received from an MCP server)
mcpTools := []openrouter.MCPTool{
    {
        Name:        "read_file",
        Description: "Read the contents of a file from the filesystem",
        InputSchema: &openrouter.MCPInputSchema{
            Type: "object",
            Properties: map[string]interface{}{
                "path": map[string]interface{}{
                    "type":        "string",
                    "description": "The path to the file to read",
                },
            },
            Required: []string{"path"},
        },
    },
}

// Convert to OpenRouter format
tools := openrouter.ConvertMCPTools(mcpTools)

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

Parsing MCP Tools from JSON

// Parse MCP tools from JSON (as received from an MCP server)
mcpToolsJSON := []byte(`[
    {
        "name": "get_weather",
        "description": "Get the current weather for a location",
        "inputSchema": {
            "type": "object",
            "properties": {
                "location": {"type": "string", "description": "City name"}
            },
            "required": ["location"]
        }
    }
]`)

mcpTools, err := openrouter.ParseMCPToolsFromJSON(mcpToolsJSON)
if err != nil {
    log.Fatal(err)
}

// Convert and use
tools := openrouter.ConvertMCPTools(mcpTools)

Handling MCP Tool Results

// Convert MCP tool result to string for tool response
mcpResult := openrouter.MCPToolResult{
    Content: []openrouter.MCPContent{
        {Type: "text", Text: "File contents: Hello, World!"},
    },
}

resultStr := openrouter.ConvertToolResultToMCP(mcpResult)

// Use in tool response message
messages = append(messages, openrouter.Message{
    Role:       "tool",
    Content:    resultStr,
    ToolCallID: toolCall.ID,
})

MCP Types

The library provides the following MCP types:

• MCPTool: Represents an MCP tool definition (name, description, inputSchema)
• MCPInputSchema: JSON Schema for tool parameters (type, properties, required)
• MCPToolResult: Result from tool execution (content array, isError)
• MCPContent: Content item in responses (type, text, data, mimeType)

Functions

• ConvertMCPTool(mcpTool MCPTool) Tool - Convert single MCP tool
• ConvertMCPTools(mcpTools []MCPTool) []Tool - Convert multiple tools
• ConvertToolResultToMCP(result MCPToolResult) string - Convert result to string
• ParseMCPToolFromJSON(data []byte) (MCPTool, error) - Parse single tool from JSON
• ParseMCPToolsFromJSON(data []byte) ([]MCPTool, error) - Parse multiple tools from JSON

See the mcp-tools example for complete usage examples.

Web Search

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

Responses API [BETA]

⚠️ WARNING: BETA API - EXPECT BREAKING CHANGES

The Responses API is in beta and may have breaking changes at any time. Do not rely on this API for production workloads. The API structure, parameters, and behavior may change without notice as OpenRouter continues to develop this feature.

For stable production use, consider using the Chat Completions API instead.

The library supports OpenRouter's new Responses API, which provides an OpenAI-compatible stateless API with enhanced capabilities including reasoning, tool calling, web search integration, and streaming.

Basic Usage

// Simple string input
resp, err := client.CreateResponse(ctx, "What is 2+2?",
    openrouter.WithResponsesModel("openai/gpt-4o-mini"),
    openrouter.WithResponsesMaxOutputTokens(100),
)
if err != nil {
    log.Fatal(err)
}
fmt.Println(resp.GetTextContent())

Structured Input

// Use structured input for multi-turn conversations
input := []openrouter.ResponsesInputItem{
    openrouter.CreateResponsesSystemMessage("You are a helpful assistant."),
    openrouter.CreateResponsesUserMessage("What is the capital of France?"),
}

resp, err := client.CreateResponse(ctx, input,
    openrouter.WithResponsesModel("openai/gpt-4o-mini"),
    openrouter.WithResponsesMaxOutputTokens(200),
)

Reasoning

// Enable reasoning for complex problems
resp, err := client.CreateResponse(ctx, "Solve this step by step: 15 * 17",
    openrouter.WithResponsesModel("openai/o4-mini"),
    openrouter.WithResponsesMaxOutputTokens(500),
    openrouter.WithResponsesReasoningEffort(openrouter.ReasoningEffortMedium),
)

// Check for reasoning summary
if summary := resp.GetReasoningSummary(); len(summary) > 0 {
    for i, step := range summary {
        fmt.Printf("%d. %s\n", i+1, step)
    }
}

Reasoning effort levels: ReasoningEffortMinimal, ReasoningEffortLow, ReasoningEffortMedium, ReasoningEffortHigh

Tool Calling

// Define tools using the flat ResponsesTool structure
// Note: Responses API uses a different tool format than Chat Completions API
weatherTool := openrouter.CreateResponsesTool(
    "get_weather",
    "Get weather for a location",
    map[string]any{
        "type": "object",
        "properties": map[string]any{
            "location": map[string]any{
                "type":        "string",
                "description": "The city and state, e.g. San Francisco, CA",
            },
        },
        "required": []string{"location"},
    },
)

resp, err := client.CreateResponse(ctx, "What's the weather in Tokyo?",
    openrouter.WithResponsesModel("openai/gpt-4o-mini"),
    openrouter.WithResponsesTools(weatherTool),
)

// Check for function calls
calls := resp.GetFunctionCalls()
if len(calls) > 0 {
    for _, call := range calls {
        fmt.Printf("Function: %s, Args: %s\n", call.Name, call.Arguments)
    }
}

Web Search

// Enable web search for real-time information
resp, err := client.CreateResponse(ctx, "What are the latest AI news?",
    openrouter.WithResponsesModel("openai/gpt-4o-mini"),
    openrouter.WithResponsesWebSearch(3), // Get up to 3 search results
)

// Check for citations
annotations := resp.GetAnnotations()
for _, ann := range annotations {
    if ann.Type == "url_citation" {
        fmt.Printf("Source: %s\n", ann.URL)
    }
}

Streaming

stream, err := client.CreateResponseStream(ctx, "Write a haiku about programming.",
    openrouter.WithResponsesModel("openai/gpt-4o-mini"),
    openrouter.WithResponsesMaxOutputTokens(100),
)
if err != nil {
    log.Fatal(err)
}
defer stream.Close()

var lastContent string
for event := range stream.Events() {
    content := event.GetTextContent()
    // Only print the new delta (GetTextContent returns cumulative content)
    if len(content) > len(lastContent) {
        fmt.Print(content[len(lastContent):])
        lastContent = content
    }
}

if err := stream.Err(); err != nil {
    log.Fatal(err)
}

Key Differences from Chat API

Feature	Chat Completions	Responses API
Endpoint	/chat/completions	/responses
Input	Array of messages	String or structured array
Response	choices array	output array with typed items
Reasoning	Not available	Configurable effort levels
Web Search	Via :online suffix	Via plugins parameter

See the responses example for complete usage examples.

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
• responses/ - [BETA] Responses API examples with reasoning, tools, and streaming
• 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

# Run responses API examples [BETA]
go run examples/responses/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.

Package openrouter provides Go bindings for the OpenRouter API.

Package openrouter provides Go bindings for the OpenRouter API.

Package openrouter provides Go bindings for the OpenRouter API.

Index

• Constants
• Variables
• func AverageEmbeddings(embeddings [][]float64) []float64
• func ChunkTexts(texts []string, config ChunkConfig) ([][]TextChunk, error)
• func ConcatenateChatStreamResponses(responses []ChatCompletionResponse) string
• func ConcatenateCompletionStreamResponses(responses []CompletionResponse) string
• func ConvertToolResultToMCP(result MCPToolResult) string
• func CosineSimilarity(a, b []float64) float64
• func DefaultWebSearchPrompt(date string) string
• func EncodeAudioBytesToBase64(audioData []byte, format string) (string, error)
• func EncodeAudioToBase64(audioPath string) (string, string, error)
• func EncodeImageBytesToBase64(imageData []byte, contentType string) string
• func EncodeImageToBase64(imagePath string) (string, error)
• func EncodePDFBytesToBase64(pdfData []byte) string
• func EncodePDFToBase64(pdfPath string) (string, error)
• func EstimateTokens(text string) int
• func EstimateTokensFromWords(text string) int
• func ReadTextFile(filePath string) (string, error)
• func ReadTextFileWithFilename(filePath string) (content string, filename string, err error)
• func RetryWithBackoff(ctx context.Context, config *RetryConfig, fn func() error) error
• func ValidateTextContent(content string) error
• func WeightedAverageEmbeddings(embeddings [][]float64, weights []float64) []float64
• func WithOnlineModel(model string) string
• type APIError
• type APIKey
• type ActivityData
• type ActivityOptions
• type ActivityResponse
• type Annotation
• type ChatCompletionOption
  • func WithAllowFallbacks(allow bool) ChatCompletionOption
  • func WithDataCollection(policy string) ChatCompletionOption
  • func WithFloorPrice() ChatCompletionOption
  • func WithFrequencyPenalty(penalty float64) ChatCompletionOption
  • func WithIgnoreProviders(providers ...string) ChatCompletionOption
  • func WithJSONMode() ChatCompletionOption
  • func WithJSONSchema(name string, strict bool, schema map[string]interface{}) ChatCompletionOption
  • func WithLogProbs(topLogProbs int) ChatCompletionOption
  • func WithMaxPrice(maxPrice MaxPrice) ChatCompletionOption
  • func WithMaxTokens(maxTokens int) ChatCompletionOption
  • func WithMessages(messages []Message) ChatCompletionOption
  • func WithMetadata(metadata map[string]interface{}) ChatCompletionOption
  • func WithModel(model string) ChatCompletionOption
  • func WithModels(models ...string) ChatCompletionOption
  • func WithNitro() ChatCompletionOption
  • func WithOnlyProviders(providers ...string) ChatCompletionOption
  • func WithParallelToolCalls(parallel *bool) ChatCompletionOption
  • func WithPlugins(plugins ...Plugin) ChatCompletionOption
  • func WithPresencePenalty(penalty float64) ChatCompletionOption
  • func WithProvider(provider Provider) ChatCompletionOption
  • func WithProviderOrder(providers ...string) ChatCompletionOption
  • func WithProviderSort(sort string) ChatCompletionOption
  • func WithQuantizations(quantizations ...string) ChatCompletionOption
  • func WithRepetitionPenalty(penalty float64) ChatCompletionOption
  • func WithRequireParameters(require bool) ChatCompletionOption
  • func WithResponseFormat(format ResponseFormat) ChatCompletionOption
  • func WithRoute(route string) ChatCompletionOption
  • func WithSeed(seed int) ChatCompletionOption
  • func WithStop(stop ...string) ChatCompletionOption
  • func WithTemperature(temperature float64) ChatCompletionOption
  • func WithToolChoice(toolChoice interface{}) ChatCompletionOption
  • func WithTools(tools ...Tool) ChatCompletionOption
  • func WithTopK(topK int) ChatCompletionOption
  • func WithTopP(topP float64) ChatCompletionOption
  • func WithTransforms(transforms ...string) ChatCompletionOption
  • func WithUser(user string) ChatCompletionOption
  • func WithWebSearchOptions(options *WebSearchOptions) ChatCompletionOption
  • func WithZDR(enabled bool) ChatCompletionOption
• type ChatCompletionRequest
  • func (r *ChatCompletionRequest) GetMetadata() map[string]interface{}
• type ChatCompletionResponse
• type ChatStream
• type Choice
• type ChunkConfig
  • func DefaultChunkConfig() ChunkConfig
• type ChunkEmbedding
• type ChunkStrategy
• type ChunkedEmbeddingResult
• type Client
  • func NewClient(opts ...ClientOption) *Client
  • func (c *Client) ChatComplete(ctx context.Context, messages []Message, opts ...ChatCompletionOption) (*ChatCompletionResponse, error)
  • func (c *Client) ChatCompleteStream(ctx context.Context, messages []Message, opts ...ChatCompletionOption) (*ChatStream, error)
  • func (c *Client) Complete(ctx context.Context, prompt string, opts ...CompletionOption) (*CompletionResponse, error)
  • func (c *Client) CompleteStream(ctx context.Context, prompt string, opts ...CompletionOption) (*CompletionStream, error)
  • func (c *Client) CompleteWithContext(ctx context.Context, contextPrompt, userPrompt string, ...) (*CompletionResponse, error)
  • func (c *Client) CompleteWithExamples(ctx context.Context, instruction string, examples []string, prompt string, ...) (*CompletionResponse, error)
  • func (c *Client) CreateChunkedEmbedding(ctx context.Context, text string, model string, config ChunkConfig, ...) (*ChunkedEmbeddingResult, error)
  • func (c *Client) CreateChunkedEmbeddings(ctx context.Context, texts []string, model string, config ChunkConfig, ...) ([]*ChunkedEmbeddingResult, error)
  • func (c *Client) CreateEmbedding(ctx context.Context, input interface{}, model string, opts ...EmbeddingOption) (*EmbeddingResponse, error)
  • func (c *Client) CreateEmbeddings(ctx context.Context, inputs []string, model string, opts ...EmbeddingOption) (*EmbeddingResponse, error)
  • func (c *Client) CreateKey(ctx context.Context, request *CreateKeyRequest) (*CreateKeyResponse, error)
  • func (c *Client) CreateResponse(ctx context.Context, input interface{}, opts ...ResponsesOption) (*ResponsesResponse, error)
  • func (c *Client) CreateResponseStream(ctx context.Context, input interface{}, opts ...ResponsesOption) (*ResponsesStream, error)
  • func (c *Client) DeleteKey(ctx context.Context, hash string) (*DeleteKeyResponse, error)
  • func (c *Client) GetActivity(ctx context.Context, opts *ActivityOptions) (*ActivityResponse, error)
  • func (c *Client) GetCredits(ctx context.Context) (*CreditsResponse, error)
  • func (c *Client) GetKey(ctx context.Context) (*KeyResponse, error)
  • func (c *Client) GetKeyByHash(ctx context.Context, hash string) (*GetKeyByHashResponse, error)
  • func (c *Client) ListEmbeddingsModels(ctx context.Context) (*EmbeddingsModelsResponse, error)
  • func (c *Client) ListKeys(ctx context.Context, options *ListKeysOptions) (*ListKeysResponse, error)
  • func (c *Client) ListModelEndpoints(ctx context.Context, author, slug string) (*ModelEndpointsResponse, error)
  • func (c *Client) ListModels(ctx context.Context, opts *ListModelsOptions) (*ModelsResponse, error)
  • func (c *Client) ListProviders(ctx context.Context) (*ProvidersResponse, error)
  • func (c *Client) UpdateKey(ctx context.Context, hash string, request *UpdateKeyRequest) (*UpdateKeyResponse, error)
• type ClientOption
  • func WithAPIKey(apiKey string) ClientOption
  • func WithAppName(appName string) ClientOption
  • func WithBaseURL(baseURL string) ClientOption
  • func WithDefaultModel(model string) ClientOption
  • func WithHTTPClient(httpClient *http.Client) ClientOption
  • func WithHeader(key, value string) ClientOption
  • func WithReferer(referer string) ClientOption
  • func WithRetry(maxRetries int, retryDelay time.Duration) ClientOption
  • func WithTimeout(timeout time.Duration) ClientOption
• type CompletionChoice
• type CompletionOption
  • func WithCompletionAllowFallbacks(allow bool) CompletionOption
  • func WithCompletionBestOf(bestOf int) CompletionOption
  • func WithCompletionDataCollection(policy string) CompletionOption
  • func WithCompletionEcho(echo bool) CompletionOption
  • func WithCompletionFloorPrice() CompletionOption
  • func WithCompletionIgnoreProviders(providers ...string) CompletionOption
  • func WithCompletionJSONMode() CompletionOption
  • func WithCompletionJSONSchema(name string, strict bool, schema map[string]interface{}) CompletionOption
  • func WithCompletionLogProbs(logProbs int) CompletionOption
  • func WithCompletionMaxPrice(maxPrice MaxPrice) CompletionOption
  • func WithCompletionMaxTokens(maxTokens int) CompletionOption
  • func WithCompletionMetadata(metadata map[string]interface{}) CompletionOption
  • func WithCompletionModel(model string) CompletionOption
  • func WithCompletionModels(models ...string) CompletionOption
  • func WithCompletionN(n int) CompletionOption
  • func WithCompletionNitro() CompletionOption
  • func WithCompletionOnlyProviders(providers ...string) CompletionOption
  • func WithCompletionPlugins(plugins ...Plugin) CompletionOption
  • func WithCompletionProvider(provider Provider) CompletionOption
  • func WithCompletionProviderOrder(providers ...string) CompletionOption
  • func WithCompletionProviderSort(sort string) CompletionOption
  • func WithCompletionQuantizations(quantizations ...string) CompletionOption
  • func WithCompletionRequireParameters(require bool) CompletionOption
  • func WithCompletionResponseFormat(format ResponseFormat) CompletionOption
  • func WithCompletionRoute(route string) CompletionOption
  • func WithCompletionStop(stop ...string) CompletionOption
  • func WithCompletionSuffix(suffix string) CompletionOption
  • func WithCompletionTemperature(temperature float64) CompletionOption
  • func WithCompletionTopP(topP float64) CompletionOption
  • func WithCompletionTransforms(transforms ...string) CompletionOption
  • func WithCompletionUser(user string) CompletionOption
  • func WithCompletionWebSearchOptions(options *WebSearchOptions) CompletionOption
  • func WithCompletionZDR(enabled bool) CompletionOption
• type CompletionRequest
  • func (r *CompletionRequest) GetMetadata() map[string]interface{}
• type CompletionResponse
• type CompletionStream
• type ContentBuilder
  • func NewContentBuilder() *ContentBuilder
  • func (cb *ContentBuilder) AddAudio(audioData string, format string) *ContentBuilder
  • func (cb *ContentBuilder) AddBase64Audio(audioPath string) (*ContentBuilder, error)
  • func (cb *ContentBuilder) AddBase64PDF(pdfPath string, filename string) (*ContentBuilder, error)
  • func (cb *ContentBuilder) AddFile(filename string, fileData string) *ContentBuilder
  • func (cb *ContentBuilder) AddImage(imageURL string) *ContentBuilder
  • func (cb *ContentBuilder) AddImageWithDetail(imageURL string, detail string) *ContentBuilder
  • func (cb *ContentBuilder) AddPDF(pdfURL string, filename string) *ContentBuilder
  • func (cb *ContentBuilder) AddText(text string) *ContentBuilder
  • func (cb *ContentBuilder) AddTextContent(content string, label string) *ContentBuilder
  • func (cb *ContentBuilder) AddTextFile(filePath string) (*ContentBuilder, error)
  • func (cb *ContentBuilder) AddTextFileWithLabel(filePath string, label string) (*ContentBuilder, error)
  • func (cb *ContentBuilder) Build() []ContentPart
  • func (cb *ContentBuilder) BuildMessage(role string) Message
• type ContentPart
• type CreateKeyRequest
• type CreateKeyResponse
• type CreditsData
• type CreditsResponse
• type DeleteKeyData
• type DeleteKeyResponse
• type EmbeddingContentPart
• type EmbeddingData
  • func (e *EmbeddingData) GetEmbeddingBase64() string
  • func (e *EmbeddingData) GetEmbeddingVector() []float64
• type EmbeddingImageURL
• type EmbeddingMultimodalInput
• type EmbeddingOption
  • func WithEmbeddingAllowFallbacks(allow bool) EmbeddingOption
  • func WithEmbeddingDataCollection(policy string) EmbeddingOption
  • func WithEmbeddingDimensions(dimensions int) EmbeddingOption
  • func WithEmbeddingEncodingFormat(format string) EmbeddingOption
  • func WithEmbeddingIgnoreProviders(providers ...string) EmbeddingOption
  • func WithEmbeddingInputType(inputType string) EmbeddingOption
  • func WithEmbeddingOnlyProviders(providers ...string) EmbeddingOption
  • func WithEmbeddingProvider(provider Provider) EmbeddingOption
  • func WithEmbeddingProviderOrder(providers ...string) EmbeddingOption
  • func WithEmbeddingProviderSort(sort string) EmbeddingOption
  • func WithEmbeddingUser(user string) EmbeddingOption
• type EmbeddingRequest
• type EmbeddingResponse
• type EmbeddingUsage
• type EmbeddingsModelsResponse
• type ErrorResponse
• type File
• type FileAnnotation
• type Function
• type FunctionCall
• type GetKeyByHashResponse
• type ImageURL
• type InputAudio
• type JSONSchema
• type KeyData
• type KeyRateLimit
• type KeyResponse
• type ListKeysOptions
• type ListKeysResponse
• type ListModelsOptions
• type LogProbContent
• type LogProbs
• type MCPContent
• type MCPInputSchema
• type MCPTool
  • func ParseMCPToolFromJSON(data []byte) (MCPTool, error)
  • func ParseMCPToolsFromJSON(data []byte) ([]MCPTool, error)
• type MCPToolResult
• type MaxPrice
• type Message
  • func CreateAssistantMessage(content string) Message
  • func CreateChatMessage(role string, content string) Message
  • func CreateMultiModalMessage(role string, text string, imageURL string) Message
  • func CreateSystemMessage(content string) Message
  • func CreateToolMessage(content string, toolCallID string) Message
  • func CreateUserMessage(content string) Message
  • func CreateUserMessageWithAudio(text string, audioData string, format string) Message
  • func CreateUserMessageWithBase64Audio(text string, audioPath string) (Message, error)
  • func CreateUserMessageWithBase64Image(text string, imagePath string) (Message, error)
  • func CreateUserMessageWithBase64Images(text string, imagePaths ...string) (Message, error)
  • func CreateUserMessageWithBase64PDF(text string, pdfPath string, filename string) (Message, error)
  • func CreateUserMessageWithFiles(text string, files []File) Message
  • func CreateUserMessageWithImage(text string, imageURL string) Message
  • func CreateUserMessageWithImageDetail(text string, imageURL string, detail string) Message
  • func CreateUserMessageWithImages(text string, imageURLs ...string) Message
  • func CreateUserMessageWithPDF(text string, pdfURL string, filename string) Message
  • func CreateUserMessageWithTextContent(text string, content string, filename string) Message
  • func CreateUserMessageWithTextFile(text string, filePath string) (Message, error)
  • func CreateUserMessageWithTextFiles(text string, filePaths ...string) (Message, error)
• type MessageContent
• type Model
• type ModelArchitecture
• type ModelDefaultParameters
• type ModelEndpoint
• type ModelEndpointPricing
• type ModelEndpointsArchitecture
• type ModelEndpointsData
• type ModelEndpointsResponse
• type ModelPerRequestLimits
• type ModelPricing
• type ModelTopProvider
• type ModelsResponse
• type PDFParserConfig
• type Plugin
  • func CreateFileParserPlugin(engine string) Plugin
  • func NewWebPlugin() Plugin
  • func NewWebPluginWithOptions(engine WebSearchEngine, maxResults int, searchPrompt string) Plugin
• type Provider
• type ProviderInfo
• type ProvidersResponse
• type RateLimiter
  • func NewRateLimiter(requestsPerSecond float64, burst int) *RateLimiter
  • func (rl *RateLimiter) Close()
  • func (rl *RateLimiter) Wait(ctx context.Context) error
• type RequestConfig
• type RequestError
  • func IsRequestError(err error) (*RequestError, bool)
  • func (e *RequestError) Error() string
  • func (e *RequestError) IsAuthenticationError() bool
  • func (e *RequestError) IsNotFoundError() bool
  • func (e *RequestError) IsPermissionError() bool
  • func (e *RequestError) IsRateLimitError() bool
  • func (e *RequestError) IsServerError() bool
• type RequestOption
• type RequestWithProvider
• type ResponseFormat
• type ResponsesAnnotation
• type ResponsesInputContent
• type ResponsesInputItem
  • func CreateResponsesAssistantMessage(text string) ResponsesInputItem
  • func CreateResponsesFunctionOutput(callID, output string) ResponsesInputItem
  • func CreateResponsesMessage(role, text string) ResponsesInputItem
  • func CreateResponsesSystemMessage(text string) ResponsesInputItem
  • func CreateResponsesUserMessage(text string) ResponsesInputItem
• type ResponsesOption
  • func WithResponsesInput(input any) ResponsesOption
  • func WithResponsesMaxOutputTokens(tokens int) ResponsesOption
  • func WithResponsesMetadata(metadata map[string]interface{}) ResponsesOption
  • func WithResponsesModel(model string) ResponsesOption
  • func WithResponsesPlugins(plugins ...Plugin) ResponsesOption
  • func WithResponsesReasoning(ptr *ResponsesReasoning) ResponsesOption
  • func WithResponsesReasoningEffort(effort string) ResponsesOption
  • func WithResponsesTemperature(temperature float64) ResponsesOption
  • func WithResponsesToolChoice(toolChoice any) ResponsesOption
  • func WithResponsesTools(tools ...ResponsesTool) ResponsesOption
  • func WithResponsesTopP(topP float64) ResponsesOption
  • func WithResponsesWebSearch(maxResults int) ResponsesOption
• type ResponsesOutput
• type ResponsesOutputContent
• type ResponsesReasoning
• type ResponsesRequest
  • func (r *ResponsesRequest) GetMetadata() map[string]interface{}
• type ResponsesResponse
  • func (r *ResponsesResponse) GetAnnotations() []ResponsesAnnotation
  • func (r *ResponsesResponse) GetFunctionCalls() []ResponsesOutput
  • func (r *ResponsesResponse) GetReasoningSummary() []string
  • func (r *ResponsesResponse) GetTextContent() string
• type ResponsesStream
• type ResponsesTool
  • func ConvertToolToResponsesTool(tool Tool) ResponsesTool
  • func ConvertToolsToResponsesTools(tools []Tool) []ResponsesTool
  • func CreateResponsesTool(name, description string, parameters map[string]any) ResponsesTool
• type ResponsesUsage
• type RetryConfig
  • func DefaultRetryConfig() *RetryConfig
• type Stream
  • func (s *Stream[T]) Close() error
  • func (s *Stream[T]) Err() error
  • func (s *Stream[T]) Events() <-chan T
• type StreamError
  • func IsStreamError(err error) (*StreamError, bool)
  • func (e *StreamError) Error() string
  • func (e *StreamError) Unwrap() error
• type StreamEvent
• type TextChunk
  • func ChunkText(text string, config ChunkConfig) ([]TextChunk, error)
• type Tool
  • func ConvertMCPTool(mcpTool MCPTool) Tool
  • func ConvertMCPTools(mcpTools []MCPTool) []Tool
• type ToolCall
• type TopLogProb
• type URLCitation
  • func ParseAnnotations(annotations []Annotation) []URLCitation
• type UpdateKeyRequest
• type UpdateKeyResponse
• type Usage
• type ValidationError
  • func IsValidationError(err error) (*ValidationError, bool)
  • func (e *ValidationError) Error() string
• type WebSearchContextSize
• type WebSearchEngine
• type WebSearchOptions

Constants

const (
	// ReasoningEffortMinimal indicates minimal reasoning effort for simple queries.
	ReasoningEffortMinimal = "minimal"
	// ReasoningEffortLow indicates low reasoning effort for straightforward tasks.
	ReasoningEffortLow = "low"
	// ReasoningEffortMedium indicates medium reasoning effort for moderate complexity.
	ReasoningEffortMedium = "medium"
	// ReasoningEffortHigh indicates high reasoning effort for complex problems.
	ReasoningEffortHigh = "high"
)

Reasoning effort level constants for the Responses API.

Variables

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

ErrNoAPIKey is returned when no API key is provided.

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

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

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

ErrNoModel is returned when no model is specified.

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

ErrNoPrompt is returned when no prompt is provided for completion.

var (
	// ErrNoResponsesInput is returned when no input is provided.
	ErrNoResponsesInput = &ValidationError{
		Field:   "input",
		Message: "input is required",
	}
)

Predefined validation errors for Responses API.

Functions

func AverageEmbeddings

func AverageEmbeddings(embeddings [][]float64) []float64

AverageEmbeddings computes the element-wise average of multiple embeddings. Useful for combining chunk embeddings into a single document embedding.

func ChunkTexts

func ChunkTexts(texts []string, config ChunkConfig) ([][]TextChunk, error)

ChunkTexts splits multiple texts into chunks.

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 ConvertToolResultToMCP

func ConvertToolResultToMCP(result MCPToolResult) string

ConvertToolResultToMCP converts an MCP tool result to a string suitable for use as tool response content in chat completions.

func CosineSimilarity

func CosineSimilarity(a, b []float64) float64

CosineSimilarity computes the cosine similarity between two embedding vectors. Returns a value between -1 and 1, where 1 means identical direction.

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

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

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

func EncodeAudioToBase64

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

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

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

func EncodePDFBytesToBase64(pdfData []byte) string

EncodePDFBytesToBase64 encodes PDF bytes to a base64 data URL.

func EncodePDFToBase64

func EncodePDFToBase64(pdfPath string) (string, error)

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

func EstimateTokens

func EstimateTokens(text string) int

EstimateTokens estimates the token count for text using character-based heuristics. Uses approximately 4 characters per token for English text.

func EstimateTokensFromWords

func EstimateTokensFromWords(text string) int

EstimateTokensFromWords estimates token count based on word count. Uses approximately 1.3 tokens per word for English text.

func ReadTextFile

func ReadTextFile(filePath string) (string, error)

ReadTextFile reads a text file and returns its content as a string. It validates that the file contains valid UTF-8 text. Supported formats: .txt, .md, .json, .csv, .js, .py, .go, .java, .rs, .ts, .jsx, .tsx, .cpp, .c, .h, .rb, .php, .swift, .kt, .yaml, .yml, .toml, .xml, .ini

func ReadTextFileWithFilename

func ReadTextFileWithFilename(filePath string) (content string, filename string, err error)

ReadTextFileWithFilename reads a text file and returns both the content and filename. This is useful when you want to include the filename in your message.

func RetryWithBackoff

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

RetryWithBackoff executes a function with exponential backoff retry logic.

func ValidateTextContent

func ValidateTextContent(content string) error

ValidateTextContent validates that the given content is valid UTF-8 text.

func WeightedAverageEmbeddings

func WeightedAverageEmbeddings(embeddings [][]float64, weights []float64) []float64

WeightedAverageEmbeddings computes a weighted average of embeddings. weights should have the same length as embeddings.

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 WithUser

func WithUser(user string) ChatCompletionOption

WithUser sets a unique identifier for the end-user. This helps OpenRouter track users for analytics, improve caching by making it sticky to individual users, and provides user-level reporting in the activity feed.

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"`
	User              string                 `json:"user,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 ChunkConfig

type ChunkConfig struct {
	// Strategy determines how text is split.
	Strategy ChunkStrategy

	// ChunkSize is the target size per chunk.
	// For semantic strategies: target token count (units are merged to reach this).
	// For size-based strategies: exact limit (tokens or characters).
	ChunkSize int

	// Overlap specifies units to overlap between chunks for context preservation.
	// For semantic strategies: number of units (sentences/paragraphs) to repeat.
	// For size-based strategies: number of tokens/characters to overlap.
	Overlap int

	// TrimWhitespace removes leading/trailing whitespace from chunks.
	TrimWhitespace bool

	// PreserveWords prevents splitting mid-word (for tokens/characters strategies).
	PreserveWords bool

	// SectionHeaders defines custom section delimiters for sections strategy.
	// Default: ["#", "##", "###", "####", "#####", "######"] for markdown.
	SectionHeaders []string
}

ChunkConfig configures text chunking behavior.

func DefaultChunkConfig

func DefaultChunkConfig() ChunkConfig

DefaultChunkConfig returns a sensible default configuration.

type ChunkEmbedding

type ChunkEmbedding struct {
	// Chunk is the original text chunk with metadata.
	Chunk TextChunk

	// Embedding is the vector representation.
	Embedding []float64
}

ChunkEmbedding contains the embedding for a single chunk.

type ChunkStrategy

type ChunkStrategy string

ChunkStrategy defines the strategy for chunking text. Strategies are ordered by semantic quality, with semantic strategies (sections, paragraphs, sentences) preferred over size-based strategies (tokens, characters).

const (

	// ChunkBySections splits at markdown headers or document structure.
	// Best for structured documents with clear sections.
	ChunkBySections ChunkStrategy = "sections"

	// ChunkByParagraphs splits at paragraph boundaries (double newlines).
	// Good for prose and articles.
	ChunkByParagraphs ChunkStrategy = "paragraphs"

	// ChunkBySentences splits at sentence boundaries.
	// Fine-grained semantic chunking.
	ChunkBySentences ChunkStrategy = "sentences"

	// ChunkByTokens splits by estimated token count.
	ChunkByTokens ChunkStrategy = "tokens"

	// ChunkByCharacters splits by character count.
	ChunkByCharacters ChunkStrategy = "characters"
)

type ChunkedEmbeddingResult

type ChunkedEmbeddingResult struct {
	// Chunks contains the embedding for each chunk.
	Chunks []ChunkEmbedding

	// TotalTokensUsed is the sum of tokens used across all chunk embeddings.
	TotalTokensUsed int

	// Model is the embedding model used.
	Model string
}

ChunkedEmbeddingResult contains embeddings for all chunks of a document.

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) CreateChunkedEmbedding

func (c *Client) CreateChunkedEmbedding(ctx context.Context, text string, model string, config ChunkConfig, opts ...EmbeddingOption) (*ChunkedEmbeddingResult, error)

CreateChunkedEmbedding creates embeddings for a long text by chunking it first.

func (*Client) CreateChunkedEmbeddings

func (c *Client) CreateChunkedEmbeddings(ctx context.Context, texts []string, model string, config ChunkConfig, opts ...EmbeddingOption) ([]*ChunkedEmbeddingResult, error)

CreateChunkedEmbeddings creates embeddings for multiple long texts by chunking each.

func (*Client) CreateEmbedding

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

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) CreateResponse

func (c *Client) CreateResponse(ctx context.Context, input interface{}, opts ...ResponsesOption) (*ResponsesResponse, error)

CreateResponse sends a request to the OpenRouter Responses API (beta). The input can be a simple string or a structured array of ResponsesInputItem.

Note: This API is in beta and may have breaking changes. Use with caution in production.

Example with simple string input:

resp, err := client.CreateResponse(ctx, "Hello, world!",
    openrouter.WithResponsesModel("openai/o4-mini"),
    openrouter.WithResponsesMaxOutputTokens(100),
)

Example with structured input:

input := []openrouter.ResponsesInputItem{
    openrouter.CreateResponsesUserMessage("Hello!"),
}
resp, err := client.CreateResponse(ctx, input,
    openrouter.WithResponsesModel("openai/o4-mini"),
)

func (*Client) CreateResponseStream

func (c *Client) CreateResponseStream(ctx context.Context, input interface{}, opts ...ResponsesOption) (*ResponsesStream, error)

CreateResponseStream sends a streaming request to the OpenRouter Responses API (beta). Returns a stream that can be used to receive response events as they arrive.

Note: This API is in beta and may have breaking changes. Use with caution in production.

Example:

stream, err := client.CreateResponseStream(ctx, "Tell me a story",
    openrouter.WithResponsesModel("openai/o4-mini"),
)
if err != nil {
    log.Fatal(err)
}
defer stream.Close()

for event := range stream.Events() {
    // Process streaming event
    fmt.Print(event.GetTextContent())
}

if err := stream.Err(); err != nil {
    log.Printf("Stream error: %v", err)
}

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

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 WithCompletionUser

func WithCompletionUser(user string) CompletionOption

WithCompletionUser sets a unique identifier for the end-user in completion requests. This helps OpenRouter track users for analytics, improve caching by making it sticky to individual users, and provides user-level reporting in the activity feed.

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"`
	User              string                 `json:"user,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

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

CreateContentParts is a helper to build custom content part arrays.

func NewContentBuilder

func NewContentBuilder() *ContentBuilder

NewContentBuilder creates a new content builder.

func (*ContentBuilder) AddAudio

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

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

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

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

AddFile adds a file to the content builder.

func (*ContentBuilder) AddImage

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

AddImage adds an image content part.

func (*ContentBuilder) AddImageWithDetail

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

AddImageWithDetail adds an image content part with a detail level.

func (*ContentBuilder) AddPDF

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

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

AddText adds a text content part.

func (*ContentBuilder) AddTextContent

func (cb *ContentBuilder) AddTextContent(content string, label string) *ContentBuilder

AddTextContent adds raw text content with an optional label.

func (*ContentBuilder) AddTextFile

func (cb *ContentBuilder) AddTextFile(filePath string) (*ContentBuilder, error)

AddTextFile reads a text file and adds its content to the message. The content is formatted with a filename header for context.

func (*ContentBuilder) AddTextFileWithLabel

func (cb *ContentBuilder) AddTextFileWithLabel(filePath string, label string) (*ContentBuilder, error)

AddTextFileWithLabel reads a text file and adds its content with a custom label.

func (*ContentBuilder) Build

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

Build returns the content parts array.

func (*ContentBuilder) BuildMessage

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

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

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

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

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

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

EmbeddingImageURL represents an image URL for multimodal embedding input.

type EmbeddingMultimodalInput

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

EmbeddingMultimodalInput represents multimodal input for embeddings.

type EmbeddingOption

type EmbeddingOption func(*EmbeddingRequest)

EmbeddingOption is a functional option for embedding requests.

func WithEmbeddingAllowFallbacks

func WithEmbeddingAllowFallbacks(allow bool) EmbeddingOption

WithEmbeddingAllowFallbacks controls whether to allow backup providers.

func WithEmbeddingDataCollection

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

func WithEmbeddingDimensions(dimensions int) EmbeddingOption

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

func WithEmbeddingEncodingFormat

func WithEmbeddingEncodingFormat(format string) EmbeddingOption

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

func WithEmbeddingIgnoreProviders

func WithEmbeddingIgnoreProviders(providers ...string) EmbeddingOption

WithEmbeddingIgnoreProviders specifies providers to skip for this request.

func WithEmbeddingInputType

func WithEmbeddingInputType(inputType string) EmbeddingOption

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

func WithEmbeddingOnlyProviders

func WithEmbeddingOnlyProviders(providers ...string) EmbeddingOption

WithEmbeddingOnlyProviders restricts the request to only use specified providers.

func WithEmbeddingProvider

func WithEmbeddingProvider(provider Provider) EmbeddingOption

WithEmbeddingProvider sets provider-specific routing parameters.

func WithEmbeddingProviderOrder

func WithEmbeddingProviderOrder(providers ...string) EmbeddingOption

WithEmbeddingProviderOrder sets the order of providers to try.

func WithEmbeddingProviderSort

func WithEmbeddingProviderSort(sort string) EmbeddingOption

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

func WithEmbeddingUser

func WithEmbeddingUser(user string) EmbeddingOption

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

type EmbeddingRequest

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

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

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

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

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

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

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

	// SupportedParameters filters models by supported parameter (e.g. "tools", "temperature").
	SupportedParameters string

	// UseRSS returns an RSS feed instead of JSON when set to "true".
	UseRSS string

	// UseRSSChatLinks includes chat links in the RSS feed when set to "true".
	UseRSSChatLinks 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 MCPContent

type MCPContent struct {
	// Type is the content type (e.g., "text", "image", "resource")
	Type string `json:"type"`
	// Text is the text content (when Type is "text")
	Text string `json:"text,omitempty"`
	// Data is base64-encoded data (when Type is "image" or "resource")
	Data string `json:"data,omitempty"`
	// MimeType is the MIME type for binary content
	MimeType string `json:"mimeType,omitempty"`
}

MCPContent represents content in an MCP response.

type MCPInputSchema

type MCPInputSchema struct {
	// Type is typically "object" for MCP tool schemas
	Type string `json:"type,omitempty"`
	// Properties defines the tool's input parameters
	Properties map[string]interface{} `json:"properties,omitempty"`
	// Required lists parameter names that must be provided
	Required []string `json:"required,omitempty"`
	// AdditionalProperties controls whether extra properties are allowed
	AdditionalProperties *bool `json:"additionalProperties,omitempty"`
}

MCPInputSchema represents the input schema for an MCP tool. It follows JSON Schema Draft 7 format.

type MCPTool

type MCPTool struct {
	// Name is the unique identifier for the tool
	Name string `json:"name"`
	// Description explains what the tool does
	Description string `json:"description,omitempty"`
	// InputSchema defines the expected input parameters using JSON Schema
	InputSchema *MCPInputSchema `json:"inputSchema,omitempty"`
}

MCPTool represents a tool in MCP (Model Context Protocol) format. This format is used by MCP servers and clients for tool definitions.

func ParseMCPToolFromJSON

func ParseMCPToolFromJSON(data []byte) (MCPTool, error)

ParseMCPToolFromJSON parses an MCP tool from JSON data. This is useful when receiving tool definitions from an MCP server.

func ParseMCPToolsFromJSON

func ParseMCPToolsFromJSON(data []byte) ([]MCPTool, error)

ParseMCPToolsFromJSON parses multiple MCP tools from JSON data.

type MCPToolResult

type MCPToolResult struct {
	// Content contains the tool execution result(s)
	Content []MCPContent `json:"content"`
	// IsError indicates if the tool execution failed
	IsError bool `json:"isError,omitempty"`
}

MCPToolResult represents the result of an MCP tool execution.

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

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

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

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

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

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

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

func CreateUserMessageWithImage(text string, imageURL string) Message

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

func CreateUserMessageWithImageDetail

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

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

CreateUserMessageWithImages creates a user message with text and multiple images.

func CreateUserMessageWithPDF

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).

func CreateUserMessageWithTextContent

func CreateUserMessageWithTextContent(text string, content string, filename string) Message

CreateUserMessageWithTextContent creates a user message with inline text content. Unlike CreateUserMessageWithTextFile, this doesn't read from a file but formats the content with an optional filename for context.

func CreateUserMessageWithTextFile

func CreateUserMessageWithTextFile(text string, filePath string) (Message, error)

CreateUserMessageWithTextFile creates a user message with text and content from a text file. The file content is included inline as text, not base64-encoded. Example:

msg, err := CreateUserMessageWithTextFile(
    "Review this code for bugs:",
    "/path/to/code.py",
)

func CreateUserMessageWithTextFiles

func CreateUserMessageWithTextFiles(text string, filePaths ...string) (Message, error)

CreateUserMessageWithTextFiles creates a user message with multiple text files. Each file's content is included with a header showing the filename.

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

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

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 RequestOption

type RequestOption[T any] func(T)

RequestOption is a generic functional option type for configuring requests.

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 ResponsesAnnotation

type ResponsesAnnotation struct {
	// Type specifies the annotation type (e.g., "url_citation").
	Type string `json:"type"`

	// URL is the cited URL (for "url_citation" type).
	URL string `json:"url,omitempty"`

	// StartIndex is the start position of the citation in the text.
	StartIndex int `json:"start_index,omitempty"`

	// EndIndex is the end position of the citation in the text.
	EndIndex int `json:"end_index,omitempty"`
}

ResponsesAnnotation represents an annotation in the output content.

type ResponsesInputContent

type ResponsesInputContent struct {
	// Type specifies the content type: "input_text"
	Type string `json:"type"`

	// Text is the text content.
	Text string `json:"text"`
}

ResponsesInputContent represents a content item in a message.

type ResponsesInputItem

type ResponsesInputItem struct {
	// Type specifies the item type: "message" or "function_call_output"
	Type string `json:"type"`

	// ID is the unique identifier for this item (used in multi-turn conversations).
	ID string `json:"id,omitempty"`

	// Status indicates the completion status (e.g., "completed").
	Status string `json:"status,omitempty"`

	// Role is the message role: "user", "assistant", "system"
	// Only used when Type is "message".
	Role string `json:"role,omitempty"`

	// Content is the message content array.
	// Only used when Type is "message".
	Content []ResponsesInputContent `json:"content,omitempty"`

	// CallID is the ID of the function call being responded to.
	// Only used when Type is "function_call_output".
	CallID string `json:"call_id,omitempty"`

	// Output is the result of the function call.
	// Only used when Type is "function_call_output".
	Output string `json:"output,omitempty"`
}

ResponsesInputItem represents an item in the structured input array. Used for multi-turn conversations and function call outputs.

func CreateResponsesAssistantMessage

func CreateResponsesAssistantMessage(text string) ResponsesInputItem

CreateResponsesAssistantMessage creates an assistant message input item.

func CreateResponsesFunctionOutput

func CreateResponsesFunctionOutput(callID, output string) ResponsesInputItem

CreateResponsesFunctionOutput creates a function call output item.

func CreateResponsesMessage

func CreateResponsesMessage(role, text string) ResponsesInputItem

CreateResponsesMessage creates a message input item with the specified role and text.

func CreateResponsesSystemMessage

func CreateResponsesSystemMessage(text string) ResponsesInputItem

CreateResponsesSystemMessage creates a system message input item.

func CreateResponsesUserMessage

func CreateResponsesUserMessage(text string) ResponsesInputItem

CreateResponsesUserMessage creates a user message input item.

type ResponsesOption

type ResponsesOption = RequestOption[*ResponsesRequest]

ResponsesOption is a functional option for configuring ResponsesRequest.

func WithResponsesInput

func WithResponsesInput(input any) ResponsesOption

WithResponsesInput sets the input for the Responses API request. Input can be a string for simple text, or []ResponsesInputItem for structured messages.

func WithResponsesMaxOutputTokens

func WithResponsesMaxOutputTokens(tokens int) ResponsesOption

WithResponsesMaxOutputTokens sets the maximum number of output tokens.

func WithResponsesMetadata

func WithResponsesMetadata(metadata map[string]interface{}) ResponsesOption

WithResponsesMetadata sets metadata headers for the request.

func WithResponsesModel

func WithResponsesModel(model string) ResponsesOption

WithResponsesModel sets the model for the Responses API request.

func WithResponsesPlugins

func WithResponsesPlugins(plugins ...Plugin) ResponsesOption

WithResponsesPlugins appends plugins to the request. This appends to any existing plugins to avoid overwriting plugins added by other options like WithResponsesWebSearch.

func WithResponsesReasoning

func WithResponsesReasoning(ptr *ResponsesReasoning) ResponsesOption

WithResponsesReasoning sets the reasoning configuration. If ptr is nil, r.Reasoning is left nil. Otherwise, a defensive copy is made.

func WithResponsesReasoningEffort

func WithResponsesReasoningEffort(effort string) ResponsesOption

WithResponsesReasoningEffort sets the reasoning effort level. Valid values: "minimal", "low", "medium", "high"

func WithResponsesTemperature

func WithResponsesTemperature(temperature float64) ResponsesOption

WithResponsesTemperature sets the temperature for sampling (0-2).

func WithResponsesToolChoice

func WithResponsesToolChoice(toolChoice any) ResponsesOption

WithResponsesToolChoice sets the tool choice strategy for ResponsesRequest.ToolChoice. Can be:

• "auto" - let the model decide whether to call tools
• "none" - disable tool calling
• A specific tool: map[string]any{"type": "function", "function": map[string]any{"name": "functionName"}}

func WithResponsesTools

func WithResponsesTools(tools ...ResponsesTool) ResponsesOption

WithResponsesTools sets the available tools/functions for the request. Uses ResponsesTool which has a flat structure expected by the Responses API.

func WithResponsesTopP

func WithResponsesTopP(topP float64) ResponsesOption

WithResponsesTopP sets the top_p value for nucleus sampling (0-1).

func WithResponsesWebSearch

func WithResponsesWebSearch(maxResults int) ResponsesOption

WithResponsesWebSearch enables web search with the specified maximum results. This is a convenience function that adds the web search plugin.

type ResponsesOutput

type ResponsesOutput struct {
	// Type specifies the output type: "message" or "function_call"
	Type string `json:"type"`

	// ID is the unique identifier for this output item.
	ID string `json:"id"`

	// Status indicates the completion status.
	Status string `json:"status,omitempty"`

	// Role is the message role (for "message" type).
	Role string `json:"role,omitempty"`

	// Content is the message content array (for "message" type).
	Content []ResponsesOutputContent `json:"content,omitempty"`

	// CallID is the function call ID (for "function_call" type).
	CallID string `json:"call_id,omitempty"`

	// Name is the function name (for "function_call" type).
	Name string `json:"name,omitempty"`

	// Arguments is the JSON-encoded function arguments (for "function_call" type).
	Arguments string `json:"arguments,omitempty"`
}

ResponsesOutput represents an output item in the response.

type ResponsesOutputContent

type ResponsesOutputContent struct {
	// Type specifies the content type: "output_text" or "reasoning"
	Type string `json:"type"`

	// Text is the text content (for "output_text" type).
	Text string `json:"text,omitempty"`

	// Annotations contains URL citations and other annotations.
	Annotations []ResponsesAnnotation `json:"annotations,omitempty"`

	// EncryptedContent contains the encrypted reasoning chain (for "reasoning" type).
	EncryptedContent string `json:"encrypted_content,omitempty"`

	// Summary contains key reasoning steps as text (for "reasoning" type).
	Summary []string `json:"summary,omitempty"`
}

ResponsesOutputContent represents a content item in the output.

type ResponsesReasoning

type ResponsesReasoning struct {
	// Effort controls the computational intensity of reasoning.
	// Valid values: "minimal", "low", "medium", "high"
	Effort string `json:"effort"`
}

ResponsesReasoning configures reasoning capabilities for the Responses API.

type ResponsesRequest

type ResponsesRequest struct {
	// Model is the model identifier (required).
	// Example: "openai/o4-mini"
	Model string `json:"model"`

	// Input is the input to the model (required).
	// Can be a string for simple text input, or []ResponsesInputItem for structured messages.
	Input any `json:"input"`

	// Stream enables streaming responses via Server-Sent Events.
	Stream bool `json:"stream,omitempty"`

	// MaxOutputTokens limits the number of tokens in the response.
	MaxOutputTokens *int `json:"max_output_tokens,omitempty"`

	// Temperature controls randomness in sampling (0-2).
	Temperature *float64 `json:"temperature,omitempty"`

	// TopP controls nucleus sampling (0-1).
	TopP *float64 `json:"top_p,omitempty"`

	// Reasoning configures reasoning capabilities.
	Reasoning *ResponsesReasoning `json:"reasoning,omitempty"`

	// Tools defines available functions the model can call.
	// Uses ResponsesTool which has a flat structure (name, description, parameters at top level).
	Tools []ResponsesTool `json:"tools,omitempty"`

	// ToolChoice controls tool invocation behavior.
	// Can be "auto", "none", or a specific tool specification.
	ToolChoice any `json:"tool_choice,omitempty"`

	// Plugins configures plugins like web search.
	Plugins []Plugin `json:"plugins,omitempty"`

	// Metadata is used for custom headers (not serialized to JSON).
	Metadata map[string]interface{} `json:"-"`
}

ResponsesRequest represents a request to the OpenRouter Responses API.

WARNING: BETA API - EXPECT BREAKING CHANGES

This API is in beta and may have breaking changes at any time. Do not rely on this for production workloads. The API structure, parameters, and behavior may change without notice.

For stable production use, consider using ChatCompletionRequest instead.

Features: reasoning, tool calling, web search integration, and streaming.

func (*ResponsesRequest) GetMetadata

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

GetMetadata returns the metadata map for header generation.

type ResponsesResponse

type ResponsesResponse struct {
	// ID is the unique identifier for this response.
	ID string `json:"id"`

	// Object is the object type, always "response".
	Object string `json:"object"`

	// CreatedAt is the Unix timestamp when the response was created.
	CreatedAt int64 `json:"created_at"`

	// Model is the model that generated the response.
	Model string `json:"model"`

	// Output is the array of output items (messages, function calls, etc.).
	Output []ResponsesOutput `json:"output"`

	// Usage contains token usage information.
	Usage ResponsesUsage `json:"usage"`

	// Status indicates the completion status (e.g., "completed").
	Status string `json:"status"`

	// Metadata contains additional response metadata.
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

ResponsesResponse represents a response from the OpenRouter Responses API.

func (*ResponsesResponse) GetAnnotations

func (r *ResponsesResponse) GetAnnotations() []ResponsesAnnotation

GetAnnotations returns all annotations from the response.

func (*ResponsesResponse) GetFunctionCalls

func (r *ResponsesResponse) GetFunctionCalls() []ResponsesOutput

GetFunctionCalls returns all function calls from the response.

func (*ResponsesResponse) GetReasoningSummary

func (r *ResponsesResponse) GetReasoningSummary() []string

GetReasoningSummary returns the reasoning summary if present.

func (*ResponsesResponse) GetTextContent

func (r *ResponsesResponse) GetTextContent() string

GetTextContent extracts the text content from a ResponsesResponse. Returns the first text content found in the output, or an empty string if none found.

type ResponsesStream

type ResponsesStream = Stream[ResponsesResponse]

ResponsesStream represents a streaming response from the Responses API.

type ResponsesTool

type ResponsesTool struct {
	// Type specifies the tool type, always "function".
	Type string `json:"type"`

	// Name is the function name.
	Name string `json:"name"`

	// Description explains what the function does.
	Description string `json:"description,omitempty"`

	// Strict enables strict schema validation (set to null/nil for default behavior).
	Strict *bool `json:"strict"`

	// Parameters is the JSON Schema for the function parameters.
	Parameters map[string]any `json:"parameters,omitempty"`
}

ResponsesTool represents a tool definition for the Responses API. This has a flat structure unlike the Chat Completions API which nests under "function".

func ConvertToolToResponsesTool

func ConvertToolToResponsesTool(tool Tool) ResponsesTool

ConvertToolToResponsesTool converts a Chat Completions Tool to a Responses API tool.

func ConvertToolsToResponsesTools

func ConvertToolsToResponsesTools(tools []Tool) []ResponsesTool

ConvertToolsToResponsesTools converts multiple Chat Completions Tools to Responses API tools.

func CreateResponsesTool

func CreateResponsesTool(name, description string, parameters map[string]any) ResponsesTool

CreateResponsesTool creates a ResponsesTool with the given parameters.

type ResponsesUsage

type ResponsesUsage struct {
	// InputTokens is the number of tokens in the input.
	InputTokens int `json:"input_tokens"`

	// OutputTokens is the number of tokens in the output.
	OutputTokens int `json:"output_tokens"`

	// TotalTokens is the total number of tokens used.
	TotalTokens int `json:"total_tokens"`

	// ReasoningTokens is the number of tokens used for reasoning (if reasoning is enabled).
	ReasoningTokens int `json:"reasoning_tokens,omitempty"`
}

ResponsesUsage contains token usage information for the Responses API.

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 TextChunk

type TextChunk struct {
	// Text is the chunk content.
	Text string

	// Index is the zero-based index of this chunk.
	Index int

	// StartPos is the byte offset in the original text where this chunk starts.
	StartPos int

	// EndPos is the byte offset in the original text where this chunk ends.
	EndPos int
}

TextChunk represents a single chunk of text with metadata.

func ChunkText

func ChunkText(text string, config ChunkConfig) ([]TextChunk, error)

ChunkText splits text into chunks according to the configuration.

type Tool

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

Tool represents a tool/function that can be called.

func ConvertMCPTool

func ConvertMCPTool(mcpTool MCPTool) Tool

ConvertMCPTool converts an MCP tool to OpenRouter's Tool format. The OpenRouter format follows the OpenAI function calling specification.

func ConvertMCPTools

func ConvertMCPTools(mcpTools []MCPTool) []Tool

ConvertMCPTools converts a slice of MCP tools to OpenRouter Tool format.

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.