README

Go OpenAI

An unofficial Go client for the OpenAI API.

For new text-generation, reasoning, tool-calling, and multi-turn integrations, start with the Responses API. Chat Completions remains available for existing integrations.

The client also covers embeddings, images, audio, moderation, files, fine-tuning, batches, vector stores, and legacy Assistants API surfaces.

Building agents? Try Unreal Agent - Go-based, fully async harness that drives 40% cost savings compared to Codex!

Installation

go get github.com/sashabaranov/go-openai

Go OpenAI requires Go 1.18 or later.

Quick start: Responses API

Set an OpenAI API key in your environment:

export OPENAI_API_KEY="<your key>"

Then create a response and read its generated text:

package main

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

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

func main() {
	client := openai.NewClient(os.Getenv("OPENAI_API_KEY"))

	response, err := client.CreateResponse(context.Background(), openai.CreateResponseRequest{
		Model:        openai.GPT5Dot6Sol,
		Instructions: "You are a concise technical explainer.",
		Input:        "Why is the sky blue?",
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(response.GetOutputText())
}

Input can be a string or a slice of typed input items. For reasoning, tools, multimodal output, or custom processing, inspect response.Output instead of using the GetOutputText convenience method.

Continue a conversation

Use PreviousResponseID when OpenAI should carry the earlier response context. Resend Instructions on each call when they should continue to apply.

store := true

first, err := client.CreateResponse(ctx, openai.CreateResponseRequest{
	Model:        openai.GPT5Dot6Sol,
	Instructions: "Answer as a travel guide.",
	Input:        "What should I see in Lisbon?",
	Store:        &store,
})
if err != nil {
	return err
}

second, err := client.CreateResponse(ctx, openai.CreateResponseRequest{
	Model:              openai.GPT5Dot6Sol,
	Instructions:       "Answer as a travel guide.",
	Input:              "Which one is best on a rainy day?",
	PreviousResponseID: first.ID,
	Store:              &store,
})
if err != nil {
	return err
}

fmt.Println(second.GetOutputText())

Stream output

stream, err := client.CreateResponseStream(ctx, openai.CreateResponseRequest{
	Model: openai.GPT5Dot6Sol,
	Input: "Write a short story about a curious gopher.",
})
if err != nil {
	return err
}
defer stream.Close()

for {
	event, err := stream.Recv()
	if errors.Is(err, io.EOF) {
		break
	}
	if err != nil {
		return err
	}
	if event.Type == openai.ResponseStreamEventOutputTextDelta {
		fmt.Print(event.Delta)
	}
}

Choosing a model

Choose a model based on the workload's reasoning, latency, and cost requirements.

Constant	Model ID	Typical use
`GPT6Dot1Sol`	`gpt-6.1-sol`	Complex coding and professional work
`GPT6Astra`	`gpt-6-astra`	Most demanding reasoning and coding
`GPT6Sol`	`gpt-6-sol`	Previous Sol model
`GPT6Luna`	`gpt-6-luna`	Focused, high-volume work

GPT-5.6 and earlier model constants remain available. GPT-6.1 Sol and Astra support low, medium (default), high, xhigh, and max reasoning; they do not support none or minimal. GPT-6 Sol and Luna also support none. Use Responses for tool calling with GPT-6.1 Sol or Astra, or when combining GPT-6 reasoning with tools. See GPT-6 guidance.

See the OpenAI model catalog for capabilities and availability. Model IDs are accepted as strings, so you can use a model before a named constant is added to this package.

Chat Completions

Chat Completions remains supported for existing integrations:

response, err := client.CreateChatCompletion(ctx, openai.ChatCompletionRequest{
	Model: openai.GPT4oMini,
	Messages: []openai.ChatCompletionMessage{
		{
			Role:    openai.ChatMessageRoleUser,
			Content: "Hello!",
		},
	},
})
if err != nil {
	return err
}

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

For a new integration, prefer Responses unless you specifically need the Chat Completions request or response shape.

Configuration

Use DefaultConfig to customize the HTTP client, base URL, organization, or headers before constructing a client:

config := openai.DefaultConfig(os.Getenv("OPENAI_API_KEY"))
config.BaseURL = "https://your-compatible-endpoint.example/v1"
client := openai.NewClientWithConfig(config)

For Azure OpenAI, start with DefaultAzureConfig and configure the deployment mapping or API version required by your Azure resource.

Error handling

API failures can be inspected with errors.As:

var apiError *openai.APIError
if errors.As(err, &apiError) {
	fmt.Printf("OpenAI error: status=%d code=%v message=%s\n",
		apiError.HTTPStatusCode, apiError.Code, apiError.Message)
}

Examples

Runnable examples live in examples/:

To run one:

go run ./examples/responses

Contributing

See the contributing guidelines before opening a pull request.

Thank you

Thank you to all of the project's contributors and sponsors, including Carson Kahn of Spindle AI.

Current rankings

409
All-Time Champions · Go
11K stars · 1.7K fork · Total stars
All-time · Go →

Momentum, past 30 days

No leaderboard records in the last 30 days.

sashabaranov/go-openai