grok

README

grok

An idiomatic, batteries-included Go client SDK for the xAI Grok API.

import "github.com/buckedunicorn/grok"

go get github.com/buckedunicorn/grok

Quick start

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/buckedunicorn/grok"
    "github.com/buckedunicorn/grok/chat"
)

func main() {
    client := grok.New(grok.WithAPIKey(os.Getenv("XAI_API_KEY")))

    comp, err := client.Chat.Create(context.Background(), &chat.CreateRequest{
        Model: "grok-4-1-fast-non-reasoning",
        Messages: []chat.Message{
            {Role: "user", Content: "What is the speed of light?"},
        },
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(comp.Choices[0].Message.Content)
}

Package map

The root client (grok.New(...)) wires up sub-clients for every API surface. Import them as you need them.

Package	Endpoint	Purpose
chat	POST /v1/chat/completions	OpenAI-compatible chat completions, streaming, tool use, structured output, conversation helper
responses	POST /v1/responses	The newer stateful Responses API, server-side tools (web_search, x_search, code_interpreter)
images	POST /v1/images/generations, /edits	Text-to-image and image-to-image
videos	POST /v1/videos/{generations,edits,extensions}	Async video generation, with polling helper
voice	TTS, STT, realtime voice (HTTP and WebSocket)	Text-to-speech, speech-to-text, bidirectional voice
models	GET /v1/models and friends	List and inspect available models
files	/v1/files	Upload, download, list, delete files
batches	/v1/batches	Asynchronous bulk inference at reduced cost
grpc	gRPC transport	Lower-overhead alternative to REST for high-throughput workloads

Higher-level helpers built on top of the API surface

Package	Use it for
agents	Structured agent runtime: Agent, Runner, Tool, Handoff, Session, Guardrails, observable Trajectory
agents/harness	Opinionated default agent with planning, FS, shell, and subagent tools pre-wired
agents/durable	Checkpoint persistence (MemoryStore, FileStore) for resumable agent runs
agents/eval	Score RunResult values: scorers, suites, pass@1 / latency aggregation
agents/sandbox	Sandboxing implementations of the harness.Executor contract (Docker today)
agents/tracing	OpenTelemetry instrumentation for agents.Runner
discord	Discord-friendly chat sugar: tool-aware Agent, Sender interface, pre-wired media and server-side tool factories
prompt	Minimal {name} template substitution for chat messages
runnable	Generic Runnable[In, Out] interface and combinators (Pipe, Parallel, Branch, Map, Retry)
workflow	Composable steps for multi-step AI pipelines
queue	Token-bucket rate limiter for outgoing API calls
memory	Conversation and agent memory backends (in-memory, file-based)
cache	Prompt-cache helpers for the x-grok-conv-id header
council	Multi-agent roundtable: ask N agents the same prompt and synthesize

Documentation

Guide	When to read
Getting started	First call, picking a model, common 401/404/timeout failure modes.
Configuration	Every With* option, request-level fields, env vars, and the headers the SDK sends.
Streaming and tools	SSE patterns, tool-use loops, the RunAgent vs agents.Runner decision.
Production guide	Retries, rate limits, prompt caching, sandboxing, observability, cost tracking.

Per-package READMEs under chat/, responses/, images/, videos/, voice/, agents/, discord/, and friends document the package-specific surface.

Common configuration

client := grok.New(
    grok.WithAPIKey(os.Getenv("XAI_API_KEY")),
    grok.WithBaseURL("https://api.x.ai"),     // override base URL
    grok.WithHTTPClient(custom),              // bring your own *http.Client
    grok.WithConvID("conv-42"),               // x-grok-conv-id for prompt-cache locality
    grok.WithMaxRetries(3),                   // exponential backoff with jitter on 429/5xx
)

grok.New reads XAI_API_KEY from the environment if WithAPIKey is omitted. Every public method takes a context.Context and respects cancellation.

Examples

The examples/ directory holds runnable demonstrations of every API surface and feature combination, including:

• chat, streaming-chat, conversation
• responses, server-tools
• images, image-edit
• video-from-prompt, video-from-image, video-edit, video-extend
• tts, stt
• tool-use, thinking, decode
• agents-runner, agents-handoff, agents-guardrails
• harness, coding-agent, sandboxed-eval, full-stack
• durable, tracing, eval, sandbox
• discord, discord-bot
• council, memory, workflow, queue, cache, sugar

Most examples live in the root module and run with go run ./examples/<name>. A handful that need heavyweight third-party dependencies (notably examples/discord-bot with discordgo) are nested Go modules with their own go.mod; build those from inside their directory so the root module stays slim.

Testing

The repository ships integration tests for every API surface. They read XAI_API_KEY from the environment and skip when absent.

go test ./...                          # unit tests only when XAI_API_KEY is unset
XAI_API_KEY=... go test ./... -v       # full integration sweep

Use grok-4-1-fast-reasoning or grok-4-1-fast-non-reasoning for production-accuracy tests, and grok-3-mini-fast for cheaper smoke tests.

Project

• Changelog — release-by-release notes following Keep a Changelog.
• Releasing — versioning policy and the steps to cut a tag.
• Security policy — coordinated disclosure address, scope, threat model.

References

• Models and pricing
• REST API reference
• gRPC API reference
• Rate limits
• Prompt caching
• Server-side tools overview

Documentation

Overview

Package grok is an idiomatic Go client SDK for the xAI Grok API.

Create a client with New, then access each API surface through its sub-client:

client := grok.New(grok.WithAPIKey(os.Getenv("XAI_API_KEY")))
resp, err := client.Chat.Create(ctx, &chat.CreateRequest{...})

API surfaces exposed on Client:

• [Client.Chat] — chat completions, streaming, tool use (chat.Client)
• [Client.Responses] — stateful Responses API (responses.Client)
• [Client.Images] — image generation and editing (images.Client)
• [Client.Videos] — async video generation (videos.Client)
• [Client.Voice] — TTS, STT, and realtime voice (voice.Client)
• [Client.Models] — model listing (models.Client)
• [Client.Files] — file upload and download (files.Client)
• [Client.Batches] — async bulk inference (batches.Client)
• Client.NewGRPC — gRPC transport alternative

Index

• type APIError
• type Client
  • func New(opts ...Option) *Client
  • func (c *Client) NewGRPC(opts ...grpc.DialOption) (*xgrpc.Client, error)
  • func (c *Client) WithConvID(id string) *Client
• type Option
  • func WithAPIKey(key string) Option
  • func WithBaseURL(url string) Option
  • func WithConcurrency(n int) Option
  • func WithConvID(id string) Option
  • func WithHTTPClient(hc *http.Client) Option
  • func WithInsecureBaseURL() Option
  • func WithLogger(l *slog.Logger) Option
  • func WithMaxRetries(n int) Option

Examples

• Client.WithConvID
• New
• New (Options)

Types

type APIError

type APIError = apierr.APIError

APIError is returned when the xAI API responds with a non-2xx status code. Use errors.As to extract it from any error returned by this package:

var apiErr *grok.APIError
if errors.As(err, &apiErr) {
    fmt.Println(apiErr.StatusCode, apiErr.Message)
}

type Client

type Client struct {
	Chat      *chat.Client
	Responses *responses.Client
	Images    *images.Client
	Videos    *videos.Client
	Voice     *voice.Client
	Models    *models.Client
	Files     *files.Client
	Batches   *batches.Client
	// contains filtered or unexported fields
}

Client is the top-level SDK entry point. Use New() to create one.

func New

func New(opts ...Option) *Client

New creates a Client. If no WithAPIKey option is provided, it reads XAI_API_KEY from env.

Example

package main

import (
	"github.com/buckedunicorn/grok"
)

func main() {
	// New reads XAI_API_KEY from the environment when WithAPIKey is omitted.
	client := grok.New()
	_ = client
}

Example (Options)

package main

import (
	"os"

	"github.com/buckedunicorn/grok"
)

func main() {
	client := grok.New(
		grok.WithAPIKey(os.Getenv("XAI_API_KEY")),
		grok.WithMaxRetries(3),
		grok.WithConvID("session-42"),
	)
	_ = client
}

func (*Client) NewGRPC

func (c *Client) NewGRPC(opts ...grpc.DialOption) (*xgrpc.Client, error)

NewGRPC creates a gRPC client for the xAI API at api.x.ai:443. The gRPC surface mirrors the REST inference endpoints; proto definitions are at https://github.com/xai-org/xai-proto. Additional dial options (e.g. interceptors) may be passed via opts.

func (*Client) WithConvID

func (c *Client) WithConvID(id string) *Client

WithConvID returns a new Client with the x-grok-conv-id header set for all requests. Use this to scope a conversation for prompt caching without recreating the full client.

Example

package main

import (
	"github.com/buckedunicorn/grok"
)

func main() {
	client := grok.New()

	// Scope a copy of the client to a specific conversation for cache locality.
	scoped := client.WithConvID("conv-abc")
	_ = scoped
}

type Option

type Option func(*config)

Option configures the Client.

func WithAPIKey

func WithAPIKey(key string) Option

WithAPIKey sets the xAI API key. Defaults to the XAI_API_KEY environment variable.

func WithBaseURL

func WithBaseURL(url string) Option

WithBaseURL overrides the API base URL (default: https://api.x.ai). The URL must use the https scheme; non-HTTPS values are rejected to prevent silent downgrade of the API key. For testing or trusted internal mirrors that do not speak TLS, combine with WithInsecureBaseURL.

func WithConcurrency

func WithConcurrency(n int) Option

WithConcurrency limits the number of simultaneous in-flight HTTP requests to n. Requests beyond the limit block until a slot is free. 0 means unlimited (default).

func WithConvID

func WithConvID(id string) Option

WithConvID sets the x-grok-conv-id header on all requests from this client, which maximises prompt-cache hit rates across consecutive turns.

func WithHTTPClient

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient replaces the default HTTP client.

func WithInsecureBaseURL

func WithInsecureBaseURL() Option

WithInsecureBaseURL permits non-HTTPS base URLs paired with WithBaseURL. Use only for local tests or trusted on-network mirrors. The bearer token is sent in cleartext over plain HTTP.

func WithLogger

func WithLogger(l *slog.Logger) Option

WithLogger attaches a slog.Logger that receives request/response events. Successful requests are logged at Info; retries at Warn; failures at Error.

func WithMaxRetries

func WithMaxRetries(n int) Option

WithMaxRetries configures automatic retry with exponential backoff for transient errors (429, 500, 502, 503, 504, and network errors). n=0 disables retries (default).