discover · compare · collections · requirements · contribute · feed · watching · stats · help with your tokens
sashabaranov/go-openai · source
Snapshot 0 · 2026-11-04T12:47:26Z · Go · Apache-2.0
Content fingerprint
971b65ebbe23f73f4afbd3116a5455c2169bb757bd81f7034f0104154068b818GitHub description at capture
OpenAI, GPT 6.1, GPT-Image-2, Whisper API clients for Go. Zero-dependency.
README at capture
# Go OpenAI
[](https://pkg.go.dev/github.com/sashabaranov/go-openai)
[](https://codecov.io/gh/sashabaranov/go-openai)
An unofficial Go client for the [OpenAI API](https://developers.openai.com/api/docs/overview).
For new text-generation, reasoning, tool-calling, and multi-turn integrations,
start with the [Responses API](https://developers.openai.com/api/docs/guides/migrate-to-responses).
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](https://github.com/unreallabsai/unreal-agent) - Go-based, fully async harness that drives 40% cost savings compared to Codex!
## Installation
```sh
go get github.com/sashabaranov/go-openai
```
Go OpenAI requires Go 1.18 or later.
## Quick start: Responses API
Set an [OpenAI API key](https://platform.openai.com/api-keys) in your environment:
```sh
export OPENAI_API_KEY="<your key>"
```
Then create a response and read its generated text:
```go
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.
```go
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
```go
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](https://developers.openai.com/api/docs/guides/latest-model).
See the [OpenAI model catalog](https://developers.openai.com/api/docs/models) 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:
```go
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:
```go
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`:
```go
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/`](examples):
- [Responses API with multi-turn state](examples/responses)
- [Chat Completions](examples/completion)
- [Chat Completions with a function tool](examples/completion-with-tool)
- [Image generation](examples/images)
- [Speech to text](examples/voice-to-text)
To run one:
```sh
go run ./examples/responses
```
## Contributing
See the [contributing guidelines](CONTRIBUTING.md) before opening a pull request.
## Thank you
Thank you to all of the project's
[contributors](https://github.com/sashabaranov/go-openai/graphs/contributors)
and sponsors, including [Carson Kahn](https://carsonkahn.com) of
[Spindle AI](https://spindleai.com).