Go SDK
Integrate Go applications with nRouter using our official Go SDK or OpenAI Go client. Access typed helpers, automatic cost tracking, and resilient routing.
The official nRouter Go SDK delivers high-performance, idiomatic Go bindings for the unified AI gateway with typed helpers, real-time cost tracking, and streaming.
Target https://api.nrouter.ai/v1 using your virtual NROUTER_API_KEY:
- Official & OpenAI compatibility: Use
github.com/nRouterGateway/nrouter-sdk/sdks/go/v3or pointgithub.com/openai/openai-godirectly to nRouter. - Pre-call guardrails & safety: Prompt injection defense, PII masking, and budget controls execute before upstream dispatch — refused calls cost $0.
Installation
Install the versioned v3 package:
go get github.com/nRouterGateway/nrouter-sdk/sdks/go/v3@v3.1.2Package documentation: pkg.go.dev/github.com/nRouterGateway/nrouter-sdk/sdks/go/v3.
Setup & Chat Completion
Set your virtual API key in your environment:
export NROUTER_API_KEY="sk-nrouter-xxxxxxxxxxxx"Initialize the client and execute a chat completion:
package main
import (
"context"
"fmt"
"log"
"time"
nrouter "github.com/nRouterGateway/nrouter-sdk/sdks/go/v3"
)
func main() {
client, err := nrouter.NewFromEnv()
if err != nil {
log.Fatal(err)
}
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
res, err := client.ChatCompletions(ctx, map[string]any{
"model": "gpt-5.4-mini",
"messages": []any{
map[string]any{"role": "user", "content": "Explain raft consensus in three sentences."},
},
})
if err != nil {
log.Fatalf("Chat completion failed: %v", err)
}
if res.Meta.Cost != nil {
fmt.Printf("Cost: $%v | Request ID: %s\n", *res.Meta.Cost, res.Meta.RequestID)
}
}Streaming Responses
Stream tokens via Server-Sent Events (SSE):
package main
import (
"context"
"fmt"
"log"
nrouter "github.com/nRouterGateway/nrouter-sdk/sdks/go/v3"
)
func main() {
client, err := nrouter.NewFromEnv()
if err != nil {
log.Fatal(err)
}
stream, err := client.ChatCompletionsStream(context.Background(), map[string]any{
"model": "claude-haiku-4-5-20251001",
"messages": []any{map[string]any{"role": "user", "content": "Write a worker pool in Go."}},
"stream": true,
})
if err != nil {
log.Fatal(err)
}
defer stream.Close()
for stream.Next() {
fmt.Print(stream.Current().DeltaContent)
}
fmt.Println()
}Error Handling
Errors map to HTTP status codes documented in Errors & Rate Limits and unwrap to *nrouter.APIError:
package main
import (
"context"
"errors"
"log"
nrouter "github.com/nRouterGateway/nrouter-sdk/sdks/go/v3"
)
func handleCall(client *nrouter.Client) {
_, err := client.ChatCompletions(context.Background(), map[string]any{
"model": "gpt-5.4-mini",
"messages": []any{map[string]any{"role": "user", "content": "Run"}},
})
if err != nil {
var nErr *nrouter.APIError
if errors.As(err, &nErr) {
log.Printf("Gateway error [%d]: %s", nErr.StatusCode, nErr.Message)
return
}
log.Printf("Transport error: %v", err)
}
}Next Steps
- Python SDK Guide — Official nRouter Python SDK
- cURL Examples — Raw HTTP request and response inspection
- Chat Completions API — HTTP endpoint specifications
- Router Settings — Dynamic
nrouter/automodel routing - Per-Request Options — Custom fallback chains and tags
Was this page helpful?