Go SDK

Planned Go SDK for AllRoutes. Until it ships, use any OpenAI-compatible Go client pointed at https://api.allroutes.ai/v1.

Not yet published. The native github.com/allroutes-ai/allroutes-go module on this page is on the roadmap but is not released yet. Use any OpenAI-compatible Go client (for example github.com/sashabaranov/go-openai) pointed at https://api.allroutes.ai/v1 for now -- see the snippet directly below. The rest of this document previews the surface the native SDK will ship with.

Use an OpenAI-Compatible Client Today

import (
    "context"
    "fmt"
    "os"

    openai "github.com/sashabaranov/go-openai"
)

cfg := openai.DefaultConfig(os.Getenv("ALLROUTES_API_KEY"))
cfg.BaseURL = "https://api.allroutes.ai/v1"
client := openai.NewClientWithConfig(cfg)

resp, err := client.CreateChatCompletion(context.Background(), openai.ChatCompletionRequest{
    Model: "gpt-4o",
    Messages: []openai.ChatCompletionMessage{
        {Role: openai.ChatMessageRoleUser, Content: "Hello!"},
    },
})
if err != nil {
    panic(err)
}
fmt.Println(resp.Choices[0].Message.Content)

Installation (planned)

go get github.com/allroutes-ai/allroutes-go/allroutes  # not yet released

Requires Go 1.21+.

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/allroutes-ai/allroutes-go/allroutes"
)

func main() {
    client := allroutes.NewClient("allroutes_sk_...")

    resp, err := client.Chat.Completions.Create(context.Background(), allroutes.ChatCompletionRequest{
        Model: "gpt-4o",
        Messages: []allroutes.Message{
            {Role: "user", Content: "Explain quantum computing in one paragraph."},
        },
    })
    if err != nil {
        log.Fatal(err)
    }

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

Client Configuration

client := allroutes.NewClient(
    "allroutes_sk_...",
    allroutes.WithBaseURL("https://custom-gateway.example.com"),
    allroutes.WithTimeout(60 * time.Second),
    allroutes.WithMaxRetries(3),
)

Option	Type	Default	Description
API key (first arg)	`string`	(required)	Your AllRoutes API key
`WithBaseURL`	`string`	`https://api.allroutes.ai`	API base URL
`WithTimeout`	`time.Duration`	`120s`	Request timeout
`WithMaxRetries`	`int`	`2`	Max retries on transient errors
`WithHTTPClient`	`*http.Client`	default	Custom HTTP client

Chat Completions

resp, err := client.Chat.Completions.Create(ctx, allroutes.ChatCompletionRequest{
    Model:       "claude-sonnet-4-20250514",
    Messages:    []allroutes.Message{
        {Role: "system", Content: "You are a helpful assistant."},
        {Role: "user", Content: "What is the capital of France?"},
    },
    Temperature: allroutes.Float64(0.7),
    MaxTokens:   allroutes.Int(256),
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Model: %s\n", resp.Model)
fmt.Printf("Content: %s\n", resp.Choices[0].Message.Content)
fmt.Printf("Tokens: %d prompt + %d completion\n",
    resp.Usage.PromptTokens, resp.Usage.CompletionTokens)

Model Fallbacks

resp, err := client.Chat.Completions.Create(ctx, allroutes.ChatCompletionRequest{
    Models: []string{"claude-sonnet-4-20250514", "gpt-4o", "gemini-2.0-flash"},
    Messages: []allroutes.Message{
        {Role: "user", Content: "Summarize this document."},
    },
})

Streaming

stream, err := client.Chat.Completions.CreateStream(ctx, allroutes.ChatCompletionRequest{
    Model: "gpt-4o",
    Messages: []allroutes.Message{
        {Role: "user", Content: "Write a short story about a robot."},
    },
})
if err != nil {
    log.Fatal(err)
}
defer stream.Close()

for {
    chunk, err := stream.Recv()
    if err != nil {
        if err == allroutes.ErrStreamDone {
            break
        }
        log.Fatal(err)
    }
    if len(chunk.Choices) > 0 && chunk.Choices[0].Delta.Content != "" {
        fmt.Print(chunk.Choices[0].Delta.Content)
    }
}
fmt.Println()

Stream to a Channel

ch := make(chan string)
go func() {
    defer close(ch)
    stream, _ := client.Chat.Completions.CreateStream(ctx, req)
    defer stream.Close()
    for {
        chunk, err := stream.Recv()
        if err != nil {
            return
        }
        if len(chunk.Choices) > 0 {
            ch <- chunk.Choices[0].Delta.Content
        }
    }
}()

for text := range ch {
    fmt.Print(text)
}

Embeddings

resp, err := client.Embeddings.Create(ctx, allroutes.EmbeddingRequest{
    Model: "text-embedding-3-small",
    Input: []string{"The quick brown fox jumps over the lazy dog"},
})
if err != nil {
    log.Fatal(err)
}

vector := resp.Data[0].Embedding
fmt.Printf("Dimensions: %d\n", len(vector))

Batch Embeddings

resp, err := client.Embeddings.Create(ctx, allroutes.EmbeddingRequest{
    Model: "text-embedding-3-small",
    Input: []string{
        "First sentence",
        "Second sentence",
        "Third sentence",
    },
})
if err != nil {
    log.Fatal(err)
}

for _, item := range resp.Data {
    fmt.Printf("Index %d: %d dimensions\n", item.Index, len(item.Embedding))
}

Credits

credits, err := client.Credits.Get(ctx)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Balance: $%.2f USD\n", credits.BalanceUSD)
fmt.Printf("Lifetime spend: $%.2f USD\n", credits.LifetimeSpendUSD)

Models

models, err := client.Models.List(ctx)
if err != nil {
    log.Fatal(err)
}

for _, m := range models.Data {
    fmt.Printf("%s by %s — context: %d tokens\n", m.ID, m.Provider, m.ContextLength)
}

Error Handling

resp, err := client.Chat.Completions.Create(ctx, req)
if err != nil {
    var apiErr *allroutes.APIError
    if errors.As(err, &apiErr) {
        switch apiErr.StatusCode {
        case 401:
            log.Println("Invalid API key")
        case 429:
            log.Printf("Rate limited, retry after %s", apiErr.RetryAfter)
        case 402:
            log.Println("Insufficient credits")
        default:
            log.Printf("API error %d: %s", apiErr.StatusCode, apiErr.Message)
        }
    } else {
        log.Printf("Network error: %v", err)
    }
    return
}

The client automatically retries on transient errors (5xx and 429) with exponential backoff.

Environment Variable

The SDK reads ALLROUTES_API_KEY from the environment if an empty string is passed:

export ALLROUTES_API_KEY="allroutes_sk_..."

client := allroutes.NewClient("") // reads from environment

Context Cancellation

Every SDK call accepts a context.Context. Use context.WithTimeout or context.WithCancel to cancel in-flight requests:

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

resp, err := client.Chat.Completions.Create(ctx, req)
if errors.Is(err, context.DeadlineExceeded) {
    log.Println("Request exceeded 10s budget")
}

Cancellation also stops streaming reads cleanly: the next stream.Recv() after cancellation returns the context error.