grok

README

grok

grok is a Go client for the xAI (Grok) API. It implements the github.com/goloop/ai interface, so it looks and works like every other goloop AI provider, and exposes the native chat-completions endpoint with its full options on top.

Features

• Chat completions: Generate for a single response, Stream for token-by-token output through iter.Seq2.
• Tool use (function calling), multimodal image input and system prompts.
• Native ChatCompletion and ChatCompletionStream with the full option set (response_format, seed, n, ...).
• Image generation and model listing.
• Retries on 429 and 5xx with backoff; normalized, typed API errors.
• Depends only on github.com/goloop/ai and the standard library.
• Structured output: ai.Format maps onto the provider's response_format (JSON mode or a JSON Schema); read the reply with resp.JSON(&v).
• Hosted capabilities: ai.Request.Hosted is refused with ai.ErrNoHosted, because this provider's search is not reachable from the chat endpoint.

Installation

go get github.com/goloop/grok

Quick start

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/goloop/ai"
	"github.com/goloop/grok"
)

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

	resp, err := c.Generate(context.Background(), &ai.Request{
		Model:    grok.ModelGrok4,
		Messages: []ai.Message{ai.UserText("Say hello in one word.")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(resp.Text())
}

Streaming

for chunk, err := range c.Stream(ctx, req) {
	if err != nil {
		break
	}
	fmt.Print(chunk.Text)
	if chunk.Done && chunk.Usage != nil {
		fmt.Printf("\n[%d in / %d out]\n",
			chunk.Usage.InputTokens, chunk.Usage.OutputTokens)
	}
}

Tools, images and system prompts

Tools, images and system prompts use the same shared ai types as every other provider (see the reference). For provider-only options such as structured output, build a native ChatRequest:

resp, _ := c.ChatCompletion(ctx, &grok.ChatRequest{
	Model:          grok.ModelGrok4,
	Messages:       []grok.ChatMessage{{Role: "user", Content: "List two colors as JSON."}},
	ResponseFormat: json.RawMessage(`{"type":"json_object"}`),
})

Native endpoints

c.Models(ctx)
c.GetModel(ctx, grok.ModelGrok4)
c.GenerateImage(ctx, &grok.ImageRequest{Model: grok.ModelGrok2Image, Prompt: "a cat"})

Documentation

Full reference: DOC.md (Ukrainian: DOC.UK.md).

Contributing

See CONTRIBUTING.md.

License

MIT - see LICENSE.

Documentation

Overview

Package grok is a client for the xAI (Grok) API, built on the goloop/ai interface.

The Client implements ai.Client, so Generate and Stream work the same as with any other goloop AI provider. On top of that it exposes the native chat completions endpoint with its full options, image generation (GenerateImage, with ImageData.Bytes and a nil-report ImageResponse.Usage in the same shape as the other goloop drivers) and model listing. The wire format is chat-completions compatible.

c := grok.New(os.Getenv("XAI_API_KEY"))
resp, err := c.Generate(ctx, &ai.Request{
    Model:    grok.ModelGrok4,
    Messages: []ai.Message{ai.UserText("Say hello in one word.")},
})

Structured output

ai.Request.Format maps onto the provider's response_format, so a request for JSON is enforced rather than merely asked for, and ai.Response.JSON decodes the reply. Plain JSON mode also puts ai.Format.Instruction into the system prompt, because this wire format rejects json_object unless the word "json" appears in the messages.

Hosted capabilities

This provider does run searches of its own, but they are not reachable from the chat endpoint this package speaks, and its documentation leaves more than one plausible request shape. Rather than guess at one, ai.Hosted is refused with ai.ErrNoHosted before the request leaves.

The refusal is the documented behavior, not a gap waiting to be filled in silence: an answer produced without the search that was asked for looks exactly like one produced with it. A caller who would rather have the answer anyway asks again without ai.Request.Hosted.

Asking what this driver can do

Capabilities describes this driver for the decision taken before a call: whether to offer a feature at all, and whether it needs one request or two.

if ai.SupportsHosted(c, ai.Hosted{Kind: ai.HostedWebSearch}) { ... }

It is a hint and not a permission - support also depends on the model, the account and the region - so ai.ErrNoHosted and ai.ErrNoFormat remain the source of truth and a caller still handles them. What changes is that a refusal the provider only reports as a 400 now arrives as those same sentinels, wrapped around the original ai.APIError, so one errors.Is covers a limitation this driver knew in advance and one it learned over the wire.

It depends only on goloop/ai and the standard library.

Index

• Constants
• Variables
• type ChatChoice
• type ChatFunctionCall
• type ChatFunctionDef
• type ChatMessage
• type ChatRequest
• type ChatResponse
• type ChatStreamChunk
• type ChatTool
• type ChatToolCall
• type ChatUsage
• type Client
  • func New(apiKey string, opts ...Option) *Client
  • func (c *Client) Capabilities() ai.Capabilities
  • func (c *Client) ChatCompletion(ctx context.Context, req *ChatRequest) (*ChatResponse, error)
  • func (c *Client) ChatCompletionStream(ctx context.Context, req *ChatRequest) iter.Seq2[ChatStreamChunk, error]
  • func (c *Client) Generate(ctx context.Context, req *ai.Request) (*ai.Response, error)
  • func (c *Client) GenerateImage(ctx context.Context, req *ImageRequest) (*ImageResponse, error)
  • func (c *Client) GetModel(ctx context.Context, id string) (*Model, error)
  • func (c *Client) Models(ctx context.Context) ([]Model, error)
  • func (c *Client) Stream(ctx context.Context, req *ai.Request) iter.Seq2[ai.Chunk, error]
• type ImageData
  • func (d ImageData) Bytes() ([]byte, error)
• type ImageRequest
• type ImageResponse
• type ImageUsage
• type Model
• type Option
  • func WithBaseURL(u string) Option
  • func WithHTTPClient(c *http.Client) Option
  • func WithHeader(key, value string) Option
  • func WithMaxRetries(n int) Option
  • func WithTimeout(d time.Duration) Option

Examples

• Client.Generate
• New

Constants

const (
	ModelGrok4       = "grok-4"
	ModelGrok3       = "grok-3"
	ModelGrok3Mini   = "grok-3-mini"
	ModelGrok2Vision = "grok-2-vision-1212"
	ModelGrok2Image  = "grok-2-image-1212"
)

Convenience model identifiers. Any model string is accepted; use Models to discover what the account can call.

const (
	ImageFormatURL     = "url"
	ImageFormatB64JSON = "b64_json"
)

The values ImageRequest.ResponseFormat accepts. The model constant (ModelGrok2Image) lives in grok.go with the other model identifiers.

const DefaultBaseURL = "https://api.x.ai/v1"

DefaultBaseURL is the xAI API base URL, including the version segment.

Variables

var (
	// ErrNoImageRequest is returned by GenerateImage for a nil request.
	ErrNoImageRequest = errors.New("grok: image request is nil")

	// ErrNoImageBytes is returned by ImageData.Bytes for an image the provider
	// returned as a URL. Fetch the URL, or ask for ImageFormatB64JSON.
	ErrNoImageBytes = errors.New("grok: image was returned as a URL")
)

Errors reported for an image request or its result. They carry the same names as in the other goloop drivers, so application code reads the same way whichever provider is behind it.

Types

type ChatChoice

type ChatChoice struct {
	Index        int         `json:"index"`
	Message      ChatMessage `json:"message"`
	FinishReason string      `json:"finish_reason"`
}

ChatChoice is one completion choice.

type ChatFunctionCall

type ChatFunctionCall struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

ChatFunctionCall is the function name and JSON-encoded arguments of a call.

type ChatFunctionDef

type ChatFunctionDef struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	Parameters  json.RawMessage `json:"parameters,omitempty"`
}

ChatFunctionDef is a function's name, description and JSON Schema parameters.

type ChatMessage

type ChatMessage struct {
	Role       string         `json:"role"`
	Content    any            `json:"content,omitempty"`
	Name       string         `json:"name,omitempty"`
	ToolCalls  []ChatToolCall `json:"tool_calls,omitempty"`
	ToolCallID string         `json:"tool_call_id,omitempty"`
}

ChatMessage is one message in a chat request or response. Content is a string or a slice of content parts (for images).

type ChatRequest

type ChatRequest struct {
	Model          string          `json:"model"`
	Messages       []ChatMessage   `json:"messages"`
	Tools          []ChatTool      `json:"tools,omitempty"`
	ToolChoice     any             `json:"tool_choice,omitempty"`
	Temperature    *float64        `json:"temperature,omitempty"`
	TopP           *float64        `json:"top_p,omitempty"`
	MaxTokens      int             `json:"max_tokens,omitempty"`
	Stop           []string        `json:"stop,omitempty"`
	N              int             `json:"n,omitempty"`
	Seed           *int            `json:"seed,omitempty"`
	ResponseFormat json.RawMessage `json:"response_format,omitempty"`
	User           string          `json:"user,omitempty"`
	Stream         bool            `json:"stream,omitempty"`
	StreamOptions  *streamOptions  `json:"stream_options,omitempty"`
}

ChatRequest is the native chat completions request, exposing the full option set (response_format, seed, n and so on). Build one directly for features the shared ai.Request does not model, or let Generate build it.

type ChatResponse

type ChatResponse struct {
	ID      string       `json:"id"`
	Object  string       `json:"object"`
	Model   string       `json:"model"`
	Choices []ChatChoice `json:"choices"`
	Usage   ChatUsage    `json:"usage"`
}

ChatResponse is the native chat completions response.

type ChatStreamChunk

type ChatStreamChunk struct {
	ID      string `json:"id"`
	Model   string `json:"model"`
	Choices []struct {
		Index int `json:"index"`
		Delta struct {
			Content   string `json:"content"`
			ToolCalls []struct {
				Index    int    `json:"index"`
				ID       string `json:"id"`
				Function struct {
					Name      string `json:"name"`
					Arguments string `json:"arguments"`
				} `json:"function"`
			} `json:"tool_calls"`
		} `json:"delta"`
		FinishReason string `json:"finish_reason"`
	} `json:"choices"`
	Usage *ChatUsage `json:"usage"`
}

ChatStreamChunk is one streamed chat completions event.

type ChatTool

type ChatTool struct {
	Type     string          `json:"type"`
	Function ChatFunctionDef `json:"function"`
}

ChatTool declares a callable function.

type ChatToolCall

type ChatToolCall struct {
	ID       string           `json:"id"`
	Type     string           `json:"type"`
	Function ChatFunctionCall `json:"function"`
}

ChatToolCall is a tool call the model produced.

type ChatUsage

type ChatUsage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
}

ChatUsage reports token usage for a chat completion.

type Client

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

Client is an xAI (Grok) API client. It implements ai.Client and adds the provider's native endpoints. The wire format is chat-completions compatible.

func New

func New(apiKey string, opts ...Option) *Client

New returns a Client for the given API key. Shared options (WithBaseURL, WithHTTPClient, WithTimeout, WithMaxRetries, WithHeader) configure it.

Example

package main

import (
	"fmt"

	"github.com/goloop/grok"
)

func main() {
	c := grok.New("xai-...")
	_ = c // use c.Generate, c.Stream, c.ChatCompletion, ...
	fmt.Println(grok.ModelGrok4)
}

Output:
grok-4

func (*Client) Capabilities

func (c *Client) Capabilities() ai.Capabilities

Capabilities describes what this driver can be asked for. It is a hint for the decision taken before a call - whether to offer a feature, and whether it needs one request or two - and never a substitute for handling ai.ErrNoHosted, ai.ErrNoFormat or ai.ErrFormatWithHosted, because support also depends on the model, the account and the region.

func (*Client) ChatCompletion

func (c *Client) ChatCompletion(ctx context.Context, req *ChatRequest) (*ChatResponse, error)

ChatCompletion sends a native chat completions request and returns the whole response. Use it for provider-specific options; use Generate for the shared, provider-agnostic path.

func (*Client) ChatCompletionStream

func (c *Client) ChatCompletionStream(ctx context.Context, req *ChatRequest) iter.Seq2[ChatStreamChunk, error]

ChatCompletionStream sends a native streaming chat request and returns an iterator over the raw chunks.

func (*Client) Generate

func (c *Client) Generate(ctx context.Context, req *ai.Request) (*ai.Response, error)

Generate implements ai.Client over chat completions.

Example

ExampleClient_Generate builds a request. Sending it needs a real API key, so this example only shows the shape.

package main

import (
	"fmt"

	"github.com/goloop/ai"
	"github.com/goloop/grok"
)

func main() {
	req := &ai.Request{
		Model: grok.ModelGrok4,
		Messages: []ai.Message{
			ai.UserText("Name the capital of France."),
		},
	}
	fmt.Println(req.Model, len(req.Messages))
}

Output:
grok-4 1

func (*Client) GenerateImage

func (c *Client) GenerateImage(
	ctx context.Context,
	req *ImageRequest,
) (*ImageResponse, error)

GenerateImage generates one or more images from a prompt. Read each image with ImageData.Bytes.

func (*Client) GetModel

func (c *Client) GetModel(ctx context.Context, id string) (*Model, error)

GetModel returns a single model by ID.

func (*Client) Models

func (c *Client) Models(ctx context.Context) ([]Model, error)

Models lists the models available to the account.

func (*Client) Stream

func (c *Client) Stream(ctx context.Context, req *ai.Request) iter.Seq2[ai.Chunk, error]

Stream implements ai.Client over streaming chat completions.

type ImageData

type ImageData struct {
	URL           string `json:"url,omitempty"`
	B64JSON       string `json:"b64_json,omitempty"`
	RevisedPrompt string `json:"revised_prompt,omitempty"`
}

ImageData is one generated image: a URL or base64-encoded bytes.

func (ImageData) Bytes

func (d ImageData) Bytes() ([]byte, error)

Bytes returns the decoded image. It reads what the provider put inline and does no I/O: an image delivered as a URL returns ErrNoImageBytes, because fetching it is a network call with the caller's own timeouts, redirects and proxy rules, not something a field accessor should decide.

type ImageRequest

type ImageRequest struct {
	Model  string `json:"model"`
	Prompt string `json:"prompt"`
	N      int    `json:"n,omitempty"`

	// ResponseFormat is ImageFormatURL or ImageFormatB64JSON.
	ResponseFormat string `json:"response_format,omitempty"`
}

ImageRequest is the native image generation request.

The xAI images endpoint takes the OpenAI shape but a smaller subset of it: there is no size, quality or style knob, so those fields are deliberately absent rather than accepted and ignored. ResponseFormat is kept because xAI does honor it.

type ImageResponse

type ImageResponse struct {
	Created int64       `json:"created"`
	Data    []ImageData `json:"data"`

	// Usage carries the tokens the request billed, when the provider reports
	// them. It is a pointer so a nil Usage - the provider said nothing - is
	// distinct from a zero count. The type mirrors the other drivers'.
	Usage *ImageUsage `json:"usage,omitempty"`
}

ImageResponse is the native image generation response.

type ImageUsage

type ImageUsage struct {
	TotalTokens  int `json:"total_tokens"`
	InputTokens  int `json:"input_tokens"`
	OutputTokens int `json:"output_tokens"`
}

ImageUsage reports the tokens an image request consumed. It matches the shape used by the other goloop image drivers so accounting code is uniform; fields the provider does not send stay zero.

type Model

type Model struct {
	ID      string `json:"id"`
	Object  string `json:"object"`
	Created int64  `json:"created"`
	OwnedBy string `json:"owned_by"`
}

Model describes a model returned by the models endpoint.

type Option

type Option func(*settings)

Option configures a Client in New.

func WithBaseURL

func WithBaseURL(u string) Option

WithBaseURL overrides the API base URL (proxies, gateways, mock servers).

func WithHTTPClient

func WithHTTPClient(c *http.Client) Option

WithHTTPClient sets the HTTP client used for requests.

func WithHeader

func WithHeader(key, value string) Option

WithHeader adds a header sent with every request.

func WithMaxRetries

func WithMaxRetries(n int) Option

WithMaxRetries sets how many times a request is retried on 429 and 5xx.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the per-request timeout when no custom HTTP client is set.