gopenrouter

gopenrouter is a Go client for the OpenRouter API. It combines the complete generated interface from OpenRouter's official Go SDK with an ergonomic, go-openai-style compatibility interface.

Use one client for both surfaces:

• the generated namespaces expose the complete typed OpenRouter API, including Chat, Responses, Images, Files, audio, embeddings, reranking, video, analytics, BYOK, presets, observability, guardrails, workspaces, and API-key management;
• the compatibility methods provide a compact interface for chat completions, streaming, Anthropic Messages, Responses, embeddings, model discovery, generation metadata, credits, OAuth, and management operations.

Requirements

• Go 1.25.10 or newer
• an OpenRouter API key

The official SDK version used by the generated surface is pinned in go.mod.

Installation

go get github.com/iamwavecut/gopenrouter@main

Quick start

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/iamwavecut/gopenrouter"
)

func main() {
	client := gopenrouter.NewClient(os.Getenv("OPENROUTER_API_KEY"))

	response, err := client.CreateChatCompletion(
		context.Background(),
		gopenrouter.ChatCompletionRequest{
			Model: "openai/gpt-5-nano",
			Messages: []gopenrouter.ChatCompletionMessage{
				{
					Role:    gopenrouter.RoleUser,
					Content: "Explain why the sky is blue in one sentence.",
				},
			},
		},
	)
	if err != nil {
		log.Fatal(err)
	}

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

Generated OpenRouter interface

Client embeds OpenRouter's generated Go client. Its namespaces and exact request, response, union, multipart, pagination, binary, error, and event-stream types are available directly:

client := gopenrouter.NewClient(os.Getenv("OPENROUTER_API_KEY"))

models, err := client.Models.List(ctx, nil)
files, err := client.Files.List(ctx, nil)
responses, err := client.Responses.Send(ctx, request, nil)

Generated model types live under github.com/OpenRouterTeam/go-sdk/models. The client currently exposes these top-level namespaces:

Analytics, APIKeys, Benchmarks, Beta, Byok, Chat, Classifications, Credits, Datasets, Embeddings, Endpoints, Files, Generations, Guardrails, Images, Models, OAuth, Observability, Organization, Presets, Providers, Rerank, Responses, Stt, Tts, VideoGeneration, and Workspaces.

Compatibility interface

The root methods retain the library's concise, go-openai-inspired API:

response, err := client.CreateChatCompletion(ctx, request)
stream, err := client.CreateChatCompletionStream(ctx, request)

embedding, err := client.CreateEmbeddings(ctx, embeddingRequest)
anthropic, err := client.CreateAnthropicMessage(ctx, anthropicRequest)
responses, err := client.CreateResponse(ctx, responsesRequest)
generation, err := client.GetGeneration(ctx, generationID)

The catalog, embeddings, responses, anthropic, oauth, management, and shared packages provide the same compatibility contracts in focused namespaces.

The compatibility surface also covers POST /messages and the deprecated POST /credits/coinbase operation, which are present in OpenRouter's public OpenAPI contract but intentionally omitted from the generated official client.

Configuration

config := gopenrouter.DefaultConfig(os.Getenv("OPENROUTER_API_KEY"))
config.HTTPClient = &http.Client{Timeout: 2 * time.Minute}
config.SiteURL = "https://example.com"
config.SiteName = "Example application"
config.SiteCategories = []string{"productivity", "developer-tools"}

client := gopenrouter.NewClientWithConfig(config)

The configuration is shared by both client surfaces and controls:

• bearer authentication;
• the base URL and HTTP client;
• HTTP-Referer, X-Title, and X-OpenRouter-Title;
• X-OpenRouter-Categories.

OpenRouter-specific capabilities

• provider routing, fallback model lists, provider preferences, ZDR and region selection;
• reasoning controls and reasoning details;
• prompt caching and cache-control directives;
• structured outputs, tools, server tools, and plugins;
• text, image, audio, file, embedding, rerank, and video payloads;
• cost and native-token accounting;
• typed synchronous and streaming errors;
• Chat SSE, Responses semantic events, and Anthropic event streams.

Examples

Runnable programs are available in examples/:

• inference: Chat, streaming Chat, Responses, Anthropic Messages, and embeddings;
• multimodal: vision, file attachments, and PDF parsing;
• generation controls: reasoning, structured output, logprobs, prompt caching, provider extras, and tool calling;
• utilities: model discovery, generation metadata, and credit status.

API parity

The repository checks API coverage against a pinned official OpenAPI snapshot, maps every documented HTTP operation to a callable client method, inventories the complete official documentation corpus, and tests current schema and streaming contracts.

The reproducible source hashes, upstream client revisions, documented source lag, and verification commands are recorded in the parity evidence.

Credits

The compatibility interface is inspired by go-openai. The complete generated surface is provided by OpenRouter's official Go SDK.

License

MIT