openrouter

README

openrouter-go

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

📚 Docs site: https://openrouter-go.hra42.lol · Recipes: docs/recipes/ · Building with an AI coding agent? Start with AGENTS.md.

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.26 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
• ✅ Workspaces management (create/list/update/delete, bulk member add/remove)
• ✅ Organization member listing
• ✅ Guardrails for spend caps, allowed model/provider lists, and ZDR enforcement
• ✅ Video generation with async job submission, polling, and content download
• ✅ Text-to-speech (/audio/speech) with mp3/pcm output
• ✅ Rerank endpoint for relevance scoring (e.g. Cohere rerank-v3.5)
• ✅ Broadcast webhook parsing (OTLP JSON traces)
• ✅ OAuth PKCE authorization-code exchange helper
• ⚠️ [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.26
• 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
• videos/ - Submit, poll, and download a video generation job
• tts/ - Create speech audio from text via /audio/speech
• rerank/ - Rerank documents by relevance to a query
• workspaces/ - Manage workspaces (Management API key required)
• list-organization-members/ - List members of your organization
• broadcast-webhook/ - Parse OTLP JSON payloads from the Broadcast webhook
• oauth-pkce/ - Exchange an OAuth PKCE auth code for an API key

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

# Run workspaces example (requires a Management key)
go run examples/workspaces/main.go

Documentation

Task-indexed recipes live under docs/recipes/. A few pointers to the newer endpoints:

• Workspaces — Management API for workspace lifecycle and membership
• Video generation — async submit/poll/download flow
• Guardrails — spend caps, allowed models, ZDR enforcement, key/member assignment
• Organization members — list org members for admin dashboards
• Text-to-speech, Rerank, Broadcast webhook, OAuth PKCE

For detailed API documentation and usage examples, see DOCUMENTATION.md. Building agent code against the SDK? Start with AGENTS.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 is a zero-dependency Go client for the OpenRouter API (https://openrouter.ai). It provides complete bindings for chat completions, legacy completions, streaming via Server-Sent Events, tool calling, structured outputs, multimodal inputs (image, audio, PDF, text file), embeddings, the Responses API (beta), the Anthropic-compatible Messages endpoint, broadcast webhook parsing, and the full account/admin surface (models, providers, keys, activity, credits, guardrails, ZDR).

The entire package uses only the Go standard library.

Quick start

client := openrouter.NewClient(openrouter.WithAPIKey(os.Getenv("OPENROUTER_API_KEY")))

resp, err := client.ChatComplete(ctx,
    []openrouter.Message{openrouter.CreateUserMessage("Hello")},
    openrouter.WithModel("openai/gpt-4o-mini"),
)
if err != nil {
    log.Fatal(err)
}
fmt.Println(resp.Choices[0].Message.Content)

Design

The package follows a small set of conventions used uniformly across every endpoint:

• Functional options. Both NewClient and every request method take a variadic list of options (for example WithAPIKey, WithModel, WithTools, WithResponseFormat). New behavior is added via new option functions rather than by growing config structs.

• context.Context on every call, for cancellation and deadlines.

• Streaming via typed iterators (ChatStream, CompletionStream, ResponsesStream) that must be closed by the caller. The canonical loop is:

  stream, err := client.ChatCompleteStream(ctx, msgs, openrouter.WithModel(m)) if err != nil { return err } defer stream.Close() for event := range stream.Events() { // accumulate event.Choices[0].Delta.Content, etc. } if err := stream.Err(); err != nil { return err }

• Errors unwrap to *RequestError, which exposes helpers such as IsRateLimitError, IsAuthenticationError, IsContextLengthError, and IsModerationError for structured handling.

• Automatic retry with exponential backoff on transient failures, configurable via [WithMaxRetries] and [WithRetryDelay].

• Thread-safe: a single Client is safe for concurrent use by multiple goroutines.

Stability

The chat, completion, streaming, tool-calling, structured-output, multimodal, embeddings, models, providers, keys, credits, activity, transforms, web-search, MCP-conversion, and broadcast-webhook APIs are stable.

The Responses API (see Client.CreateResponse and Client.CreateResponseStream) is in beta and may have breaking changes; avoid using it in production workloads.

Further reading

Runnable examples live under examples/ in the repository. Agent-oriented conventions live in AGENTS.md; build and test commands live in CLAUDE.md; a task-to-file index lives in llms.txt.

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 BroadcastWebhookHandler(callback func([]BroadcastTrace)) http.HandlerFunc
• func BroadcastWebhookHandlerWithError(callback func([]BroadcastTrace) error) http.HandlerFunc
• func BuildAuthURL(baseURL string, params AuthURLParams) (string, error)
• 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 CreateS256CodeChallenge(verifier string) string
• 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 EndpointSupportsParameter(params []string, param string) bool
• func EstimateTokens(text string) int
• func EstimateTokensFromWords(text string) int
• func GenerateCodeVerifier() (string, error)
• func ParsePricing(priceStr string) float64
• func ParsePricingPtr(priceStr *string) float64
• 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 AnthropicCitation
• type AnthropicCitationsConfig
• type AnthropicContentBlock
  • func CreateAnthropicDocumentBase64Block(mediaType string, data string) AnthropicContentBlock
  • func CreateAnthropicDocumentURLBlock(url string) AnthropicContentBlock
  • func CreateAnthropicImageBase64Block(mediaType string, data string) AnthropicContentBlock
  • func CreateAnthropicImageURLBlock(url string) AnthropicContentBlock
  • func CreateAnthropicTextBlock(text string) AnthropicContentBlock
  • func CreateAnthropicToolResultBlock(toolUseID string, content string) AnthropicContentBlock
  • func CreateAnthropicToolUseBlock(id, name string, input json.RawMessage) AnthropicContentBlock
• type AnthropicContentSource
• type AnthropicMessage
  • func CreateAnthropicAssistantMessage(text string) AnthropicMessage
  • func CreateAnthropicUserMessage(text string) AnthropicMessage
  • func CreateAnthropicUserMessageWithBlocks(blocks []AnthropicContentBlock) AnthropicMessage
• type AnthropicMessagesRequest
  • func (r *AnthropicMessagesRequest) GetMetadata() map[string]any
• type AnthropicMessagesResponse
  • func (r *AnthropicMessagesResponse) GetStopReason() string
  • func (r *AnthropicMessagesResponse) GetTextBlocks() []AnthropicResponseContentBlock
  • func (r *AnthropicMessagesResponse) GetTextContent() string
  • func (r *AnthropicMessagesResponse) GetThinkingContent() string
  • func (r *AnthropicMessagesResponse) GetToolUseBlocks() []AnthropicResponseContentBlock
  • func (r *AnthropicMessagesResponse) IsToolUse() bool
• type AnthropicOption
  • func WithAnthropicHeaderMetadata(metadata map[string]any) AnthropicOption
  • func WithAnthropicMaxTokens(maxTokens int) AnthropicOption
  • func WithAnthropicMessages(messages []AnthropicMessage) AnthropicOption
  • func WithAnthropicModel(model string) AnthropicOption
  • func WithAnthropicModels(models ...string) AnthropicOption
  • func WithAnthropicPlugins(plugins ...Plugin) AnthropicOption
  • func WithAnthropicProvider(provider Provider) AnthropicOption
  • func WithAnthropicRequestMetadata(metadata AnthropicRequestMetadata) AnthropicOption
  • func WithAnthropicServiceTier(tier string) AnthropicOption
  • func WithAnthropicSessionID(sessionID string) AnthropicOption
  • func WithAnthropicStopSequences(sequences ...string) AnthropicOption
  • func WithAnthropicSystemBlocks(blocks []AnthropicTextBlock) AnthropicOption
  • func WithAnthropicSystemString(system string) AnthropicOption
  • func WithAnthropicTemperature(temperature float64) AnthropicOption
  • func WithAnthropicThinkingDisabled() AnthropicOption
  • func WithAnthropicThinkingEnabled(budgetTokens int) AnthropicOption
  • func WithAnthropicToolChoiceAny() AnthropicOption
  • func WithAnthropicToolChoiceAuto() AnthropicOption
  • func WithAnthropicToolChoiceNone() AnthropicOption
  • func WithAnthropicToolChoiceSpecific(name string) AnthropicOption
  • func WithAnthropicTools(tools ...AnthropicTool) AnthropicOption
  • func WithAnthropicTopK(topK int) AnthropicOption
  • func WithAnthropicTopP(topP float64) AnthropicOption
  • func WithAnthropicUser(user string) AnthropicOption
• type AnthropicRequestMetadata
• type AnthropicResponseContentBlock
• type AnthropicStream
• type AnthropicStreamDelta
• type AnthropicStreamError
• type AnthropicStreamEvent
  • func (e *AnthropicStreamEvent) GetTextDelta() string
• type AnthropicStreamUsage
• type AnthropicTextBlock
• type AnthropicThinkingConfig
• type AnthropicTool
  • func CreateAnthropicBashTool() AnthropicTool
  • func CreateAnthropicCustomTool(name, description string, schema map[string]any) AnthropicTool
  • func CreateAnthropicTextEditorTool() AnthropicTool
  • func CreateAnthropicWebSearchTool(maxUses *int) AnthropicTool
• type AnthropicToolChoice
• type AnthropicUsage
• type AssignKeysRequest
• type AssignKeysResponse
• type AssignMembersRequest
• type AssignMembersResponse
• type AuthURLParams
• type BroadcastTrace
  • func ExtractBroadcastTraces(payload *OTLPExportTraceRequest) []BroadcastTrace
  • func ParseBroadcastTraces(data []byte) ([]BroadcastTrace, error)
• type BulkAddWorkspaceMembersResponse
• type BulkRemoveWorkspaceMembersResponse
• 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]any) 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]any) ChatCompletionOption
  • func WithMinP(minP float64) 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 WithRequestRetry(maxRetries int, retryDelay time.Duration) ChatCompletionOption
  • func WithRequestTimeout(timeout time.Duration) 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 WithStreamChannelBuffer(n int) ChatCompletionOption
  • func WithStreamMaxBackoff(d time.Duration) ChatCompletionOption
  • func WithStreamMaxRetries(n int) ChatCompletionOption
  • func WithTemperature(temperature float64) ChatCompletionOption
  • func WithToolChoice(toolChoice any) ChatCompletionOption
  • func WithTools(tools ...Tool) ChatCompletionOption
  • func WithTopA(topA float64) 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]any
• type ChatCompletionResponse
• type ChatStream
• type Choice
• type ChunkConfig
  • func DefaultChunkConfig() ChunkConfig
• type ChunkEmbedding
• type ChunkStrategy
• type ChunkedEmbeddingResult
• type CircuitBreaker
  • func NewCircuitBreaker(config *CircuitBreakerConfig) *CircuitBreaker
  • func (cb *CircuitBreaker) AllowRequest() bool
  • func (cb *CircuitBreaker) RecordFailure()
  • func (cb *CircuitBreaker) RecordSuccess()
  • func (cb *CircuitBreaker) Reset()
  • func (cb *CircuitBreaker) State() CircuitState
• type CircuitBreakerConfig
  • func DefaultCircuitBreakerConfig() *CircuitBreakerConfig
• type CircuitBreakerError
  • func IsCircuitBreakerError(err error) (*CircuitBreakerError, bool)
  • func (e *CircuitBreakerError) Error() string
• type CircuitState
  • func (s CircuitState) String() string
• type Client
  • func NewClient(opts ...ClientOption) *Client
  • func (c *Client) AddWorkspaceMembers(ctx context.Context, idOrSlug string, userIDs []string) (*BulkAddWorkspaceMembersResponse, error)
  • func (c *Client) AssignKeysToGuardrail(ctx context.Context, id string, request *AssignKeysRequest) (*AssignKeysResponse, error)
  • func (c *Client) AssignMembersToGuardrail(ctx context.Context, id string, request *AssignMembersRequest) (*AssignMembersResponse, error)
  • 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) CreateAnthropicMessage(ctx context.Context, messages []AnthropicMessage, opts ...AnthropicOption) (*AnthropicMessagesResponse, error)
  • func (c *Client) CreateAnthropicMessageStream(ctx context.Context, messages []AnthropicMessage, opts ...AnthropicOption) (*AnthropicStream, 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 any, model string, opts ...EmbeddingOption) (*EmbeddingResponse, error)
  • func (c *Client) CreateEmbeddings(ctx context.Context, inputs []string, model string, opts ...EmbeddingOption) (*EmbeddingResponse, error)
  • func (c *Client) CreateGuardrail(ctx context.Context, request *CreateGuardrailRequest) (*Guardrail, error)
  • func (c *Client) CreateKey(ctx context.Context, request *CreateKeyRequest) (*CreateKeyResponse, error)
  • func (c *Client) CreateResponse(ctx context.Context, input any, opts ...ResponsesOption) (*ResponsesResponse, error)
  • func (c *Client) CreateResponseStream(ctx context.Context, input any, opts ...ResponsesOption) (*ResponsesStream, error)
  • func (c *Client) CreateSpeech(ctx context.Context, input, model, voice string, opts ...SpeechOption) (*SpeechResponse, error)
  • func (c *Client) CreateVideo(ctx context.Context, model, prompt string, opts ...VideoGenerationOption) (*VideoGenerationResponse, error)
  • func (c *Client) CreateWorkspace(ctx context.Context, req *CreateWorkspaceRequest) (*CreateWorkspaceResponse, error)
  • func (c *Client) DeleteGuardrail(ctx context.Context, id string) (*DeleteGuardrailResponse, error)
  • func (c *Client) DeleteKey(ctx context.Context, hash string) (*DeleteKeyResponse, error)
  • func (c *Client) DeleteWorkspace(ctx context.Context, idOrSlug string) (*DeleteWorkspaceResponse, error)
  • func (c *Client) ExchangeAuthCode(ctx context.Context, request *ExchangeAuthCodeRequest) (*ExchangeAuthCodeResponse, error)
  • func (c *Client) GetActivity(ctx context.Context, opts *ActivityOptions) (*ActivityResponse, error)
  • func (c *Client) GetCredits(ctx context.Context) (*CreditsResponse, error)
  • func (c *Client) GetGuardrail(ctx context.Context, id string) (*Guardrail, error)
  • func (c *Client) GetKey(ctx context.Context) (*KeyResponse, error)
  • func (c *Client) GetKeyByHash(ctx context.Context, hash string) (*GetKeyByHashResponse, error)
  • func (c *Client) GetVideo(ctx context.Context, jobID string) (*VideoGenerationResponse, error)
  • func (c *Client) GetVideoContent(ctx context.Context, jobID string, index int) (*VideoContentResponse, error)
  • func (c *Client) GetWorkspace(ctx context.Context, idOrSlug string) (*GetWorkspaceResponse, error)
  • func (c *Client) ListAllKeyAssignments(ctx context.Context, options *ListGuardrailsOptions) (*ListGuardrailKeyAssignmentsResponse, error)
  • func (c *Client) ListAllMemberAssignments(ctx context.Context, options *ListGuardrailsOptions) (*ListGuardrailMemberAssignmentsResponse, error)
  • func (c *Client) ListEmbeddingsModels(ctx context.Context) (*EmbeddingsModelsResponse, error)
  • func (c *Client) ListGuardrailKeyAssignments(ctx context.Context, id string, options *ListGuardrailsOptions) (*ListGuardrailKeyAssignmentsResponse, error)
  • func (c *Client) ListGuardrailMemberAssignments(ctx context.Context, id string, options *ListGuardrailsOptions) (*ListGuardrailMemberAssignmentsResponse, error)
  • func (c *Client) ListGuardrails(ctx context.Context, options *ListGuardrailsOptions) (*ListGuardrailsResponse, 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) ListModelsUser(ctx context.Context) (*ModelsResponse, error)
  • func (c *Client) ListOrganizationMembers(ctx context.Context, options *ListOrganizationMembersOptions) (*ListOrganizationMembersResponse, error)
  • func (c *Client) ListProviders(ctx context.Context) (*ProvidersResponse, error)
  • func (c *Client) ListVideoModels(ctx context.Context) (*VideoModelsResponse, error)
  • func (c *Client) ListWorkspaces(ctx context.Context, options *ListWorkspacesOptions) (*ListWorkspacesResponse, error)
  • func (c *Client) ListZDREndpoints(ctx context.Context) (*ZDREndpointsResponse, error)
  • func (c *Client) RemoveWorkspaceMembers(ctx context.Context, idOrSlug string, userIDs []string) (*BulkRemoveWorkspaceMembersResponse, error)
  • func (c *Client) Rerank(ctx context.Context, query string, documents []string, model string, ...) (*RerankResponse, error)
  • func (c *Client) UnassignKeysFromGuardrail(ctx context.Context, id string, request *AssignKeysRequest) error
  • func (c *Client) UnassignMembersFromGuardrail(ctx context.Context, id string, request *AssignMembersRequest) error
  • func (c *Client) UpdateGuardrail(ctx context.Context, id string, request *UpdateGuardrailRequest) (*Guardrail, error)
  • func (c *Client) UpdateKey(ctx context.Context, hash string, request *UpdateKeyRequest) (*UpdateKeyResponse, error)
  • func (c *Client) UpdateWorkspace(ctx context.Context, idOrSlug string, req *UpdateWorkspaceRequest) (*UpdateWorkspaceResponse, error)
• type ClientOption
  • func WithAPIKey(apiKey string) ClientOption
  • func WithAppName(appName string) ClientOption
  • func WithBaseURL(baseURL string) ClientOption
  • func WithCircuitBreaker(config *CircuitBreakerConfig) 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 WithStreamConfig(config *StreamConfig) ClientOption
  • func WithTimeout(timeout time.Duration) ClientOption
• type CodeChallengeMethod
• 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 WithCompletionFrequencyPenalty(penalty float64) CompletionOption
  • func WithCompletionIgnoreProviders(providers ...string) CompletionOption
  • func WithCompletionJSONMode() CompletionOption
  • func WithCompletionJSONSchema(name string, strict bool, schema map[string]any) CompletionOption
  • func WithCompletionLogProbs(logProbs int) CompletionOption
  • func WithCompletionMaxPrice(maxPrice MaxPrice) CompletionOption
  • func WithCompletionMaxTokens(maxTokens int) CompletionOption
  • func WithCompletionMetadata(metadata map[string]any) CompletionOption
  • func WithCompletionMinP(minP float64) 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 WithCompletionPresencePenalty(penalty float64) CompletionOption
  • func WithCompletionProvider(provider Provider) CompletionOption
  • func WithCompletionProviderOrder(providers ...string) CompletionOption
  • func WithCompletionProviderSort(sort string) CompletionOption
  • func WithCompletionQuantizations(quantizations ...string) CompletionOption
  • func WithCompletionRepetitionPenalty(penalty float64) CompletionOption
  • func WithCompletionRequestRetry(maxRetries int, retryDelay time.Duration) CompletionOption
  • func WithCompletionRequestTimeout(timeout time.Duration) CompletionOption
  • func WithCompletionRequireParameters(require bool) CompletionOption
  • func WithCompletionResponseFormat(format ResponseFormat) CompletionOption
  • func WithCompletionRoute(route string) CompletionOption
  • func WithCompletionSeed(seed int) CompletionOption
  • func WithCompletionStop(stop ...string) CompletionOption
  • func WithCompletionStreamChannelBuffer(n int) CompletionOption
  • func WithCompletionStreamMaxBackoff(d time.Duration) CompletionOption
  • func WithCompletionStreamMaxRetries(n int) CompletionOption
  • func WithCompletionSuffix(suffix string) CompletionOption
  • func WithCompletionTemperature(temperature float64) CompletionOption
  • func WithCompletionTopA(topA float64) CompletionOption
  • func WithCompletionTopK(topK int) 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]any
• 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 CostResult
  • func EstimateCost(pricing ModelPricing, usage Usage) CostResult
  • func EstimateCostFromTokens(promptPrice, completionPrice string, promptTokens, completionTokens int) CostResult
  • func EstimateCostWithCaching(pricing ModelPricing, usage Usage, cacheReadTokens, cacheWriteTokens int) CostResult
• type CreateGuardrailRequest
• type CreateKeyRequest
• type CreateKeyResponse
• type CreateWorkspaceRequest
• type CreateWorkspaceResponse
• type CreditsData
• type CreditsResponse
• type DeleteGuardrailResponse
• type DeleteKeyData
• type DeleteKeyResponse
• type DeleteWorkspaceResponse
• 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 EndpointFilter
• type ErrorResponse
• type ExchangeAuthCodeRequest
• type ExchangeAuthCodeResponse
• type File
• type FileAnnotation
• type FlexInt
  • func (f FlexInt) MarshalJSON() ([]byte, error)
  • func (f FlexInt) String() string
  • func (f *FlexInt) UnmarshalJSON(data []byte) error
• type Function
• type FunctionCall
• type GetKeyByHashResponse
• type GetWorkspaceResponse
• type Guardrail
• type GuardrailKeyAssignment
• type GuardrailMemberAssignment
• type ImageURL
• type InputAudio
• type JSONSchema
• type KeyData
• type KeyRateLimit
• type KeyResponse
• type ListGuardrailKeyAssignmentsResponse
• type ListGuardrailMemberAssignmentsResponse
• type ListGuardrailsOptions
• type ListGuardrailsResponse
• type ListKeysOptions
• type ListKeysResponse
• type ListModelsOptions
• type ListOrganizationMembersOptions
• type ListOrganizationMembersResponse
• type ListWorkspacesOptions
• type ListWorkspacesResponse
• 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
  • func FilterModels(models []Model, predicate func(*Model) bool) []Model
  • func (m *Model) HasInputModality(modality string) bool
  • func (m *Model) HasOutputModality(modality string) bool
  • func (m *Model) SupportsAudio() bool
  • func (m *Model) SupportsJSON() bool
  • func (m *Model) SupportsParameter(param string) bool
  • func (m *Model) SupportsStreaming() bool
  • func (m *Model) SupportsTools() bool
  • func (m *Model) SupportsVision() bool
• type ModelArchitecture
• type ModelDefaultParameters
• type ModelEndpoint
  • func CheapestModelEndpoint(endpoints []ModelEndpoint) *ModelEndpoint
  • func FilterModelEndpoints(endpoints []ModelEndpoint, filter EndpointFilter) []ModelEndpoint
• type ModelEndpointPricing
• type ModelEndpointsArchitecture
• type ModelEndpointsData
• type ModelEndpointsResponse
• type ModelPerRequestLimits
• type ModelPricing
• type ModelTopProvider
• type ModelsResponse
• type OTLPAnyValue
  • func (v OTLPAnyValue) StringVal() string
• type OTLPArrayValue
• type OTLPAttribute
• type OTLPEvent
• type OTLPExportTraceRequest
  • func ParseBroadcastPayload(data []byte) (*OTLPExportTraceRequest, error)
• type OTLPResource
• type OTLPResourceSpan
• type OTLPScope
• type OTLPScopeSpan
• type OTLPSpan
• type OTLPStatus
• type OrganizationMember
• type OrganizationMemberRole
• type PDFParserConfig
• type PercentileStats
• 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 PublicEndpoint
  • func CheapestZDREndpoint(endpoints []PublicEndpoint) *PublicEndpoint
  • func FilterZDREndpoints(endpoints []PublicEndpoint, filter EndpointFilter) []PublicEndpoint
• type PublicEndpointPricing
• 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 RerankDocument
• type RerankOption
  • func WithRerankAllowFallbacks(allow bool) RerankOption
  • func WithRerankDataCollection(policy string) RerankOption
  • func WithRerankIgnoreProviders(providers ...string) RerankOption
  • func WithRerankOnlyProviders(providers ...string) RerankOption
  • func WithRerankProvider(provider Provider) RerankOption
  • func WithRerankProviderOrder(providers ...string) RerankOption
  • func WithRerankProviderSort(sort string) RerankOption
  • func WithRerankTopN(topN int) RerankOption
• type RerankRequest
• type RerankResponse
• type RerankResult
• type RerankUsage
• type ResetInterval
• 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]any) 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]any
• 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 SpeechOption
  • func WithSpeechProviderOptions(provider string, options map[string]any) SpeechOption
  • func WithSpeechResponseFormat(format string) SpeechOption
  • func WithSpeechSpeed(speed float64) SpeechOption
• type SpeechProvider
• type SpeechRequest
• type SpeechResponse
• type Stream
  • func (s *Stream[T]) Close() error
  • func (s *Stream[T]) Err() error
  • func (s *Stream[T]) Events() <-chan T
• type StreamConfig
  • func DefaultStreamConfig() *StreamConfig
• 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 UpdateGuardrailRequest
• type UpdateKeyRequest
• type UpdateKeyResponse
• type UpdateWorkspaceRequest
• type UpdateWorkspaceResponse
• type Usage
• type ValidationError
  • func IsValidationError(err error) (*ValidationError, bool)
  • func (e *ValidationError) Error() string
• type VideoAspectRatio
• type VideoContentPartImage
• type VideoContentResponse
• type VideoFrameImage
• type VideoFrameType
• type VideoGenerationOption
  • func WithVideoAspectRatio(ratio VideoAspectRatio) VideoGenerationOption
  • func WithVideoCallbackURL(url string) VideoGenerationOption
  • func WithVideoDuration(seconds int) VideoGenerationOption
  • func WithVideoFrameImages(frames ...VideoFrameImage) VideoGenerationOption
  • func WithVideoGenerateAudio(enabled bool) VideoGenerationOption
  • func WithVideoInputReferences(refs ...VideoContentPartImage) VideoGenerationOption
  • func WithVideoProviderOptions(provider string, options map[string]any) VideoGenerationOption
  • func WithVideoResolution(resolution VideoResolution) VideoGenerationOption
  • func WithVideoSeed(seed int) VideoGenerationOption
  • func WithVideoSize(size string) VideoGenerationOption
• type VideoGenerationRequest
• type VideoGenerationResponse
• type VideoGenerationUsage
• type VideoImageURL
• type VideoModel
• type VideoModelsResponse
• type VideoProvider
• type VideoResolution
• type VideoStatus
• type WebSearchContextSize
• type WebSearchEngine
• type WebSearchOptions
• type Workspace
• type WorkspaceMember
• type WorkspaceMemberRole
• type ZDREndpointsResponse

Constants

const (
	AnthropicStopReasonEndTurn      = "end_turn"
	AnthropicStopReasonMaxTokens    = "max_tokens"
	AnthropicStopReasonStopSequence = "stop_sequence"
	AnthropicStopReasonToolUse      = "tool_use"
)

Anthropic Messages API stop reasons.

const (
	AnthropicThinkingEnabled  = "enabled"
	AnthropicThinkingDisabled = "disabled"
)

Anthropic thinking types.

const (
	AnthropicToolChoiceAuto = "auto"
	AnthropicToolChoiceAny  = "any"
	AnthropicToolChoiceNone = "none"
	AnthropicToolChoiceTool = "tool"
)

Anthropic tool choice types.

const (
	AnthropicServiceTierAuto     = "auto"
	AnthropicServiceTierStandard = "standard"
)

Anthropic service tier values.

const (
	AnthropicContentTypeText             = "text"
	AnthropicContentTypeImage            = "image"
	AnthropicContentTypeDocument         = "document"
	AnthropicContentTypeToolUse          = "tool_use"
	AnthropicContentTypeToolResult       = "tool_result"
	AnthropicContentTypeThinking         = "thinking"
	AnthropicContentTypeRedactedThinking = "redacted_thinking"
)

Anthropic content block types.

const (
	AnthropicSourceBase64 = "base64"
	AnthropicSourceURL    = "url"
)

Anthropic source types.

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.

const (
	SpeechFormatMP3 = "mp3"
	SpeechFormatPCM = "pcm"
)

Audio response formats for the Create Speech endpoint.

Variables

var (
	// ErrNoAnthropicMessages is returned when no messages are provided.
	ErrNoAnthropicMessages = &ValidationError{
		Field:   "messages",
		Message: "at least one message is required",
	}

	// ErrAnthropicMaxTokensRequired is returned when max_tokens is not set.
	ErrAnthropicMaxTokensRequired = &ValidationError{
		Field:   "max_tokens",
		Message: "max_tokens is required and must be greater than 0",
	}
)

Predefined validation errors for Anthropic Messages API.

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 BroadcastWebhookHandler

func BroadcastWebhookHandler(callback func([]BroadcastTrace)) http.HandlerFunc

BroadcastWebhookHandler returns an http.HandlerFunc that receives OTLP trace payloads from OpenRouter Broadcast webhooks. It handles test-connection pings automatically and invokes the callback with parsed traces.

func BroadcastWebhookHandlerWithError

func BroadcastWebhookHandlerWithError(callback func([]BroadcastTrace) error) http.HandlerFunc

BroadcastWebhookHandlerWithError is like BroadcastWebhookHandler but the callback may return an error, which results in an HTTP 500 response.

func BuildAuthURL

func BuildAuthURL(baseURL string, params AuthURLParams) (string, error)

BuildAuthURL constructs an OpenRouter authorization URL with the given parameters. The base URL is typically "https://openrouter.ai/auth".

Example:

verifier, _ := openrouter.GenerateCodeVerifier()
challenge := openrouter.CreateS256CodeChallenge(verifier)
authURL, _ := openrouter.BuildAuthURL("https://openrouter.ai/auth", openrouter.AuthURLParams{
    CallbackURL:         "https://myapp.com/callback",
    CodeChallenge:       challenge,
    CodeChallengeMethod: openrouter.CodeChallengeMethodS256,
})
// Redirect user to authURL

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 CreateS256CodeChallenge

func CreateS256CodeChallenge(verifier string) string

CreateS256CodeChallenge creates a PKCE code challenge from a code verifier using the S256 method: BASE64URL(SHA256(verifier)) per RFC 7636.

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 EndpointSupportsParameter

func EndpointSupportsParameter(params []string, param string) bool

EndpointSupportsParameter checks if a parameter list contains the given parameter.

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 GenerateCodeVerifier

func GenerateCodeVerifier() (string, error)

GenerateCodeVerifier generates a cryptographically random PKCE code verifier. The verifier is a 32-byte random value encoded as base64url without padding, resulting in a 43-character string per RFC 7636.

func ParsePricing

func ParsePricing(priceStr string) float64

ParsePricing parses a pricing string (e.g., "0.0025") to float64. Pricing values represent cost per million tokens. Returns 0 on error, empty string, or negative values.

func ParsePricingPtr

func ParsePricingPtr(priceStr *string) float64

ParsePricingPtr parses a *string pricing value. Returns 0 if the pointer is nil.

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]any `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 AnthropicCitation

type AnthropicCitation struct {
	// Type: "char_location", "page_location", "content_block_location",
	// "web_search_result_location", "search_result_location"
	Type string `json:"type"`

	// CitedText is the text being cited.
	CitedText string `json:"cited_text,omitempty"`

	// DocumentIndex is the index of the source document.
	DocumentIndex *int `json:"document_index,omitempty"`

	// DocumentTitle is the title of the source document.
	DocumentTitle string `json:"document_title,omitempty"`

	// StartCharIndex is the start character index (for "char_location").
	StartCharIndex *int `json:"start_char_index,omitempty"`

	// EndCharIndex is the end character index (for "char_location").
	EndCharIndex *int `json:"end_char_index,omitempty"`

	// StartPageNumber is the start page (for "page_location").
	StartPageNumber *int `json:"start_page_number,omitempty"`

	// EndPageNumber is the end page (for "page_location").
	EndPageNumber *int `json:"end_page_number,omitempty"`

	// StartBlockIndex is the start block index (for "content_block_location").
	StartBlockIndex *int `json:"start_block_index,omitempty"`

	// EndBlockIndex is the end block index (for "content_block_location").
	EndBlockIndex *int `json:"end_block_index,omitempty"`

	// URL is the source URL (for "web_search_result_location").
	URL string `json:"url,omitempty"`

	// Title is the source title (for "web_search_result_location").
	Title string `json:"title,omitempty"`
}

AnthropicCitation represents a citation in a text content block.

type AnthropicCitationsConfig

type AnthropicCitationsConfig struct {
	// Enabled enables citation generation.
	Enabled bool `json:"enabled"`
}

AnthropicCitationsConfig controls citation generation.

type AnthropicContentBlock

type AnthropicContentBlock struct {
	// Type is the content block type discriminator.
	Type string `json:"type"`

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

	// Source is the content source (for "image" and "document" types).
	Source *AnthropicContentSource `json:"source,omitempty"`

	// ID is the tool use ID (for "tool_use" type).
	ID string `json:"id,omitempty"`

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

	// Input is the tool input (for "tool_use" type).
	Input json.RawMessage `json:"input,omitempty"`

	// ToolUseID is the ID of the tool_use block being responded to (for "tool_result" type).
	ToolUseID string `json:"tool_use_id,omitempty"`

	// Content is the tool result content (for "tool_result" type). Can be string or []AnthropicContentBlock.
	ToolResultContent any `json:"content,omitempty"`

	// IsError indicates if the tool result is an error (for "tool_result" type).
	IsError *bool `json:"is_error,omitempty"`

	// Thinking is the thinking text (for "thinking" type).
	Thinking string `json:"thinking,omitempty"`

	// Signature is the thinking block signature (for "thinking" type).
	Signature string `json:"signature,omitempty"`

	// Data is redacted data (for "redacted_thinking" type).
	Data string `json:"data,omitempty"`

	// Citations configuration (for "text" type).
	Citations *AnthropicCitationsConfig `json:"citations,omitempty"`
}

AnthropicContentBlock represents a content block in a message. It is a unified struct with a Type discriminator covering text, image, document, tool_use, tool_result, thinking, and redacted_thinking.

func CreateAnthropicDocumentBase64Block

func CreateAnthropicDocumentBase64Block(mediaType string, data string) AnthropicContentBlock

CreateAnthropicDocumentBase64Block creates a document content block from base64 data.

func CreateAnthropicDocumentURLBlock

func CreateAnthropicDocumentURLBlock(url string) AnthropicContentBlock

CreateAnthropicDocumentURLBlock creates a document content block from a URL.

func CreateAnthropicImageBase64Block

func CreateAnthropicImageBase64Block(mediaType string, data string) AnthropicContentBlock

CreateAnthropicImageBase64Block creates an image content block from base64 data.

func CreateAnthropicImageURLBlock

func CreateAnthropicImageURLBlock(url string) AnthropicContentBlock

CreateAnthropicImageURLBlock creates an image content block from a URL.

func CreateAnthropicTextBlock

func CreateAnthropicTextBlock(text string) AnthropicContentBlock

CreateAnthropicTextBlock creates a text content block.

func CreateAnthropicToolResultBlock

func CreateAnthropicToolResultBlock(toolUseID string, content string) AnthropicContentBlock

CreateAnthropicToolResultBlock creates a tool_result content block.

func CreateAnthropicToolUseBlock

func CreateAnthropicToolUseBlock(id, name string, input json.RawMessage) AnthropicContentBlock

CreateAnthropicToolUseBlock creates a tool_use content block.

type AnthropicContentSource

type AnthropicContentSource struct {
	// Type is "base64" or "url".
	Type string `json:"type"`

	// MediaType is the MIME type (for base64 sources).
	MediaType string `json:"media_type,omitempty"`

	// Data is the base64-encoded data (for base64 sources).
	Data string `json:"data,omitempty"`

	// URL is the source URL (for URL sources).
	URL string `json:"url,omitempty"`
}

AnthropicContentSource represents a source for image or document content blocks.

type AnthropicMessage

type AnthropicMessage struct {
	// Role is "user" or "assistant".
	Role string `json:"role"`

	// Content can be a string or []AnthropicContentBlock.
	Content any `json:"content"`
}

AnthropicMessage represents a message in the Anthropic Messages API.

func CreateAnthropicAssistantMessage

func CreateAnthropicAssistantMessage(text string) AnthropicMessage

CreateAnthropicAssistantMessage creates an assistant message with text content.

func CreateAnthropicUserMessage

func CreateAnthropicUserMessage(text string) AnthropicMessage

CreateAnthropicUserMessage creates a user message with text content.

func CreateAnthropicUserMessageWithBlocks

func CreateAnthropicUserMessageWithBlocks(blocks []AnthropicContentBlock) AnthropicMessage

CreateAnthropicUserMessageWithBlocks creates a user message with content blocks.

type AnthropicMessagesRequest

type AnthropicMessagesRequest struct {
	// Model is the model identifier (required).
	Model string `json:"model"`

	// MaxTokens is the maximum number of tokens to generate (required).
	MaxTokens int `json:"max_tokens"`

	// Messages is the array of input messages (required).
	Messages []AnthropicMessage `json:"messages"`

	// System is an optional system prompt. Can be a string or []AnthropicTextBlock.
	System any `json:"system,omitempty"`

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

	// TopP controls nucleus sampling.
	TopP *float64 `json:"top_p,omitempty"`

	// TopK controls top-k sampling.
	TopK *int `json:"top_k,omitempty"`

	// StopSequences specifies custom stop sequences.
	StopSequences []string `json:"stop_sequences,omitempty"`

	// Stream enables streaming responses.
	Stream bool `json:"stream,omitempty"`

	// Tools defines available tools.
	Tools []AnthropicTool `json:"tools,omitempty"`

	// ToolChoice controls tool invocation behavior.
	ToolChoice *AnthropicToolChoice `json:"tool_choice,omitempty"`

	// Thinking configures extended thinking.
	Thinking *AnthropicThinkingConfig `json:"thinking,omitempty"`

	// ServiceTier specifies the service tier ("auto" or "standard").
	ServiceTier string `json:"service_tier,omitempty"`

	// Provider contains provider-specific routing parameters (reuses existing type).
	Provider *Provider `json:"provider,omitempty"`

	// Plugins configures plugins (reuses existing type).
	Plugins []Plugin `json:"plugins,omitempty"`

	// User is an optional unique identifier for the end-user.
	User string `json:"user,omitempty"`

	// SessionID is an optional session identifier for multi-turn conversations.
	SessionID string `json:"session_id,omitempty"`

	// Models specifies fallback models.
	Models []string `json:"models,omitempty"`

	// Metadata is the request body metadata (e.g., user_id).
	Metadata *AnthropicRequestMetadata `json:"metadata,omitempty"`

	// HeaderMetadata is used for X-* header injection (not serialized to JSON).
	HeaderMetadata map[string]any `json:"-"`
}

AnthropicMessagesRequest represents a request to the Anthropic Messages API via OpenRouter.

func (*AnthropicMessagesRequest) GetMetadata

func (r *AnthropicMessagesRequest) GetMetadata() map[string]any

GetMetadata returns the header metadata map for header generation.

type AnthropicMessagesResponse

type AnthropicMessagesResponse struct {
	// ID is the unique message identifier.
	ID string `json:"id"`

	// Type is always "message".
	Type string `json:"type"`

	// Role is always "assistant".
	Role string `json:"role"`

	// Content is the array of content blocks in the response.
	Content []AnthropicResponseContentBlock `json:"content"`

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

	// StopReason indicates why the model stopped generating.
	StopReason *string `json:"stop_reason"`

	// StopSequence is the stop sequence that triggered stopping, if any.
	StopSequence *string `json:"stop_sequence"`

	// Usage contains token usage information.
	Usage AnthropicUsage `json:"usage"`
}

AnthropicMessagesResponse represents a response from the Anthropic Messages API.

func (*AnthropicMessagesResponse) GetStopReason

func (r *AnthropicMessagesResponse) GetStopReason() string

GetStopReason returns the stop reason string, or empty if nil.

func (*AnthropicMessagesResponse) GetTextBlocks

func (r *AnthropicMessagesResponse) GetTextBlocks() []AnthropicResponseContentBlock

GetTextBlocks returns all text content blocks from the response.

func (*AnthropicMessagesResponse) GetTextContent

func (r *AnthropicMessagesResponse) GetTextContent() string

GetTextContent extracts all text content from the response, concatenated.

func (*AnthropicMessagesResponse) GetThinkingContent

func (r *AnthropicMessagesResponse) GetThinkingContent() string

GetThinkingContent extracts all thinking text from the response, concatenated.

func (*AnthropicMessagesResponse) GetToolUseBlocks

func (r *AnthropicMessagesResponse) GetToolUseBlocks() []AnthropicResponseContentBlock

GetToolUseBlocks returns all tool_use content blocks from the response.

func (*AnthropicMessagesResponse) IsToolUse

func (r *AnthropicMessagesResponse) IsToolUse() bool

IsToolUse returns true if the response stop reason is "tool_use".

type AnthropicOption

type AnthropicOption = RequestOption[*AnthropicMessagesRequest]

AnthropicOption is a functional option for configuring AnthropicMessagesRequest.

func WithAnthropicHeaderMetadata

func WithAnthropicHeaderMetadata(metadata map[string]any) AnthropicOption

WithAnthropicHeaderMetadata sets metadata for X-* header injection.

func WithAnthropicMaxTokens

func WithAnthropicMaxTokens(maxTokens int) AnthropicOption

WithAnthropicMaxTokens sets the maximum number of tokens to generate.

func WithAnthropicMessages

func WithAnthropicMessages(messages []AnthropicMessage) AnthropicOption

WithAnthropicMessages sets the messages for the request.

func WithAnthropicModel

func WithAnthropicModel(model string) AnthropicOption

WithAnthropicModel sets the model for the Anthropic Messages API request.

func WithAnthropicModels

func WithAnthropicModels(models ...string) AnthropicOption

WithAnthropicModels sets fallback models.

func WithAnthropicPlugins

func WithAnthropicPlugins(plugins ...Plugin) AnthropicOption

WithAnthropicPlugins sets plugin configurations.

func WithAnthropicProvider

func WithAnthropicProvider(provider Provider) AnthropicOption

WithAnthropicProvider sets provider-specific parameters.

func WithAnthropicRequestMetadata

func WithAnthropicRequestMetadata(metadata AnthropicRequestMetadata) AnthropicOption

WithAnthropicRequestMetadata sets the request body metadata.

func WithAnthropicServiceTier

func WithAnthropicServiceTier(tier string) AnthropicOption

WithAnthropicServiceTier sets the service tier.

func WithAnthropicSessionID

func WithAnthropicSessionID(sessionID string) AnthropicOption

WithAnthropicSessionID sets a session identifier for multi-turn conversations.

func WithAnthropicStopSequences

func WithAnthropicStopSequences(sequences ...string) AnthropicOption

WithAnthropicStopSequences sets custom stop sequences.

func WithAnthropicSystemBlocks

func WithAnthropicSystemBlocks(blocks []AnthropicTextBlock) AnthropicOption

WithAnthropicSystemBlocks sets a structured system prompt using text blocks.

func WithAnthropicSystemString

func WithAnthropicSystemString(system string) AnthropicOption

WithAnthropicSystemString sets a string system prompt.

func WithAnthropicTemperature

func WithAnthropicTemperature(temperature float64) AnthropicOption

WithAnthropicTemperature sets the temperature for sampling.

func WithAnthropicThinkingDisabled

func WithAnthropicThinkingDisabled() AnthropicOption

WithAnthropicThinkingDisabled explicitly disables extended thinking.

func WithAnthropicThinkingEnabled

func WithAnthropicThinkingEnabled(budgetTokens int) AnthropicOption

WithAnthropicThinkingEnabled enables extended thinking with a token budget.

func WithAnthropicToolChoiceAny

func WithAnthropicToolChoiceAny() AnthropicOption

WithAnthropicToolChoiceAny sets tool choice to "any" (force tool use).

func WithAnthropicToolChoiceAuto

func WithAnthropicToolChoiceAuto() AnthropicOption

WithAnthropicToolChoiceAuto sets tool choice to "auto".

func WithAnthropicToolChoiceNone

func WithAnthropicToolChoiceNone() AnthropicOption

WithAnthropicToolChoiceNone sets tool choice to "none".

func WithAnthropicToolChoiceSpecific

func WithAnthropicToolChoiceSpecific(name string) AnthropicOption

WithAnthropicToolChoiceSpecific forces the use of a specific tool.

func WithAnthropicTools

func WithAnthropicTools(tools ...AnthropicTool) AnthropicOption

WithAnthropicTools sets the available tools.

func WithAnthropicTopK

func WithAnthropicTopK(topK int) AnthropicOption

WithAnthropicTopK sets the top_k for sampling.

func WithAnthropicTopP

func WithAnthropicTopP(topP float64) AnthropicOption

WithAnthropicTopP sets the top_p for nucleus sampling.

func WithAnthropicUser

func WithAnthropicUser(user string) AnthropicOption

WithAnthropicUser sets a unique identifier for the end-user.

type AnthropicRequestMetadata

type AnthropicRequestMetadata struct {
	// UserID is an external identifier for the user making the request.
	UserID string `json:"user_id,omitempty"`
}

AnthropicRequestMetadata contains body-level metadata for the request.

type AnthropicResponseContentBlock

type AnthropicResponseContentBlock struct {
	// Type discriminator: "text", "tool_use", "thinking", "redacted_thinking",
	// "server_tool_use", "web_search_tool_result"
	Type string `json:"type"`

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

	// Citations for the text block.
	Citations []AnthropicCitation `json:"citations,omitempty"`

	// ID is the tool use ID (for "tool_use" and "server_tool_use" types).
	ID string `json:"id,omitempty"`

	// Name is the tool name (for "tool_use" and "server_tool_use" types).
	Name string `json:"name,omitempty"`

	// Input is the tool input (for "tool_use" and "server_tool_use" types).
	Input json.RawMessage `json:"input,omitempty"`

	// Thinking is the thinking text (for "thinking" type).
	Thinking string `json:"thinking,omitempty"`

	// Signature is the thinking block signature (for "thinking" type).
	Signature string `json:"signature,omitempty"`

	// Data is redacted data (for "redacted_thinking" type).
	Data string `json:"data,omitempty"`

	// Content is the web search result content (for "web_search_tool_result" type).
	Content json.RawMessage `json:"content,omitempty"`
}

AnthropicResponseContentBlock represents a content block in the response.

type AnthropicStream

type AnthropicStream = Stream[AnthropicStreamEvent]

AnthropicStream represents a streaming response from the Anthropic Messages API.

type AnthropicStreamDelta

type AnthropicStreamDelta struct {
	// Type: "text_delta", "input_json_delta", "thinking_delta", "signature_delta"
	Type string `json:"type,omitempty"`

	// Text is the incremental text (for "text_delta").
	Text string `json:"text,omitempty"`

	// PartialJSON is the incremental JSON (for "input_json_delta").
	PartialJSON string `json:"partial_json,omitempty"`

	// Thinking is the incremental thinking text (for "thinking_delta").
	Thinking string `json:"thinking,omitempty"`

	// Signature is the signature (for "signature_delta").
	Signature string `json:"signature,omitempty"`

	// StopReason is set on "message_delta" events.
	StopReason string `json:"stop_reason,omitempty"`

	// StopSequence is set on "message_delta" events.
	StopSequence string `json:"stop_sequence,omitempty"`
}

AnthropicStreamDelta represents incremental content in a streaming event.

type AnthropicStreamError

type AnthropicStreamError struct {
	Type    string `json:"type"`
	Message string `json:"message"`
}

AnthropicStreamError contains error information in streaming events.

type AnthropicStreamEvent

type AnthropicStreamEvent struct {
	// Type: "message_start", "content_block_start", "content_block_delta",
	// "content_block_stop", "message_delta", "message_stop", "ping", "error"
	Type string `json:"type"`

	// Message is the full message object (for "message_start").
	Message *AnthropicMessagesResponse `json:"message,omitempty"`

	// Index is the content block index (for content_block_* events).
	Index *int `json:"index,omitempty"`

	// ContentBlock is the content block being started (for "content_block_start").
	ContentBlock *AnthropicResponseContentBlock `json:"content_block,omitempty"`

	// Delta contains incremental content (for "content_block_delta" and "message_delta").
	Delta *AnthropicStreamDelta `json:"delta,omitempty"`

	// Usage contains updated usage info (for "message_delta").
	Usage *AnthropicStreamUsage `json:"usage,omitempty"`

	// Error contains error information (for "error" events).
	Error *AnthropicStreamError `json:"error,omitempty"`
}

AnthropicStreamEvent represents a single event in the Anthropic streaming response.

func (*AnthropicStreamEvent) GetTextDelta

func (e *AnthropicStreamEvent) GetTextDelta() string

GetTextDelta extracts the text delta from a streaming event.

type AnthropicStreamUsage

type AnthropicStreamUsage struct {
	InputTokens  int `json:"input_tokens,omitempty"`
	OutputTokens int `json:"output_tokens,omitempty"`
}

AnthropicStreamUsage contains usage information in streaming events.

type AnthropicTextBlock

type AnthropicTextBlock struct {
	Type string `json:"type"`
	Text string `json:"text"`
}

AnthropicTextBlock represents a text block used in system prompts.

type AnthropicThinkingConfig

type AnthropicThinkingConfig struct {
	// Type is "enabled" or "disabled".
	Type string `json:"type"`

	// BudgetTokens is the maximum number of thinking tokens (required when Type is "enabled").
	BudgetTokens int `json:"budget_tokens,omitempty"`
}

AnthropicThinkingConfig configures extended thinking.

type AnthropicTool

type AnthropicTool struct {
	// Type is the tool type. For custom tools, omit or set to empty.
	// Built-in types: "bash_20250124", "text_editor_20250124", "web_search_20250305"
	Type string `json:"type,omitempty"`

	// Name is the tool name (required for custom tools).
	Name string `json:"name,omitempty"`

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

	// InputSchema is the JSON Schema for the tool parameters (custom tools).
	InputSchema map[string]any `json:"input_schema,omitempty"`

	// MaxUses limits the number of times the tool can be used (for web_search).
	MaxUses *int `json:"max_uses,omitempty"`
}

AnthropicTool represents a tool definition for the Anthropic API.

func CreateAnthropicBashTool

func CreateAnthropicBashTool() AnthropicTool

CreateAnthropicBashTool creates a bash tool definition.

func CreateAnthropicCustomTool

func CreateAnthropicCustomTool(name, description string, schema map[string]any) AnthropicTool

CreateAnthropicCustomTool creates a custom tool definition.

func CreateAnthropicTextEditorTool

func CreateAnthropicTextEditorTool() AnthropicTool

CreateAnthropicTextEditorTool creates a text editor tool definition.

func CreateAnthropicWebSearchTool

func CreateAnthropicWebSearchTool(maxUses *int) AnthropicTool

CreateAnthropicWebSearchTool creates a web search tool definition.

type AnthropicToolChoice

type AnthropicToolChoice struct {
	// Type is "auto", "any", "none", or "tool".
	Type string `json:"type"`

	// Name is the tool name (only when Type is "tool").
	Name string `json:"name,omitempty"`

	// DisableParallelToolUse disables parallel tool calling.
	DisableParallelToolUse *bool `json:"disable_parallel_tool_use,omitempty"`
}

AnthropicToolChoice controls tool invocation behavior.

type AnthropicUsage

type AnthropicUsage struct {
	InputTokens              int    `json:"input_tokens"`
	OutputTokens             int    `json:"output_tokens"`
	CacheCreationInputTokens int    `json:"cache_creation_input_tokens,omitempty"`
	CacheReadInputTokens     int    `json:"cache_read_input_tokens,omitempty"`
	ServiceTier              string `json:"service_tier,omitempty"`
}

AnthropicUsage contains token usage information.

type AssignKeysRequest

type AssignKeysRequest struct {
	KeyHashes []string `json:"key_hashes"`
}

AssignKeysRequest represents a request to assign keys to a guardrail.

type AssignKeysResponse

type AssignKeysResponse struct {
	AssignedCount int `json:"assigned_count"`
}

AssignKeysResponse represents the response from assigning keys to a guardrail.

type AssignMembersRequest

type AssignMembersRequest struct {
	MemberUserIDs []string `json:"member_user_ids"`
}

AssignMembersRequest represents a request to assign members to a guardrail.

type AssignMembersResponse

type AssignMembersResponse struct {
	AssignedCount int `json:"assigned_count"`
}

AssignMembersResponse represents the response from assigning members to a guardrail.

type AuthURLParams

type AuthURLParams struct {
	// CallbackURL is the URL that OpenRouter will redirect to after authorization (required).
	CallbackURL string
	// CodeChallenge is the PKCE code challenge (optional).
	CodeChallenge string
	// CodeChallengeMethod is the method used to generate the code challenge (optional).
	CodeChallengeMethod CodeChallengeMethod
}

AuthURLParams contains the parameters for building an OpenRouter authorization URL.

type BroadcastTrace

type BroadcastTrace struct {
	TraceID      string
	SpanID       string
	ParentSpanID string
	SpanName     string

	StartTime time.Time
	EndTime   time.Time
	Duration  time.Duration

	// Deprecated: Use InputTokens instead. Still populated for backward compatibility.
	PromptTokens int
	// Deprecated: Use OutputTokens instead. Still populated for backward compatibility.
	CompletionTokens int
	TotalTokens      int
	// Deprecated: Use TotalCost instead. Still populated for backward compatibility.
	Cost float64
	// Deprecated: Use ResponseModel instead. Still populated for backward compatibility.
	Model string

	// Token usage fields (new canonical names).
	InputTokens  int // gen_ai.usage.input_tokens
	OutputTokens int // gen_ai.usage.output_tokens

	// Cost breakdown fields.
	TotalCost  float64 // gen_ai.usage.total_cost
	InputCost  float64 // gen_ai.usage.input_cost
	OutputCost float64 // gen_ai.usage.output_cost

	// Token detail fields.
	CachedTokens      int // gen_ai.usage.input_tokens.cached
	AudioInputTokens  int // gen_ai.usage.input_tokens.audio
	VideoInputTokens  int // gen_ai.usage.input_tokens.video
	ImageOutputTokens int // gen_ai.usage.output_tokens.image
	ReasoningTokens   int // gen_ai.usage.output_tokens.reasoning

	// GenAI semantic convention fields.
	OperationName string // gen_ai.operation.name
	System        string // gen_ai.system
	ProviderName  string // gen_ai.provider.name
	ResponseModel string // gen_ai.response.model
	FinishReason  string // gen_ai.response.finish_reason
	FinishReasons string // gen_ai.response.finish_reasons (JSON array)
	RequestModel  string // gen_ai.request.model

	// OpenRouter-specific fields.
	ProviderSlug           string  // openrouter.provider_slug
	OpenRouterProviderName string  // openrouter.provider_name
	APIKeyName             string  // openrouter.api_key_name
	EntityID               string  // openrouter.entity_id
	OpenRouterUserID       string  // openrouter.user_id
	OpenRouterFinishReason string  // openrouter.finish_reason
	InputUnitPrice         float64 // openrouter.input_unit_price
	OutputUnitPrice        float64 // openrouter.output_unit_price
	Source                 string  // openrouter.source

	// Content fields.
	Prompt     string // gen_ai.prompt
	Completion string // gen_ai.completion

	// Span-level fields.
	SpanType   string // span.type
	SpanLevel  string // span.level
	SpanInput  string // span.input
	SpanOutput string // span.output

	// Trace-level fields.
	TraceName   string // trace.name
	TraceInput  string // trace.input
	TraceOutput string // trace.output
	TraceTags   string // trace.tags (JSON array)

	UserID    string
	SessionID string

	// Metadata contains values from trace.metadata.* attributes (prefix stripped).
	Metadata map[string]string
	// SpanMetadata contains values from span.metadata.* attributes (prefix stripped).
	SpanMetadata map[string]string
	// ResourceAttributes contains attributes from the OTLP resource.
	ResourceAttributes map[string]string
	// RawAttributes contains all other span attributes not mapped to named fields.
	RawAttributes map[string]string
}

BroadcastTrace is a user-friendly representation of a single span extracted from an OTLP trace payload sent by OpenRouter Broadcast.

func ExtractBroadcastTraces

func ExtractBroadcastTraces(payload *OTLPExportTraceRequest) []BroadcastTrace

ExtractBroadcastTraces converts an OTLP payload into user-friendly BroadcastTrace values. Missing attributes produce zero values; extraction is best-effort.

func ParseBroadcastTraces

func ParseBroadcastTraces(data []byte) ([]BroadcastTrace, error)

ParseBroadcastTraces is a convenience function that parses raw JSON and extracts traces in one call.

type BulkAddWorkspaceMembersResponse

type BulkAddWorkspaceMembersResponse struct {
	AddedCount int               `json:"added_count"`
	Data       []WorkspaceMember `json:"data"`
}

BulkAddWorkspaceMembersResponse is the response from bulk-adding workspace members.

type BulkRemoveWorkspaceMembersResponse

type BulkRemoveWorkspaceMembersResponse struct {
	RemovedCount int `json:"removed_count"`
}

BulkRemoveWorkspaceMembersResponse is the response from bulk-removing workspace members.

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]any) 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]any) ChatCompletionOption

WithMetadata sets metadata headers for the request.

func WithMinP

func WithMinP(minP float64) ChatCompletionOption

WithMinP sets the min_p parameter for nucleus sampling.

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 WithRequestRetry

func WithRequestRetry(maxRetries int, retryDelay time.Duration) ChatCompletionOption

WithRequestRetry sets per-request retry configuration that overrides the client-level retry settings.

func WithRequestTimeout

func WithRequestTimeout(timeout time.Duration) ChatCompletionOption

WithRequestTimeout sets a per-request timeout that overrides the client-level timeout. The timeout applies to the full request lifecycle for non-streaming calls, and to the connection setup phase for streaming calls.

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 WithStreamChannelBuffer

func WithStreamChannelBuffer(n int) ChatCompletionOption

WithStreamChannelBuffer sets the events channel buffer size for this request.

func WithStreamMaxBackoff

func WithStreamMaxBackoff(d time.Duration) ChatCompletionOption

WithStreamMaxBackoff sets the maximum backoff duration for stream reconnection for this request.

func WithStreamMaxRetries

func WithStreamMaxRetries(n int) ChatCompletionOption

WithStreamMaxRetries sets the maximum number of stream reconnection retries for this request.

func WithTemperature

func WithTemperature(temperature float64) ChatCompletionOption

WithTemperature sets the temperature parameter.

func WithToolChoice

func WithToolChoice(toolChoice any) ChatCompletionOption

WithToolChoice sets the tool choice strategy.

func WithTools

func WithTools(tools ...Tool) ChatCompletionOption

WithTools sets the available tools/functions.

func WithTopA

func WithTopA(topA float64) ChatCompletionOption

WithTopA sets the top_a parameter for top-a sampling.

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        any               `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]any    `json:"-"` // Used for headers
	// contains filtered or unexported fields
}

ChatCompletionRequest represents a chat completion request to the OpenRouter API.

func (*ChatCompletionRequest) GetMetadata

func (r *ChatCompletionRequest) GetMetadata() map[string]any

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 CircuitBreaker

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

CircuitBreaker implements the circuit breaker pattern for stream reconnection.

func NewCircuitBreaker

func NewCircuitBreaker(config *CircuitBreakerConfig) *CircuitBreaker

NewCircuitBreaker creates a new CircuitBreaker with the given configuration. If config is nil, DefaultCircuitBreakerConfig is used.

func (*CircuitBreaker) AllowRequest

func (cb *CircuitBreaker) AllowRequest() bool

AllowRequest returns true if the circuit breaker allows a request to proceed.

func (*CircuitBreaker) RecordFailure

func (cb *CircuitBreaker) RecordFailure()

RecordFailure records a failed request and may open the circuit.

func (*CircuitBreaker) RecordSuccess

func (cb *CircuitBreaker) RecordSuccess()

RecordSuccess records a successful request and resets the circuit breaker.

func (*CircuitBreaker) Reset

func (cb *CircuitBreaker) Reset()

Reset resets the circuit breaker to its initial closed state.

func (*CircuitBreaker) State

func (cb *CircuitBreaker) State() CircuitState

State returns the current state of the circuit breaker.

type CircuitBreakerConfig

type CircuitBreakerConfig struct {
	// FailureThreshold is the number of consecutive failures before opening the circuit. Default: 5.
	FailureThreshold int
	// ResetTimeout is how long to wait before transitioning from open to half-open. Default: 30s.
	ResetTimeout time.Duration
	// HalfOpenMaxAttempts is the number of test requests allowed in half-open state. Default: 1.
	HalfOpenMaxAttempts int
}

CircuitBreakerConfig configures the circuit breaker behavior.

func DefaultCircuitBreakerConfig

func DefaultCircuitBreakerConfig() *CircuitBreakerConfig

DefaultCircuitBreakerConfig returns the default circuit breaker configuration.

type CircuitBreakerError

type CircuitBreakerError struct {
	State   CircuitState
	Message string
}

CircuitBreakerError is returned when a request is blocked by the circuit breaker.

func IsCircuitBreakerError

func IsCircuitBreakerError(err error) (*CircuitBreakerError, bool)

IsCircuitBreakerError checks if an error is a CircuitBreakerError and returns it.

func (*CircuitBreakerError) Error

func (e *CircuitBreakerError) Error() string

Error implements the error interface.

type CircuitState

type CircuitState int

CircuitState represents the current state of the circuit breaker.

const (
	// CircuitClosed allows requests to pass through normally.
	CircuitClosed CircuitState = iota
	// CircuitOpen blocks requests due to repeated failures.
	CircuitOpen
	// CircuitHalfOpen allows a limited number of test requests.
	CircuitHalfOpen
)

func (CircuitState) String

func (s CircuitState) String() string

String returns the string representation of the circuit state.

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

func (c *Client) AddWorkspaceMembers(ctx context.Context, idOrSlug string, userIDs []string) (*BulkAddWorkspaceMembersResponse, error)

AddWorkspaceMembers adds multiple organization members to a workspace. Members are assigned the same role they hold in the organization. Requires a Management (Provisioning) API key.

func (*Client) AssignKeysToGuardrail

func (c *Client) AssignKeysToGuardrail(ctx context.Context, id string, request *AssignKeysRequest) (*AssignKeysResponse, error)

AssignKeysToGuardrail assigns API keys to a guardrail by their hashes. Requires a Provisioning API key.

func (*Client) AssignMembersToGuardrail

func (c *Client) AssignMembersToGuardrail(ctx context.Context, id string, request *AssignMembersRequest) (*AssignMembersResponse, error)

AssignMembersToGuardrail assigns members to a guardrail by their user IDs. Requires a Provisioning API key.

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

func (c *Client) CreateAnthropicMessage(ctx context.Context, messages []AnthropicMessage, opts ...AnthropicOption) (*AnthropicMessagesResponse, error)

CreateAnthropicMessage sends a request to the Anthropic Messages API via OpenRouter.

Example:

messages := []openrouter.AnthropicMessage{
    openrouter.CreateAnthropicUserMessage("Hello!"),
}
resp, err := client.CreateAnthropicMessage(ctx, messages,
    openrouter.WithAnthropicModel("anthropic/claude-sonnet-4"),
    openrouter.WithAnthropicMaxTokens(1024),
)

func (*Client) CreateAnthropicMessageStream

func (c *Client) CreateAnthropicMessageStream(ctx context.Context, messages []AnthropicMessage, opts ...AnthropicOption) (*AnthropicStream, error)

CreateAnthropicMessageStream sends a streaming request to the Anthropic Messages API via OpenRouter.

Example:

messages := []openrouter.AnthropicMessage{
    openrouter.CreateAnthropicUserMessage("Tell me a story"),
}
stream, err := client.CreateAnthropicMessageStream(ctx, messages,
    openrouter.WithAnthropicModel("anthropic/claude-sonnet-4"),
    openrouter.WithAnthropicMaxTokens(1024),
)
if err != nil {
    log.Fatal(err)
}
defer stream.Close()

for event := range stream.Events() {
    fmt.Print(event.GetTextDelta())
}

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 any, 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) CreateGuardrail

func (c *Client) CreateGuardrail(ctx context.Context, request *CreateGuardrailRequest) (*Guardrail, error)

CreateGuardrail creates a new guardrail with the specified configuration. Requires a Provisioning API key.

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 any, 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 any, 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) CreateSpeech

func (c *Client) CreateSpeech(ctx context.Context, input, model, voice string, opts ...SpeechOption) (*SpeechResponse, error)

CreateSpeech synthesizes audio from the given input text using the specified model and voice. It returns the raw audio bytes along with the server's Content-Type and the resolved format.

func (*Client) CreateVideo

func (c *Client) CreateVideo(ctx context.Context, model, prompt string, opts ...VideoGenerationOption) (*VideoGenerationResponse, error)

CreateVideo submits a video generation job and returns the initial response (including the job ID and polling URL). Callers should poll GetVideo with the returned ID until Status is terminal (VideoStatusCompleted, VideoStatusFailed, VideoStatusCancelled, or VideoStatusExpired).

func (*Client) CreateWorkspace

func (c *Client) CreateWorkspace(ctx context.Context, req *CreateWorkspaceRequest) (*CreateWorkspaceResponse, error)

CreateWorkspace creates a new workspace. Requires a Management (Provisioning) API key.

func (*Client) DeleteGuardrail

func (c *Client) DeleteGuardrail(ctx context.Context, id string) (*DeleteGuardrailResponse, error)

DeleteGuardrail deletes a guardrail by its ID. Requires a Provisioning API key. WARNING: This operation is irreversible!

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

func (c *Client) DeleteWorkspace(ctx context.Context, idOrSlug string) (*DeleteWorkspaceResponse, error)

DeleteWorkspace deletes a workspace by ID (UUID) or slug. The default workspace cannot be deleted. Workspaces with active API keys cannot be deleted. Requires a Management (Provisioning) API key.

func (*Client) ExchangeAuthCode

func (c *Client) ExchangeAuthCode(ctx context.Context, request *ExchangeAuthCodeRequest) (*ExchangeAuthCodeResponse, error)

ExchangeAuthCode exchanges an authorization code for an API key. This is the second step of the OAuth PKCE flow, called after the user has authorized the application at OpenRouter and been redirected back with an authorization code.

If PKCE was used when creating the auth code, the code_verifier must be provided to complete the exchange.

Example:

ctx := context.Background()
verifier := "your-code-verifier"
resp, err := client.ExchangeAuthCode(ctx, &openrouter.ExchangeAuthCodeRequest{
    Code:                "auth-code-from-callback",
    CodeVerifier:        &verifier,
    CodeChallengeMethod: openrouter.CodeChallengeMethodS256,
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("API Key: %s\n", resp.Key)

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

func (c *Client) GetGuardrail(ctx context.Context, id string) (*Guardrail, error)

GetGuardrail retrieves details about a specific guardrail by its ID. Requires a Provisioning API key.

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

func (c *Client) GetVideo(ctx context.Context, jobID string) (*VideoGenerationResponse, error)

GetVideo returns the current status of a video generation job.

func (*Client) GetVideoContent

func (c *Client) GetVideoContent(ctx context.Context, jobID string, index int) (*VideoContentResponse, error)

GetVideoContent downloads the generated video bytes for a completed job. Use index to select a specific output when the provider produced multiple videos; pass 0 to fetch the default (first) output.

func (*Client) GetWorkspace

func (c *Client) GetWorkspace(ctx context.Context, idOrSlug string) (*GetWorkspaceResponse, error)

GetWorkspace retrieves a single workspace by ID (UUID) or slug. Requires a Management (Provisioning) API key.

func (*Client) ListAllKeyAssignments

func (c *Client) ListAllKeyAssignments(ctx context.Context, options *ListGuardrailsOptions) (*ListGuardrailKeyAssignmentsResponse, error)

ListAllKeyAssignments returns all key assignments across all guardrails. Requires a Provisioning API key.

func (*Client) ListAllMemberAssignments

func (c *Client) ListAllMemberAssignments(ctx context.Context, options *ListGuardrailsOptions) (*ListGuardrailMemberAssignmentsResponse, error)

ListAllMemberAssignments returns all member assignments across all guardrails. Requires a Provisioning API key.

func (*Client) ListEmbeddingsModels

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

ListEmbeddingsModels retrieves a list of available embedding models.

func (*Client) ListGuardrailKeyAssignments

func (c *Client) ListGuardrailKeyAssignments(ctx context.Context, id string, options *ListGuardrailsOptions) (*ListGuardrailKeyAssignmentsResponse, error)

ListGuardrailKeyAssignments returns key assignments for a specific guardrail. Requires a Provisioning API key.

func (*Client) ListGuardrailMemberAssignments

func (c *Client) ListGuardrailMemberAssignments(ctx context.Context, id string, options *ListGuardrailsOptions) (*ListGuardrailMemberAssignmentsResponse, error)

ListGuardrailMemberAssignments returns member assignments for a specific guardrail. Requires a Provisioning API key.

func (*Client) ListGuardrails

func (c *Client) ListGuardrails(ctx context.Context, options *ListGuardrailsOptions) (*ListGuardrailsResponse, error)

ListGuardrails returns a list of all guardrails for the organization. Requires a Provisioning API key.

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

func (c *Client) ListModelsUser(ctx context.Context) (*ModelsResponse, error)

ListModelsUser retrieves a list of models filtered by the authenticated user's provider preferences, privacy settings, and guardrails. Requires authentication via API key. If the client is configured with an EU base URL (eu.openrouter.ai), results will be filtered to models that satisfy EU in-region routing.

func (*Client) ListOrganizationMembers

func (c *Client) ListOrganizationMembers(ctx context.Context, options *ListOrganizationMembersOptions) (*ListOrganizationMembersResponse, error)

ListOrganizationMembers returns a paginated list of members in the organization associated with the authenticated management key. Requires a Provisioning API key.

Example:

ctx := context.Background()
resp, err := client.ListOrganizationMembers(ctx, nil)
if err != nil {
    log.Fatal(err)
}
for _, m := range resp.Data {
    fmt.Printf("%s (%s)\n", m.Email, m.Role)
}

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

func (c *Client) ListVideoModels(ctx context.Context) (*VideoModelsResponse, error)

ListVideoModels returns the list of available video generation models and their capabilities.

func (*Client) ListWorkspaces

func (c *Client) ListWorkspaces(ctx context.Context, options *ListWorkspacesOptions) (*ListWorkspacesResponse, error)

ListWorkspaces returns a paginated list of workspaces for the authenticated user. Requires a Management (Provisioning) API key.

func (*Client) ListZDREndpoints

func (c *Client) ListZDREndpoints(ctx context.Context) (*ZDREndpointsResponse, error)

ListZDREndpoints retrieves the list of endpoints compatible with Zero Data Retention. This endpoint previews the impact of ZDR on available endpoints across all models.

func (*Client) RemoveWorkspaceMembers

func (c *Client) RemoveWorkspaceMembers(ctx context.Context, idOrSlug string, userIDs []string) (*BulkRemoveWorkspaceMembersResponse, error)

RemoveWorkspaceMembers removes multiple members from a workspace. Members with active API keys in the workspace cannot be removed. Requires a Management (Provisioning) API key.

func (*Client) Rerank

func (c *Client) Rerank(ctx context.Context, query string, documents []string, model string, opts ...RerankOption) (*RerankResponse, error)

Rerank sends a rerank request to the OpenRouter API. It reranks the given documents by relevance to the query using the specified model.

func (*Client) UnassignKeysFromGuardrail

func (c *Client) UnassignKeysFromGuardrail(ctx context.Context, id string, request *AssignKeysRequest) error

UnassignKeysFromGuardrail removes API key assignments from a guardrail. Requires a Provisioning API key.

func (*Client) UnassignMembersFromGuardrail

func (c *Client) UnassignMembersFromGuardrail(ctx context.Context, id string, request *AssignMembersRequest) error

UnassignMembersFromGuardrail removes member assignments from a guardrail. Requires a Provisioning API key.

func (*Client) UpdateGuardrail

func (c *Client) UpdateGuardrail(ctx context.Context, id string, request *UpdateGuardrailRequest) (*Guardrail, error)

UpdateGuardrail updates an existing guardrail by its ID. Requires a Provisioning API key. All fields in the request are optional - only include the fields you want to update.

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,
})

func (*Client) UpdateWorkspace

func (c *Client) UpdateWorkspace(ctx context.Context, idOrSlug string, req *UpdateWorkspaceRequest) (*UpdateWorkspaceResponse, error)

UpdateWorkspace updates an existing workspace by ID (UUID) or slug. Requires a Management (Provisioning) API key.

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 WithCircuitBreaker

func WithCircuitBreaker(config *CircuitBreakerConfig) ClientOption

WithCircuitBreaker enables a circuit breaker for stream reconnections. The circuit breaker tracks consecutive failures and stops reconnection attempts when the failure threshold is reached.

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 WithStreamConfig

func WithStreamConfig(config *StreamConfig) ClientOption

WithStreamConfig sets the stream configuration for the client. This controls stream reconnection behavior and channel buffering.

func WithTimeout

func WithTimeout(timeout time.Duration) ClientOption

WithTimeout sets the HTTP client timeout.

type CodeChallengeMethod

type CodeChallengeMethod string

CodeChallengeMethod represents the PKCE code challenge method.

const (
	// CodeChallengeMethodS256 uses SHA-256 hashing per RFC 7636.
	CodeChallengeMethodS256 CodeChallengeMethod = "S256"
	// CodeChallengeMethodPlain uses the plain verifier as the challenge.
	CodeChallengeMethodPlain CodeChallengeMethod = "plain"
)

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 WithCompletionFrequencyPenalty

func WithCompletionFrequencyPenalty(penalty float64) CompletionOption

WithCompletionFrequencyPenalty sets the frequency penalty for completion.

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]any) 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]any) CompletionOption

WithCompletionMetadata sets metadata headers for the completion request.

func WithCompletionMinP

func WithCompletionMinP(minP float64) CompletionOption

WithCompletionMinP sets the min_p parameter for completion.

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 WithCompletionPresencePenalty

func WithCompletionPresencePenalty(penalty float64) CompletionOption

WithCompletionPresencePenalty sets the presence penalty for completion.

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 WithCompletionRepetitionPenalty

func WithCompletionRepetitionPenalty(penalty float64) CompletionOption

WithCompletionRepetitionPenalty sets the repetition penalty for completion.

func WithCompletionRequestRetry

func WithCompletionRequestRetry(maxRetries int, retryDelay time.Duration) CompletionOption

WithCompletionRequestRetry sets per-request retry configuration for completion requests.

func WithCompletionRequestTimeout

func WithCompletionRequestTimeout(timeout time.Duration) CompletionOption

WithCompletionRequestTimeout sets a per-request timeout for completion requests.

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 WithCompletionSeed

func WithCompletionSeed(seed int) CompletionOption

WithCompletionSeed sets the random seed for completion.

func WithCompletionStop

func WithCompletionStop(stop ...string) CompletionOption

WithCompletionStop sets stop sequences for completion.

func WithCompletionStreamChannelBuffer

func WithCompletionStreamChannelBuffer(n int) CompletionOption

WithCompletionStreamChannelBuffer sets the events channel buffer size for this completion request.

func WithCompletionStreamMaxBackoff

func WithCompletionStreamMaxBackoff(d time.Duration) CompletionOption

WithCompletionStreamMaxBackoff sets the maximum backoff duration for stream reconnection for this completion request.

func WithCompletionStreamMaxRetries

func WithCompletionStreamMaxRetries(n int) CompletionOption

WithCompletionStreamMaxRetries sets the maximum number of stream reconnection retries for this completion request.

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 WithCompletionTopA

func WithCompletionTopA(topA float64) CompletionOption

WithCompletionTopA sets the top_a parameter for completion.

func WithCompletionTopK

func WithCompletionTopK(topK int) CompletionOption

WithCompletionTopK sets the top_k parameter 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]any    `json:"-"` // Used for headers
	// contains filtered or unexported fields
}

CompletionRequest represents a legacy completion request to the OpenRouter API.

func (*CompletionRequest) GetMetadata

func (r *CompletionRequest) GetMetadata() map[string]any

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 CostResult

type CostResult struct {
	// PromptCost is the cost for prompt/input tokens.
	PromptCost float64
	// CompletionCost is the cost for completion/output tokens.
	CompletionCost float64
	// TotalCost is the sum of PromptCost and CompletionCost.
	TotalCost float64
}

CostResult holds a cost breakdown for a request.

func EstimateCost

func EstimateCost(pricing ModelPricing, usage Usage) CostResult

EstimateCost calculates the estimated cost from ModelPricing and Usage. Pricing values are per-million tokens: cost = tokens * price / 1,000,000.

func EstimateCostFromTokens

func EstimateCostFromTokens(promptPrice, completionPrice string, promptTokens, completionTokens int) CostResult

EstimateCostFromTokens calculates cost from raw pricing strings and token counts. This is useful when you don't have the full ModelPricing and Usage structs.

func EstimateCostWithCaching

func EstimateCostWithCaching(pricing ModelPricing, usage Usage, cacheReadTokens, cacheWriteTokens int) CostResult

EstimateCostWithCaching calculates cost including cache read/write tokens. Cache read tokens are typically cheaper than regular prompt tokens, and cache write tokens may have a different price as well.

type CreateGuardrailRequest

type CreateGuardrailRequest struct {
	Name             string         `json:"name"`
	Description      *string        `json:"description,omitempty"`
	LimitUSD         *float64       `json:"limit_usd,omitempty"`
	ResetInterval    *ResetInterval `json:"reset_interval,omitempty"`
	AllowedProviders []string       `json:"allowed_providers,omitempty"`
	AllowedModels    []string       `json:"allowed_models,omitempty"`
	EnforceZDR       *bool          `json:"enforce_zdr,omitempty"`
}

CreateGuardrailRequest represents a request to create a new guardrail.

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 CreateWorkspaceRequest

type CreateWorkspaceRequest struct {
	Name                            string   `json:"name"`
	Slug                            string   `json:"slug"`
	Description                     *string  `json:"description,omitempty"`
	DefaultTextModel                *string  `json:"default_text_model,omitempty"`
	DefaultImageModel               *string  `json:"default_image_model,omitempty"`
	DefaultProviderSort             *string  `json:"default_provider_sort,omitempty"`
	IOLoggingAPIKeyIDs              *[]int   `json:"io_logging_api_key_ids,omitempty"`
	IOLoggingSamplingRate           *float64 `json:"io_logging_sampling_rate,omitempty"`
	IsDataDiscountLoggingEnabled    *bool    `json:"is_data_discount_logging_enabled,omitempty"`
	IsObservabilityBroadcastEnabled *bool    `json:"is_observability_broadcast_enabled,omitempty"`
	IsObservabilityIOLoggingEnabled *bool    `json:"is_observability_io_logging_enabled,omitempty"`
}

CreateWorkspaceRequest is the payload for creating a workspace. Name and Slug are required. All other fields are optional.

type CreateWorkspaceResponse

type CreateWorkspaceResponse struct {
	Data Workspace `json:"data"`
}

CreateWorkspaceResponse is the response from creating a workspace.

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 DeleteGuardrailResponse

type DeleteGuardrailResponse struct {
	Deleted bool `json:"deleted"`
}

DeleteGuardrailResponse represents the response from deleting a guardrail.

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 DeleteWorkspaceResponse

type DeleteWorkspaceResponse struct {
	Deleted bool `json:"deleted"`
}

DeleteWorkspaceResponse is the response from deleting a workspace.

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 any `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 any `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 EndpointFilter

type EndpointFilter struct {
	// ProviderName filters by provider name (exact match).
	ProviderName string
	// RequiredParameters filters to endpoints supporting all listed parameters.
	RequiredParameters []string
	// MaxPromptPrice filters to endpoints with prompt price at or below this value (per million tokens).
	// Zero means no filter.
	MaxPromptPrice float64
	// MaxCompletionPrice filters to endpoints with completion price at or below this value (per million tokens).
	// Zero means no filter.
	MaxCompletionPrice float64
	// MinStatus filters to endpoints with status at or above this value.
	// Zero means no filter.
	MinStatus float64
	// Quantization filters by quantization type (exact match).
	Quantization string
}

EndpointFilter defines criteria for filtering model endpoints.

type ErrorResponse

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

ErrorResponse represents an error response from the OpenRouter API.

type ExchangeAuthCodeRequest

type ExchangeAuthCodeRequest struct {
	Code                string              `json:"code"`
	CodeVerifier        *string             `json:"code_verifier,omitempty"`
	CodeChallengeMethod CodeChallengeMethod `json:"code_challenge_method,omitempty"`
}

ExchangeAuthCodeRequest represents a request to exchange an authorization code for an API key.

type ExchangeAuthCodeResponse

type ExchangeAuthCodeResponse struct {
	Key    string  `json:"key"`
	UserID *string `json:"user_id"`
}

ExchangeAuthCodeResponse represents the response from exchanging an authorization code.

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]any `json:"metadata,omitempty"`
}

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

type FlexInt

type FlexInt string

FlexInt is a string-backed integer that can unmarshal from both a JSON string ("150") and a JSON number (150).

func (FlexInt) MarshalJSON

func (f FlexInt) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler, encoding as a JSON string per the OTLP spec.

func (FlexInt) String

func (f FlexInt) String() string

String returns the string representation.

func (*FlexInt) UnmarshalJSON

func (f *FlexInt) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler for FlexInt.

type Function

type Function struct {
	Name        string         `json:"name"`
	Description string         `json:"description,omitempty"`
	Parameters  map[string]any `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 GetWorkspaceResponse

type GetWorkspaceResponse struct {
	Data Workspace `json:"data"`
}

GetWorkspaceResponse is the response from getting a single workspace.

type Guardrail

type Guardrail struct {
	ID               string         `json:"id"`
	Name             string         `json:"name"`
	Description      *string        `json:"description"`
	LimitUSD         *float64       `json:"limit_usd"`
	ResetInterval    *ResetInterval `json:"reset_interval"`
	AllowedProviders []string       `json:"allowed_providers"`
	AllowedModels    []string       `json:"allowed_models"`
	EnforceZDR       *bool          `json:"enforce_zdr"`
	CreatedAt        string         `json:"created_at"`
	UpdatedAt        *string        `json:"updated_at"`
}

Guardrail represents a guardrail configuration for controlling spending, model access, and data policies.

type GuardrailKeyAssignment

type GuardrailKeyAssignment struct {
	ID             string  `json:"id"`
	KeyHash        string  `json:"key_hash"`
	OrganizationID string  `json:"organization_id"`
	GuardrailID    string  `json:"guardrail_id"`
	AssignedBy     *string `json:"assigned_by"`
	CreatedAt      string  `json:"created_at"`
}

GuardrailKeyAssignment represents a key assignment to a guardrail.

type GuardrailMemberAssignment

type GuardrailMemberAssignment struct {
	ID             string  `json:"id"`
	UserID         string  `json:"user_id"`
	OrganizationID string  `json:"organization_id"`
	GuardrailID    string  `json:"guardrail_id"`
	AssignedBy     *string `json:"assigned_by"`
	CreatedAt      string  `json:"created_at"`
}

GuardrailMemberAssignment represents a member assignment to a guardrail.

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]any `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 ListGuardrailKeyAssignmentsResponse

type ListGuardrailKeyAssignmentsResponse struct {
	Data       []GuardrailKeyAssignment `json:"data"`
	TotalCount int                      `json:"total_count"`
}

ListGuardrailKeyAssignmentsResponse represents the response from listing guardrail key assignments.

type ListGuardrailMemberAssignmentsResponse

type ListGuardrailMemberAssignmentsResponse struct {
	Data       []GuardrailMemberAssignment `json:"data"`
	TotalCount int                         `json:"total_count"`
}

ListGuardrailMemberAssignmentsResponse represents the response from listing guardrail member assignments.

type ListGuardrailsOptions

type ListGuardrailsOptions struct {
	Offset *int
	Limit  *int
}

ListGuardrailsOptions represents options for listing guardrails.

type ListGuardrailsResponse

type ListGuardrailsResponse struct {
	Data       []Guardrail `json:"data"`
	TotalCount int         `json:"total_count"`
}

ListGuardrailsResponse represents the response from listing guardrails.

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 ListOrganizationMembersOptions

type ListOrganizationMembersOptions struct {
	Offset *int
	Limit  *int
}

ListOrganizationMembersOptions represents options for listing organization members.

type ListOrganizationMembersResponse

type ListOrganizationMembersResponse struct {
	Data       []OrganizationMember `json:"data"`
	TotalCount int                  `json:"total_count"`
}

ListOrganizationMembersResponse is the response from listing organization members.

type ListWorkspacesOptions

type ListWorkspacesOptions struct {
	Offset *int
	Limit  *int
}

ListWorkspacesOptions represents options for listing workspaces.

type ListWorkspacesResponse

type ListWorkspacesResponse struct {
	Data       []Workspace `json:"data"`
	TotalCount int         `json:"total_count"`
}

ListWorkspacesResponse is the response from listing workspaces.

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]any `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 any

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"`
	ExpirationDate      *string                 `json:"expiration_date,omitempty"`
}

Model represents a model available on OpenRouter.

func FilterModels

func FilterModels(models []Model, predicate func(*Model) bool) []Model

FilterModels returns a subset of models that match the given predicate.

func (*Model) HasInputModality

func (m *Model) HasInputModality(modality string) bool

HasInputModality returns true if the model accepts the given input modality.

func (*Model) HasOutputModality

func (m *Model) HasOutputModality(modality string) bool

HasOutputModality returns true if the model produces the given output modality.

func (*Model) SupportsAudio

func (m *Model) SupportsAudio() bool

SupportsAudio returns true if the model supports audio inputs.

func (*Model) SupportsJSON

func (m *Model) SupportsJSON() bool

SupportsJSON returns true if the model supports structured JSON output via response_format.

func (*Model) SupportsParameter

func (m *Model) SupportsParameter(param string) bool

SupportsParameter returns true if the model supports the given parameter.

func (*Model) SupportsStreaming

func (m *Model) SupportsStreaming() bool

SupportsStreaming returns true if the model supports streaming responses.

func (*Model) SupportsTools

func (m *Model) SupportsTools() bool

SupportsTools returns true if the model supports tool calling.

func (*Model) SupportsVision

func (m *Model) SupportsVision() bool

SupportsVision returns true if the model supports image inputs.

type ModelArchitecture

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

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.

func CheapestModelEndpoint

func CheapestModelEndpoint(endpoints []ModelEndpoint) *ModelEndpoint

CheapestModelEndpoint returns the endpoint with the lowest prompt price. Returns nil if the slice is empty.

func FilterModelEndpoints

func FilterModelEndpoints(endpoints []ModelEndpoint, filter EndpointFilter) []ModelEndpoint

FilterModelEndpoints returns endpoints matching all criteria in the filter.

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 {
	PromptTokens     *float64 `json:"prompt_tokens"`
	CompletionTokens *float64 `json:"completion_tokens"`
}

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 OTLPAnyValue

type OTLPAnyValue struct {
	StringValue *string         `json:"stringValue,omitempty"`
	IntValue    *FlexInt        `json:"intValue,omitempty"`
	DoubleValue *float64        `json:"doubleValue,omitempty"`
	BoolValue   *bool           `json:"boolValue,omitempty"`
	ArrayValue  *OTLPArrayValue `json:"arrayValue,omitempty"`
}

OTLPAnyValue represents a polymorphic OTLP value. The OTLP spec encodes int64 values as strings, but some implementations send them as JSON numbers. IntValue accepts both forms.

func (OTLPAnyValue) StringVal

func (v OTLPAnyValue) StringVal() string

StringVal returns the value as a string regardless of its underlying type.

type OTLPArrayValue

type OTLPArrayValue struct {
	Values []OTLPAnyValue `json:"values"`
}

OTLPArrayValue wraps a slice of OTLP values.

type OTLPAttribute

type OTLPAttribute struct {
	Key   string       `json:"key"`
	Value OTLPAnyValue `json:"value"`
}

OTLPAttribute is a key-value pair attached to a span or resource.

type OTLPEvent

type OTLPEvent struct {
	Name         string          `json:"name"`
	TimeUnixNano string          `json:"timeUnixNano,omitempty"`
	Attributes   []OTLPAttribute `json:"attributes,omitempty"`
}

OTLPEvent represents a timed event within a span.

type OTLPExportTraceRequest

type OTLPExportTraceRequest struct {
	ResourceSpans []OTLPResourceSpan `json:"resourceSpans"`
}

OTLPExportTraceRequest is the top-level OTLP JSON trace payload sent by OpenRouter's Broadcast webhook feature.

func ParseBroadcastPayload

func ParseBroadcastPayload(data []byte) (*OTLPExportTraceRequest, error)

ParseBroadcastPayload unmarshals raw JSON bytes into an OTLPExportTraceRequest.

type OTLPResource

type OTLPResource struct {
	Attributes []OTLPAttribute `json:"attributes"`
}

OTLPResource describes the entity producing telemetry.

type OTLPResourceSpan

type OTLPResourceSpan struct {
	Resource   OTLPResource    `json:"resource"`
	ScopeSpans []OTLPScopeSpan `json:"scopeSpans"`
}

OTLPResourceSpan groups spans by their originating resource.

type OTLPScope

type OTLPScope struct {
	Name    string `json:"name,omitempty"`
	Version string `json:"version,omitempty"`
}

OTLPScope identifies the instrumentation library.

type OTLPScopeSpan

type OTLPScopeSpan struct {
	Scope *OTLPScope `json:"scope,omitempty"`
	Spans []OTLPSpan `json:"spans"`
}

OTLPScopeSpan groups spans by instrumentation scope.

type OTLPSpan

type OTLPSpan struct {
	TraceID           string          `json:"traceId"`
	SpanID            string          `json:"spanId"`
	ParentSpanID      string          `json:"parentSpanId,omitempty"`
	Name              string          `json:"name"`
	Kind              int             `json:"kind"`
	StartTimeUnixNano string          `json:"startTimeUnixNano"`
	EndTimeUnixNano   string          `json:"endTimeUnixNano"`
	Attributes        []OTLPAttribute `json:"attributes"`
	Status            *OTLPStatus     `json:"status,omitempty"`
	Events            []OTLPEvent     `json:"events,omitempty"`
}

OTLPSpan represents a single span in a trace.

type OTLPStatus

type OTLPStatus struct {
	Code    int    `json:"code,omitempty"`
	Message string `json:"message,omitempty"`
}

OTLPStatus describes the status of a span.

type OrganizationMember

type OrganizationMember struct {
	ID        string                 `json:"id"`
	Email     string                 `json:"email"`
	FirstName *string                `json:"first_name"`
	LastName  *string                `json:"last_name"`
	Role      OrganizationMemberRole `json:"role"`
}

OrganizationMember represents a single member of an organization.

type OrganizationMemberRole

type OrganizationMemberRole string

OrganizationMemberRole is the role of a member within the organization.

const (
	OrganizationMemberRoleAdmin  OrganizationMemberRole = "org:admin"
	OrganizationMemberRoleMember OrganizationMemberRole = "org:member"
)

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 PercentileStats

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

PercentileStats contains latency or throughput percentile statistics.

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"`

	// Internal provider parameters
	ProviderParams map[string]any `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 PublicEndpoint

type PublicEndpoint struct {
	Name                    string                `json:"name"`
	ModelID                 string                `json:"model_id"`
	ModelName               string                `json:"model_name"`
	ContextLength           float64               `json:"context_length"`
	Pricing                 PublicEndpointPricing `json:"pricing"`
	ProviderName            string                `json:"provider_name"`
	Tag                     *string               `json:"tag"`
	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"`
	SupportsImplicitCaching *bool                 `json:"supports_implicit_caching"`
	LatencyLast30m          *PercentileStats      `json:"latency_last_30m"`
	ThroughputLast30m       *PercentileStats      `json:"throughput_last_30m"`
}

PublicEndpoint represents a single endpoint from the ZDR endpoints listing.

func CheapestZDREndpoint

func CheapestZDREndpoint(endpoints []PublicEndpoint) *PublicEndpoint

CheapestZDREndpoint returns the public endpoint with the lowest prompt price. Returns nil if the slice is empty.

func FilterZDREndpoints

func FilterZDREndpoints(endpoints []PublicEndpoint, filter EndpointFilter) []PublicEndpoint

FilterZDREndpoints returns public endpoints matching all criteria in the filter.

type PublicEndpointPricing

type PublicEndpointPricing struct {
	Prompt            string  `json:"prompt"`
	Completion        string  `json:"completion"`
	Request           string  `json:"request,omitempty"`
	Image             string  `json:"image,omitempty"`
	ImageToken        string  `json:"image_token,omitempty"`
	ImageOutput       string  `json:"image_output,omitempty"`
	Audio             string  `json:"audio,omitempty"`
	AudioOutput       string  `json:"audio_output,omitempty"`
	InputAudioCache   string  `json:"input_audio_cache,omitempty"`
	WebSearch         string  `json:"web_search,omitempty"`
	InternalReasoning string  `json:"internal_reasoning,omitempty"`
	InputCacheRead    string  `json:"input_cache_read,omitempty"`
	InputCacheWrite   string  `json:"input_cache_write,omitempty"`
	Discount          float64 `json:"discount,omitempty"`
}

PublicEndpointPricing contains pricing information for a public 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 RerankDocument

type RerankDocument struct {
	// Text is the document text.
	Text string `json:"text"`
}

RerankDocument contains the text of a reranked document.

type RerankOption

type RerankOption func(*RerankRequest)

RerankOption is a functional option for rerank requests.

func WithRerankAllowFallbacks

func WithRerankAllowFallbacks(allow bool) RerankOption

WithRerankAllowFallbacks controls whether to allow backup providers.

func WithRerankDataCollection

func WithRerankDataCollection(policy string) RerankOption

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

func WithRerankIgnoreProviders

func WithRerankIgnoreProviders(providers ...string) RerankOption

WithRerankIgnoreProviders specifies providers to skip for this request.

func WithRerankOnlyProviders

func WithRerankOnlyProviders(providers ...string) RerankOption

WithRerankOnlyProviders restricts the request to only use specified providers.

func WithRerankProvider

func WithRerankProvider(provider Provider) RerankOption

WithRerankProvider sets provider-specific routing parameters.

func WithRerankProviderOrder

func WithRerankProviderOrder(providers ...string) RerankOption

WithRerankProviderOrder sets the order of providers to try.

func WithRerankProviderSort

func WithRerankProviderSort(sort string) RerankOption

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

func WithRerankTopN

func WithRerankTopN(topN int) RerankOption

WithRerankTopN sets the number of most relevant documents to return.

type RerankRequest

type RerankRequest struct {
	// Model specifies the rerank model to use (required).
	Model string `json:"model"`
	// Query is the search query to rerank documents against (required).
	Query string `json:"query"`
	// Documents is the list of documents to rerank (required).
	Documents []string `json:"documents"`
	// TopN is the number of most relevant documents to return.
	TopN *int `json:"top_n,omitempty"`
	// Provider contains provider-specific routing parameters.
	Provider *Provider `json:"provider,omitempty"`
}

RerankRequest represents a request to rerank documents against a query.

type RerankResponse

type RerankResponse struct {
	// ID is the unique identifier for the rerank response (ORID format).
	ID string `json:"id,omitempty"`
	// Model is the model used for reranking.
	Model string `json:"model"`
	// Provider is the provider that served the rerank request.
	Provider string `json:"provider,omitempty"`
	// Results is the list of rerank results sorted by relevance.
	Results []RerankResult `json:"results"`
	// Usage contains usage statistics for the request.
	Usage *RerankUsage `json:"usage,omitempty"`
}

RerankResponse represents the response from a rerank request.

type RerankResult

type RerankResult struct {
	// Index is the index of the document in the original input list.
	Index int `json:"index"`
	// RelevanceScore is the relevance score of the document to the query.
	RelevanceScore float64 `json:"relevance_score"`
	// Document contains the original document text.
	Document RerankDocument `json:"document"`
}

RerankResult represents a single reranked document result.

type RerankUsage

type RerankUsage struct {
	// TotalTokens is the total number of tokens used.
	TotalTokens int `json:"total_tokens,omitempty"`
	// SearchUnits is the number of search units consumed (Cohere billing).
	SearchUnits int `json:"search_units,omitempty"`
	// Cost is the cost of the request in credits.
	Cost *float64 `json:"cost,omitempty"`
}

RerankUsage contains usage statistics for a rerank request.

type ResetInterval

type ResetInterval string

ResetInterval represents the reset interval for a guardrail budget.

const (
	// ResetIntervalDaily resets the budget daily.
	ResetIntervalDaily ResetInterval = "daily"
	// ResetIntervalWeekly resets the budget weekly.
	ResetIntervalWeekly ResetInterval = "weekly"
	// ResetIntervalMonthly resets the budget monthly.
	ResetIntervalMonthly ResetInterval = "monthly"
)

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]any) 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]any `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]any

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]any `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 SpeechOption

type SpeechOption func(*SpeechRequest)

SpeechOption is a functional option for speech synthesis requests.

func WithSpeechProviderOptions

func WithSpeechProviderOptions(provider string, options map[string]any) SpeechOption

WithSpeechProviderOptions sets provider-specific passthrough options keyed by provider slug. The given options map is spread into the upstream request body when the matching provider is used.

func WithSpeechResponseFormat

func WithSpeechResponseFormat(format string) SpeechOption

WithSpeechResponseFormat sets the audio output format ("mp3" or "pcm").

func WithSpeechSpeed

func WithSpeechSpeed(speed float64) SpeechOption

WithSpeechSpeed sets the playback speed multiplier. Only used by providers that support it (e.g. OpenAI TTS); ignored otherwise.

type SpeechProvider

type SpeechProvider struct {
	// Options is a map keyed by provider slug. The map for the matched provider
	// is spread into the upstream request body.
	Options map[string]map[string]any `json:"options,omitempty"`
}

SpeechProvider contains provider-specific passthrough configuration for speech requests.

type SpeechRequest

type SpeechRequest struct {
	// Input is the text to synthesize (required).
	Input string `json:"input"`
	// Model is the TTS model identifier (required).
	Model string `json:"model"`
	// Voice is the provider-specific voice identifier (required).
	Voice string `json:"voice"`
	// ResponseFormat selects the audio output format ("mp3" or "pcm"). Defaults to "pcm" upstream.
	ResponseFormat string `json:"response_format,omitempty"`
	// Speed is the playback speed multiplier. Only used by providers that support it (e.g. OpenAI TTS).
	Speed *float64 `json:"speed,omitempty"`
	// Provider contains provider-specific passthrough configuration.
	Provider *SpeechProvider `json:"provider,omitempty"`
}

SpeechRequest represents a text-to-speech synthesis request.

type SpeechResponse

type SpeechResponse struct {
	// Audio contains the raw audio bytes (mp3 or pcm, depending on Format).
	Audio []byte
	// ContentType is the Content-Type header returned by the server.
	ContentType string
	// Format echoes the requested response format ("mp3" or "pcm").
	Format string
}

SpeechResponse represents the result of a text-to-speech request.

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 StreamConfig

type StreamConfig struct {
	// MaxRetries is the maximum number of reconnection attempts. Default: 3.
	MaxRetries int
	// MaxBackoff is the maximum backoff duration between reconnections. Default: 10s.
	MaxBackoff time.Duration
	// ChannelBuffer is the buffer size for the events channel. Default: 10.
	ChannelBuffer int
	// InitialBackoff is the initial backoff duration for reconnection. Default: 1s.
	InitialBackoff time.Duration
}

StreamConfig configures stream reconnection and buffering behavior.

func DefaultStreamConfig

func DefaultStreamConfig() *StreamConfig

DefaultStreamConfig returns the default stream configuration.

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 UpdateGuardrailRequest

type UpdateGuardrailRequest struct {
	Name             *string        `json:"name,omitempty"`
	Description      *string        `json:"description,omitempty"`
	LimitUSD         *float64       `json:"limit_usd,omitempty"`
	ResetInterval    *ResetInterval `json:"reset_interval,omitempty"`
	AllowedProviders []string       `json:"allowed_providers,omitempty"`
	AllowedModels    []string       `json:"allowed_models,omitempty"`
	EnforceZDR       *bool          `json:"enforce_zdr,omitempty"`
}

UpdateGuardrailRequest represents a request to update an existing guardrail. All fields are optional - only include fields you want to update.

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 UpdateWorkspaceRequest

type UpdateWorkspaceRequest struct {
	Name                            *string  `json:"name,omitempty"`
	Slug                            *string  `json:"slug,omitempty"`
	Description                     *string  `json:"description,omitempty"`
	DefaultTextModel                *string  `json:"default_text_model,omitempty"`
	DefaultImageModel               *string  `json:"default_image_model,omitempty"`
	DefaultProviderSort             *string  `json:"default_provider_sort,omitempty"`
	IOLoggingAPIKeyIDs              *[]int   `json:"io_logging_api_key_ids,omitempty"`
	IOLoggingSamplingRate           *float64 `json:"io_logging_sampling_rate,omitempty"`
	IsDataDiscountLoggingEnabled    *bool    `json:"is_data_discount_logging_enabled,omitempty"`
	IsObservabilityBroadcastEnabled *bool    `json:"is_observability_broadcast_enabled,omitempty"`
	IsObservabilityIOLoggingEnabled *bool    `json:"is_observability_io_logging_enabled,omitempty"`
}

UpdateWorkspaceRequest is the payload for updating a workspace. All fields are optional; only provided fields will be updated.

type UpdateWorkspaceResponse

type UpdateWorkspaceResponse struct {
	Data Workspace `json:"data"`
}

UpdateWorkspaceResponse is the response from updating a workspace.

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 VideoAspectRatio

type VideoAspectRatio string

VideoAspectRatio represents a supported aspect ratio for video generation.

const (
	VideoAspectRatio16x9 VideoAspectRatio = "16:9"
	VideoAspectRatio9x16 VideoAspectRatio = "9:16"
	VideoAspectRatio1x1  VideoAspectRatio = "1:1"
	VideoAspectRatio4x3  VideoAspectRatio = "4:3"
	VideoAspectRatio3x4  VideoAspectRatio = "3:4"
	VideoAspectRatio21x9 VideoAspectRatio = "21:9"
	VideoAspectRatio9x21 VideoAspectRatio = "9:21"
)

Supported video aspect ratios.

type VideoContentPartImage

type VideoContentPartImage struct {
	ImageURL VideoImageURL `json:"image_url"`
	// Type is always "image_url".
	Type string `json:"type"`
}

VideoContentPartImage is an image reference used to guide video generation.

type VideoContentResponse

type VideoContentResponse struct {
	// Content holds the raw video bytes.
	Content []byte
	// ContentType is the Content-Type header returned by the server (typically "application/octet-stream").
	ContentType string
}

VideoContentResponse is returned by GET /videos/{jobId}/content.

type VideoFrameImage

type VideoFrameImage struct {
	ImageURL VideoImageURL `json:"image_url"`
	// Type is always "image_url".
	Type string `json:"type"`
	// FrameType indicates whether this is the first or last frame.
	FrameType VideoFrameType `json:"frame_type"`
}

VideoFrameImage is an image supplied as either the first or last frame of the generated video.

type VideoFrameType

type VideoFrameType string

VideoFrameType identifies whether a supplied image is the first or last frame of the generated video.

const (
	VideoFrameTypeFirst VideoFrameType = "first_frame"
	VideoFrameTypeLast  VideoFrameType = "last_frame"
)

Supported frame image types.

type VideoGenerationOption

type VideoGenerationOption func(*VideoGenerationRequest)

VideoGenerationOption is a functional option for video generation requests.

func WithVideoAspectRatio

func WithVideoAspectRatio(ratio VideoAspectRatio) VideoGenerationOption

WithVideoAspectRatio sets the output aspect ratio.

func WithVideoCallbackURL

func WithVideoCallbackURL(url string) VideoGenerationOption

WithVideoCallbackURL sets the HTTPS webhook URL to receive a completion notification.

func WithVideoDuration

func WithVideoDuration(seconds int) VideoGenerationOption

WithVideoDuration sets the requested video duration in seconds.

func WithVideoFrameImages

func WithVideoFrameImages(frames ...VideoFrameImage) VideoGenerationOption

WithVideoFrameImages sets the first- and/or last-frame reference images.

func WithVideoGenerateAudio

func WithVideoGenerateAudio(enabled bool) VideoGenerationOption

WithVideoGenerateAudio enables or disables audio generation alongside the video.

func WithVideoInputReferences

func WithVideoInputReferences(refs ...VideoContentPartImage) VideoGenerationOption

WithVideoInputReferences sets the reference images used to guide generation.

func WithVideoProviderOptions

func WithVideoProviderOptions(provider string, options map[string]any) VideoGenerationOption

WithVideoProviderOptions sets provider-specific passthrough options keyed by provider slug. The given options map is spread into the upstream request body when the matching provider is used.

func WithVideoResolution

func WithVideoResolution(resolution VideoResolution) VideoGenerationOption

WithVideoResolution sets the output resolution.

func WithVideoSeed

func WithVideoSeed(seed int) VideoGenerationOption

WithVideoSeed sets a deterministic sampling seed. Determinism is not guaranteed for all providers.

func WithVideoSize

func WithVideoSize(size string) VideoGenerationOption

WithVideoSize sets the exact pixel dimensions (e.g. "1280x720"). Interchangeable with WithVideoResolution + WithVideoAspectRatio.

type VideoGenerationRequest

type VideoGenerationRequest struct {
	// Model is the video generation model identifier (required).
	Model string `json:"model"`
	// Prompt is the text prompt describing the video to generate (required).
	Prompt string `json:"prompt"`
	// AspectRatio selects the output aspect ratio.
	AspectRatio VideoAspectRatio `json:"aspect_ratio,omitempty"`
	// CallbackURL is an HTTPS URL that will receive a webhook notification when the job completes.
	CallbackURL string `json:"callback_url,omitempty"`
	// Duration is the requested video duration in seconds.
	Duration *int `json:"duration,omitempty"`
	// FrameImages provides first and/or last frame references for the generated video.
	FrameImages []VideoFrameImage `json:"frame_images,omitempty"`
	// GenerateAudio controls whether the provider also generates audio for the video.
	GenerateAudio *bool `json:"generate_audio,omitempty"`
	// InputReferences is a list of reference images used to guide generation.
	InputReferences []VideoContentPartImage `json:"input_references,omitempty"`
	// Provider contains provider-specific passthrough options.
	Provider *VideoProvider `json:"provider,omitempty"`
	// Resolution selects the output resolution.
	Resolution VideoResolution `json:"resolution,omitempty"`
	// Seed is an optional deterministic sampling seed.
	Seed *int `json:"seed,omitempty"`
	// Size specifies exact pixel dimensions as "WIDTHxHEIGHT" (e.g. "1280x720").
	// Interchangeable with Resolution + AspectRatio.
	Size string `json:"size,omitempty"`
}

VideoGenerationRequest represents a request to the POST /videos endpoint.

type VideoGenerationResponse

type VideoGenerationResponse struct {
	// ID is the unique identifier for the video generation job.
	ID string `json:"id"`
	// PollingURL is the URL to poll for job status.
	PollingURL string `json:"polling_url"`
	// Status is the current job status.
	Status VideoStatus `json:"status"`
	// Error contains an error message if the job failed.
	Error string `json:"error,omitempty"`
	// GenerationID is the generation ID assigned to this job once processed.
	GenerationID string `json:"generation_id,omitempty"`
	// UnsignedURLs contains unsigned content URLs, when available.
	UnsignedURLs []string `json:"unsigned_urls,omitempty"`
	// Usage reports cost information once the job is complete.
	Usage *VideoGenerationUsage `json:"usage,omitempty"`
}

VideoGenerationResponse is returned by POST /videos and GET /videos/{jobId}.

type VideoGenerationUsage

type VideoGenerationUsage struct {
	// Cost is the generation cost in USD.
	Cost *float64 `json:"cost,omitempty"`
	// IsBYOK indicates whether the request was made using a Bring Your Own Key configuration.
	IsBYOK bool `json:"is_byok,omitempty"`
}

VideoGenerationUsage reports cost and BYOK information for a completed video generation job.

type VideoImageURL

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

VideoImageURL wraps a URL pointing to an image used for video generation inputs.

type VideoModel

type VideoModel struct {
	ID                           string             `json:"id"`
	Name                         string             `json:"name"`
	CanonicalSlug                string             `json:"canonical_slug"`
	Created                      int64              `json:"created"`
	Description                  string             `json:"description,omitempty"`
	HuggingFaceID                *string            `json:"hugging_face_id,omitempty"`
	AllowedPassthroughParameters []string           `json:"allowed_passthrough_parameters"`
	GenerateAudio                *bool              `json:"generate_audio"`
	Seed                         *bool              `json:"seed"`
	PricingSKUs                  map[string]string  `json:"pricing_skus,omitempty"`
	SupportedAspectRatios        []VideoAspectRatio `json:"supported_aspect_ratios"`
	SupportedDurations           []int              `json:"supported_durations"`
	SupportedFrameImages         []VideoFrameType   `json:"supported_frame_images"`
	SupportedResolutions         []VideoResolution  `json:"supported_resolutions"`
	SupportedSizes               []string           `json:"supported_sizes"`
}

VideoModel describes a single video generation model returned by GET /videos/models.

type VideoModelsResponse

type VideoModelsResponse struct {
	Data []VideoModel `json:"data"`
}

VideoModelsResponse is returned by GET /videos/models.

type VideoProvider

type VideoProvider struct {
	// Options is a map keyed by provider slug. The map for the matched provider
	// is spread into the upstream request body.
	Options map[string]map[string]any `json:"options,omitempty"`
}

VideoProvider holds provider-specific passthrough configuration for video generation requests.

type VideoResolution

type VideoResolution string

VideoResolution represents a supported output resolution for video generation.

const (
	VideoResolution480p  VideoResolution = "480p"
	VideoResolution720p  VideoResolution = "720p"
	VideoResolution1080p VideoResolution = "1080p"
	VideoResolution1K    VideoResolution = "1K"
	VideoResolution2K    VideoResolution = "2K"
	VideoResolution4K    VideoResolution = "4K"
)

Supported video resolutions.

type VideoStatus

type VideoStatus string

VideoStatus represents the status of a video generation job.

const (
	VideoStatusPending    VideoStatus = "pending"
	VideoStatusInProgress VideoStatus = "in_progress"
	VideoStatusCompleted  VideoStatus = "completed"
	VideoStatusFailed     VideoStatus = "failed"
	VideoStatusCancelled  VideoStatus = "cancelled"
	VideoStatusExpired    VideoStatus = "expired"
)

Video generation job statuses.

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.

type Workspace

type Workspace struct {
	ID                              string  `json:"id"`
	Name                            string  `json:"name"`
	Slug                            string  `json:"slug"`
	Description                     *string `json:"description"`
	CreatedBy                       *string `json:"created_by"`
	CreatedAt                       string  `json:"created_at"`
	UpdatedAt                       *string `json:"updated_at"`
	DefaultTextModel                *string `json:"default_text_model"`
	DefaultImageModel               *string `json:"default_image_model"`
	DefaultProviderSort             *string `json:"default_provider_sort"`
	IOLoggingAPIKeyIDs              *[]int  `json:"io_logging_api_key_ids"`
	IOLoggingSamplingRate           float64 `json:"io_logging_sampling_rate"`
	IsDataDiscountLoggingEnabled    bool    `json:"is_data_discount_logging_enabled"`
	IsObservabilityBroadcastEnabled bool    `json:"is_observability_broadcast_enabled"`
	IsObservabilityIOLoggingEnabled bool    `json:"is_observability_io_logging_enabled"`
}

Workspace represents an OpenRouter workspace.

type WorkspaceMember

type WorkspaceMember struct {
	ID          string              `json:"id"`
	WorkspaceID string              `json:"workspace_id"`
	UserID      string              `json:"user_id"`
	Role        WorkspaceMemberRole `json:"role"`
	CreatedAt   string              `json:"created_at"`
}

WorkspaceMember represents a single workspace membership.

type WorkspaceMemberRole

type WorkspaceMemberRole string

WorkspaceMemberRole is the role of a member within a workspace.

const (
	WorkspaceMemberRoleAdmin  WorkspaceMemberRole = "admin"
	WorkspaceMemberRoleMember WorkspaceMemberRole = "member"
)

type ZDREndpointsResponse

type ZDREndpointsResponse struct {
	Data []PublicEndpoint `json:"data"`
}

ZDREndpointsResponse represents the response from the ZDR endpoints listing.