OpenAI Go SDK

Request unions have transitioned from interfaces (which required type assertions) to structs containing optional fields for each variant.

• To set a variant: Initialize the union struct with the specific field for that variant (e.g., OfCat or OfDog).
• To access fields: Use the provided Get methods (e.g., GetName()) which return pointers to fields shared across multiple variants, rather than using a switch on the type.

// Before (Interface based)
type AnimalParam interface { ImplAnimalParam() }
var dog AnimalParam = DogParam{Name: "spot"}

// After (Struct based)
type AnimalUnionParam struct {
    OfCat  *Cat  `json:",omitzero,inline`
    OfDog  *Dog  `json:",omitzero,inline`
}

dog := AnimalUnionParam{
    OfDog: &DogParam{Name: "spot"},
}

// Accessing fields
var name *string = animal.GetName()

For cloud workloads, use option.WithWorkloadIdentity to use short-lived, automatically refreshed tokens instead of API keys.

Kubernetes

Use auth.K8sServiceAccountTokenProvider("").

Azure Managed Identity

Use auth.AzureManagedIdentityTokenProvider(nil).

Google Cloud Compute Engine

Use auth.GCPIDTokenProvider(nil).

Custom Provider

Implement the auth.SubjectTokenProvider interface with TokenType() and GetToken(ctx, httpClient) methods.

Refresh Buffer

Tokens refresh 20 minutes before expiry by default. Customize this using RefreshBufferSeconds in auth.WorkloadIdentity.

// Kubernetes Example
client := openai.NewClient(
	option.WithWorkloadIdentity(auth.WorkloadIdentity{
		IdentityProviderID: "idp-123",
		ServiceAccountID:   "sa-456",
		Provider:           auth.K8sServiceAccountTokenProvider(""),
	}),
)

If you need to access undocumented API features, the library provides several escape hatches:

1. Undocumented Endpoints: Use client.Get, client.Post, etc. with a path string. Client RequestOptions (like retries) are respected.
2. Undocumented Parameters: Use option.WithQuerySet() or option.WithJSONSet() to inject arbitrary keys into requests.
3. Undocumented Response Properties:
   • Access raw JSON as a string via result.JSON.RawJSON().
   • Access a specific field's raw JSON via result.JSON.Foo.Raw().
   • Access all unknown fields via result.JSON.ExtraFields(), which returns a map[string]Field.

To use the OpenAI Go library, import the v3 module into your project. You can also pin a specific SDK version using go get to ensure compatibility with your Go environment.

Import path: github.com/openai/openai-go/v3 (imported as openai)

Pinning a version:

go get -u 'github.com/openai/openai-go/v3@v3.47.0'

import (
	"github.com/openai/openai-go/v3"
) // imported as openai

The tools module is used to pin repository-only tools (like govulncheck) without adding their dependencies to the main OpenAI SDK module graph. To manually update the tools pinned in this module, navigate to the tools directory and run the update commands.

cd tools
go get -tool golang.org/x/vuln/cmd/govulncheck@latest
go mod tidy

The requirements for the OpenAI Go SDK depend on the version you are using:

• SDK v3.45.0 and later: Requires Go 1.25 or later.
• Go 1.22–1.24: You must pin the SDK to v3.44.0, which is the final compatible release for these Go versions.

Note that older SDK releases do not receive guaranteed fixes or security backports.

The library automatically retries certain errors (connection errors, 408, 409, 429, and >=500) up to 2 times by default using exponential backoff.

You can configure the retry behavior globally when creating the client or override it for a specific request using option.WithMaxRetries(n).

// Configure the default for all requests (e.g., disable retries):
client := openai.NewClient(
	option.WithMaxRetries(0), // default is 2
)

// Override per-request:
client.Responses.New(
	context.TODO(),
	params,
	option.WithMaxRetries(5),
)

Many usage response data results are returned as a union type (e.g., AdminOrganizationUsageAudioSpeechesResponseDataResultUnion). To access the specific data for a particular usage type, use the AsAny() method combined with a type switch, or use the provided As<VariantName>() methods.

Example pattern for switching on the variant:

switch variant := resultUnion.AsAny().(type) {
case openai.AdminOrganizationUsageAudioSpeechesResponseDataResultOrganizationUsageCompletionsResult:
    // Handle completions result
case openai.AdminOrganizationUsageAudioSpeechesResponseDataResultOrganizationUsageEmbeddingsResult:
    // Handle embeddings result
// ... other cases
default:
    // Handle error
}

Non-success status codes return an *openai.Error. This error type includes StatusCode, *http.Request, *http.Response, and the error body JSON. Use errors.As to inspect these errors and apierr.DumpRequest(true) or apierr.DumpResponse(true) to debug the serialized HTTP traffic.

if err != nil {
	var apierr *openai.Error
	if errors.As(err, &apierr) {
		println(string(apierr.DumpRequest(true)))
		println(string(apierr.DumpResponse(true)))
	}
	panic(err.Error())
}