openai

package module
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 10, 2026 License: MIT Imports: 11 Imported by: 0

README

deps.dev License License Stay with Ukraine

openai

openai is a Go client for the OpenAI API. It implements the github.com/goloop/ai interface, so it looks and works like every other goloop AI provider, and exposes OpenAI's native endpoints with their 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, ...), plus the responses API.
  • Embeddings, image generation, audio (transcription, translation, speech), moderations, models, files and batches.
  • Retries on 429 and 5xx with backoff; normalized, typed API errors.
  • Depends only on github.com/goloop/ai and the standard library.

Installation

go get github.com/goloop/openai

Quick start

package main

import (
	"context"
	"fmt"
	"os"

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

func main() {
	c := openai.New(os.Getenv("OPENAI_API_KEY"))

	resp, err := c.Generate(context.Background(), &ai.Request{
		Model:    openai.ModelGPT4oMini,
		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 OpenAI-only options such as structured output, build a native ChatRequest:

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

Native endpoints

c.Embed(ctx, "text-embedding-3-small", "hello", "world")
c.GenerateImage(ctx, &openai.ImageRequest{Model: "gpt-image-1", Prompt: "a cat"})
c.Transcribe(ctx, &openai.TranscriptionRequest{Model: "whisper-1", File: wav, Filename: "a.wav"})
c.Speech(ctx, &openai.SpeechRequest{Model: "gpt-4o-mini-tts", Input: "hi", Voice: "alloy"})
c.Moderate(ctx, "some text")
c.Models(ctx)
c.UploadFile(ctx, "in.jsonl", data, "batch")
c.CreateBatch(ctx, fileID, "/v1/chat/completions", "24h")
c.CreateResponse(ctx, &openai.ResponsesRequest{Model: "gpt-4o-mini", Input: "hi"})

The responses API also streams. Range over ResponsesStream and read text from response.output_text.delta events; the final response.completed event carries the whole result and token usage:

for ev, err := range c.ResponsesStream(ctx, &openai.ResponsesRequest{
	Model: "gpt-4o-mini", Input: "Tell me a joke.",
}) {
	if err != nil {
		break
	}
	if ev.Type == "response.output_text.delta" {
		fmt.Print(ev.Delta)
	}
}

Documentation

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

Contributing

See CONTRIBUTING.md.

License

MIT - see LICENSE.

Documentation

Overview

Package openai is a client for the OpenAI 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 OpenAI's native endpoints and their full options: chat completions, the responses API (synchronous and streaming), embeddings, images, audio (transcription, translation and speech), moderations, models, files and batches. 

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

It depends only on goloop/ai and the standard library. The chat wire format it speaks is the one most other providers copied, so this package doubles as the reference for the OpenAI-compatible drivers.

Index

Examples

Constants

View Source 
const (
	ModelGPT4o     = "gpt-4o"
	ModelGPT4oMini = "gpt-4o-mini"
	ModelGPT4Turbo = "gpt-4-turbo"
	ModelO3Mini    = "o3-mini"
)

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

View Source 
const DefaultBaseURL = "https://api.openai.com/v1"

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

View Source 
const DefaultModerationModel = "omni-moderation-latest"

DefaultModerationModel is used by Moderate when no model is given.

Variables

This section is empty.

Functions

This section is empty.

Types

type Batch 

type Batch struct {
	ID            string      `json:"id"`
	Object        string      `json:"object"`
	Endpoint      string      `json:"endpoint"`
	Status        string      `json:"status"`
	InputFileID   string      `json:"input_file_id"`
	OutputFileID  string      `json:"output_file_id"`
	ErrorFileID   string      `json:"error_file_id"`
	CreatedAt     int64       `json:"created_at"`
	RequestCounts BatchCounts `json:"request_counts"`
}

Batch is the state of a batch job.

type BatchCounts 

type BatchCounts struct {
	Total     int `json:"total"`
	Completed int `json:"completed"`
	Failed    int `json:"failed"`
}

BatchCounts breaks down how many requests are in each state.

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"`
	MaxCompletionTokens int             `json:"max_completion_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 OpenAI's 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 OpenAI API client. It implements ai.Client and adds the provider's native endpoints.

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) and OpenAI options (WithOrg, WithProject) configure it.

Example 
package main

import (
	"fmt"

	"github.com/goloop/openai"
)

func main() {
	c := openai.New("sk-...")
	_ = c // use c.Generate, c.Stream, c.ChatCompletion, ...
	fmt.Println(openai.ModelGPT4oMini)
}

Output:
gpt-4o-mini

func (*Client) CancelBatch 

func (c *Client) CancelBatch(ctx context.Context, id string) (*Batch, error)

CancelBatch requests cancellation of a batch in progress.

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 OpenAI-specific options; use Generate for the shared, provider-agnostic path.

Example

ExampleClient_ChatCompletion shows a native request with structured output. 

package main

import (
	"encoding/json"
	"fmt"

	"github.com/goloop/openai"
)

func main() {
	req := &openai.ChatRequest{
		Model:          openai.ModelGPT4oMini,
		Messages:       []openai.ChatMessage{{Role: "user", Content: "as JSON"}},
		ResponseFormat: json.RawMessage(`{"type":"json_object"}`),
	}
	fmt.Println(req.Model)
}

Output:
gpt-4o-mini

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) CreateBatch 

func (c *Client) CreateBatch(
	ctx context.Context,
	inputFileID, endpoint, completionWindow string,
) (*Batch, error)

CreateBatch starts a batch that runs the requests in the uploaded input file against endpoint (for example "/v1/chat/completions"). completionWindow is usually "24h". Upload the JSONL input with UploadFile(purpose "batch") first.

func (*Client) CreateResponse 

func (c *Client) CreateResponse(ctx context.Context, req *ResponsesRequest) (*ResponsesResponse, error)

CreateResponse sends a request to the responses API.

func (*Client) DeleteFile 

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

DeleteFile deletes an uploaded file.

func (*Client) Embed 

func (c *Client) Embed(ctx context.Context, model string, input ...string) ([][]float64, error)

Embed is a convenience that returns the embedding vectors for the given inputs, in order.

func (*Client) Embeddings 

func (c *Client) Embeddings(ctx context.Context, req *EmbeddingRequest) (*EmbeddingResponse, error)

Embeddings returns embedding vectors for the request's inputs.

func (*Client) FileContent 

func (c *Client) FileContent(ctx context.Context, id string) ([]byte, error)

FileContent downloads a file's contents.

func (*Client) Files 

func (c *Client) Files(ctx context.Context) ([]File, error)

Files lists uploaded files.

func (*Client) Generate 

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

Generate implements ai.Client over chat completions. It returns the first choice; to request and read several choices (n > 1) use the native Client.ChatCompletion, which exposes every choice.

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/openai"
)

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

Output:
gpt-4o-mini 1

func (*Client) GenerateImage 

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

GenerateImage creates images from a text prompt.

func (*Client) GetBatch 

func (c *Client) GetBatch(ctx context.Context, id string) (*Batch, error)

GetBatch returns the current state of a batch.

func (*Client) GetFile 

func (c *Client) GetFile(ctx context.Context, id string) (*File, error)

GetFile returns a single file's metadata.

func (*Client) GetModel 

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

GetModel returns a single model by ID.

func (*Client) ListBatches 

func (c *Client) ListBatches(ctx context.Context) ([]Batch, error)

ListBatches lists batches, most recent first.

func (*Client) Models 

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

Models lists the models available to the account.

func (*Client) Moderate 

func (c *Client) Moderate(ctx context.Context, input string) (*ModerationResult, error)

Moderate classifies input text and returns its moderation result.

func (*Client) ResponsesStream added in v0.1.1 

func (c *Client) ResponsesStream(ctx context.Context, req *ResponsesRequest) iter.Seq2[ResponseStreamEvent, error]

ResponsesStream sends a streaming responses request and yields each raw event as it arrives. Text deltas come as "response.output_text.delta" events; the final "response.completed" event carries the full result and token usage.

Example

ExampleClient_ResponsesStream shows a streaming responses request. Ranging over ResponsesStream yields raw events; text arrives on "response.output_text.delta" and the final "response.completed" carries the whole result and token usage. 

package main

import (
	"fmt"

	"github.com/goloop/openai"
)

func main() {
	req := &openai.ResponsesRequest{
		Model: openai.ModelGPT4oMini,
		Input: "Tell me a joke.",
	}
	fmt.Println(req.Model)
}

Output:
gpt-4o-mini

func (*Client) Speech 

func (c *Client) Speech(ctx context.Context, req *SpeechRequest) ([]byte, error)

Speech synthesizes audio for the given text and returns the raw audio bytes.

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.

func (*Client) Transcribe 

func (c *Client) Transcribe(ctx context.Context, req *TranscriptionRequest) (string, error)

Transcribe converts speech in the audio file to text in the same language.

func (*Client) Translate 

func (c *Client) Translate(ctx context.Context, req *TranscriptionRequest) (string, error)

Translate converts speech in the audio file to English text.

func (*Client) UploadFile 

func (c *Client) UploadFile(
	ctx context.Context,
	filename string,
	data []byte,
	purpose string,
) (*File, error)

UploadFile uploads a file for the given purpose (for example "batch" or "fine-tune").

type Embedding 

type Embedding struct {
	Index     int       `json:"index"`
	Embedding []float64 `json:"embedding"`
}

Embedding is one embedding vector.

type EmbeddingRequest 

type EmbeddingRequest struct {
	Model          string   `json:"model"`
	Input          []string `json:"input"`
	Dimensions     int      `json:"dimensions,omitempty"`
	EncodingFormat string   `json:"encoding_format,omitempty"`
	User           string   `json:"user,omitempty"`
}

EmbeddingRequest is an embeddings request.

type EmbeddingResponse 

type EmbeddingResponse struct {
	Object string      `json:"object"`
	Model  string      `json:"model"`
	Data   []Embedding `json:"data"`
	Usage  struct {
		PromptTokens int `json:"prompt_tokens"`
		TotalTokens  int `json:"total_tokens"`
	} `json:"usage"`
}

EmbeddingResponse is an embeddings response.

type File 

type File struct {
	ID        string `json:"id"`
	Object    string `json:"object"`
	Bytes     int64  `json:"bytes"`
	CreatedAt int64  `json:"created_at"`
	Filename  string `json:"filename"`
	Purpose   string `json:"purpose"`
}

File describes an uploaded file.

type ImageData 

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

ImageData is one generated image, as a URL or base64 JSON.

type ImageRequest 

type ImageRequest struct {
	Model          string `json:"model,omitempty"`
	Prompt         string `json:"prompt"`
	N              int    `json:"n,omitempty"`
	Size           string `json:"size,omitempty"`
	Quality        string `json:"quality,omitempty"`
	Style          string `json:"style,omitempty"`
	ResponseFormat string `json:"response_format,omitempty"` // "url" or "b64_json"
	User           string `json:"user,omitempty"`
}

ImageRequest is an image generation request.

type ImageResponse 

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

ImageResponse is an image generation response.

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 ModerationResponse 

type ModerationResponse struct {
	ID      string             `json:"id"`
	Model   string             `json:"model"`
	Results []ModerationResult `json:"results"`
}

ModerationResponse is a moderations response.

type ModerationResult 

type ModerationResult struct {
	Flagged        bool               `json:"flagged"`
	Categories     map[string]bool    `json:"categories"`
	CategoryScores map[string]float64 `json:"category_scores"`
}

ModerationResult is the classification of one input.

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, OpenAI-compatible endpoints).

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 WithOrg 

func WithOrg(id string) Option

WithOrg sets the OpenAI-Organization header.

func WithProject 

func WithProject(id string) Option

WithProject sets the OpenAI-Project header.

func WithTimeout 

func WithTimeout(d time.Duration) Option

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

type ResponseItem added in v0.1.2 

type ResponseItem struct {
	Type      string `json:"type"`
	ID        string `json:"id"`
	CallID    string `json:"call_id"`
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

ResponseItem is an output item announced by a "response.output_item.added" event. For a function call it carries the call's ID, name and the arguments accumulated so far.

type ResponseOutput 

type ResponseOutput struct {
	Type    string `json:"type"`
	Content []struct {
		Type string `json:"type"`
		Text string `json:"text"`
	} `json:"content"`
}

ResponseOutput is one output item from the responses API.

type ResponseStreamEvent added in v0.1.1 

type ResponseStreamEvent struct {
	Type        string             `json:"type"`
	Delta       string             `json:"delta"`
	Arguments   string             `json:"arguments"`
	ItemID      string             `json:"item_id"`
	OutputIndex int                `json:"output_index"`
	Item        *ResponseItem      `json:"item"`
	Response    *ResponsesResponse `json:"response"`
	Message     string             `json:"message"`
	Code        string             `json:"code"`
}

ResponseStreamEvent is one server-sent event of a streaming responses request. Type names the event and selects which fields apply:

  • text: "response.output_text.delta" (Delta);
  • tool call: "response.output_item.added" announces the call (Item, with its name and call_id), "response.function_call_arguments.delta" streams the JSON arguments (Delta, keyed by ItemID), and "response.function_call_arguments.done" carries the full Arguments;
  • result: "response.completed"/"response.incomplete" (Response);
  • failure: "response.failed"/"error" (Message, Code).

type ResponsesRequest 

type ResponsesRequest struct {
	Model           string   `json:"model"`
	Input           any      `json:"input"`
	Instructions    string   `json:"instructions,omitempty"`
	MaxOutputTokens int      `json:"max_output_tokens,omitempty"`
	Temperature     *float64 `json:"temperature,omitempty"`
	Store           *bool    `json:"store,omitempty"`
	Stream          bool     `json:"stream,omitempty"`
}

ResponsesRequest is a request to the responses API, OpenAI's newer stateful generation endpoint. Input is a plain string or a structured input array.

type ResponsesResponse 

type ResponsesResponse struct {
	ID     string           `json:"id"`
	Model  string           `json:"model"`
	Status string           `json:"status"`
	Output []ResponseOutput `json:"output"`
	Usage  struct {
		InputTokens  int `json:"input_tokens"`
		OutputTokens int `json:"output_tokens"`
	} `json:"usage"`
}

ResponsesResponse is a responses API result.

func (*ResponsesResponse) Text 

func (r *ResponsesResponse) Text() string

Text returns the concatenation of the output's text segments.

type SpeechRequest 

type SpeechRequest struct {
	Model  string  `json:"model"`
	Input  string  `json:"input"`
	Voice  string  `json:"voice"`
	Format string  `json:"response_format,omitempty"`
	Speed  float64 `json:"speed,omitempty"`
}

SpeechRequest turns text into speech.

type TranscriptionRequest 

type TranscriptionRequest struct {
	Model    string
	File     []byte
	Filename string
	Language string // transcription only, optional
	Prompt   string
	Format   string // response_format, for example "json" or "text"
}

TranscriptionRequest transcribes or translates an audio file. File holds the audio bytes and Filename gives them an extension the API can recognize (for example "audio.mp3").

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.