openai

README

openai

A Go package for OpenAI API chat completions with support for both streaming and non-streaming responses.

Features

• Simple, clean API for OpenAI chat completions
• Support for streaming responses
• Terminal markdown rendering for streaming responses
• Support for custom HTTP clients
• Context-aware requests
• Proper error handling

Installation

go get github.com/jiyeol-lee/openai

Usage

Basic Non-Streaming Chat Completion

Send a prompt and wait for the full assistant reply in one shot:

See the complete example in examples/basic/basic.go.

Streaming Chat Completion

Receive tokens as soon as they are ready and render them manually:

See the complete example in examples/stream/stream.go.

Streaming Chat Completion with Markdown Output

Render the stream directly to a terminal-friendly markdown viewer while it arrives:

See the complete example in examples/stream_markdown/stream_markdown.go.

With Custom HTTP Client

import (
    "net/http"
    "time"
)

httpClient := &http.Client{
    Timeout: 60 * time.Second,
}

client := openai.NewClient(
    os.Getenv("OPENAI_API_KEY"),
    openai.WithHTTPClient(httpClient),
)

API Reference

Types

Client

The main client for making OpenAI API requests.

Message

Represents a single message in a conversation.

• Role: The role of the message sender ("system", "user", or "assistant")
• Content: The content of the message

ChatCompletionRequest

Configuration for a chat completion request.

• Model: The model to use (e.g., "gpt-4", "gpt-3.5-turbo", "gpt-4-turbo")
• Messages: Array of messages in the conversation
• Temperature: Controls randomness (0.0 to 2.0), optional
• ReasoningEffort: Optional reasoning effort parameter ("low", "medium", "high")
• Stream: Set automatically by the methods (don't set manually)

ChatCompletionResponse

Response from a non-streaming completion request. Contains choices with the assistant's message.

ChatCompletionStreamResponse

Response chunk from a streaming completion request.

StreamOptions

Configures how markdown streaming output is rendered.

• Raw: When true, writes chunks directly without styling
• WordWrap: Wrap width for the renderer (defaults to 120 when zero)
• Cancel: Optional callback invoked when the user presses Ctrl+C in the markdown viewer

StreamReader

Provides access to streaming responses.

Functions

NewClient(apiKey string, opts ...ClientOption) *Client

Creates a new OpenAI client.

Parameters:

• apiKey: Your OpenAI API key
• opts: Optional configuration options

Example:

client := openai.NewClient(apiKey)

CreateChatCompletion(ctx context.Context, req ChatCompletionRequest) (string, error)

Sends a non-streaming chat completion request and returns the complete response.

Parameters:

• ctx: Context for the request
• req: The chat completion request configuration

Returns:

• string: The assistant's response content
• error: Any error that occurred

CreateChatCompletionStream(ctx context.Context, req ChatCompletionRequest) (*StreamReader, error)

Sends a streaming chat completion request.

Parameters:

• ctx: Context for the request
• req: The chat completion request configuration

Returns:

• *StreamReader: A stream reader for receiving chunks
• error: Any error that occurred

CreateChatCompletionStreamWithMarkdown(ctx context.Context, req ChatCompletionRequest, w io.Writer, opts StreamOptions) error

Sends a streaming chat completion request and renders the incremental markdown output to the provided writer.

Parameters:

• ctx: Context for the request
• req: The chat completion request configuration
• w: Destination for the rendered markdown (for example, os.Stdout)
• opts: Rendering options that control wrapping, raw output, and cancellation

Returns:

• error: Any error that occurred while streaming or rendering

StreamReader.Recv() (ChatCompletionStreamResponse, error)

Reads the next chunk from the stream.

Returns:

• ChatCompletionStreamResponse: The next chunk
• error: io.EOF when the stream ends, or any other error

StreamReader.Close() error

Closes the stream. Should be called when done reading.

Options

WithHTTPClient(httpClient *http.Client) ClientOption

Sets a custom HTTP client.

Example:

httpClient := &http.Client{Timeout: 60 * time.Second}
client := openai.NewClient(apiKey, openai.WithHTTPClient(httpClient))

Error Handling

The package returns detailed errors for various failure scenarios:

• Network errors
• API errors (with status code and message)
• JSON parsing errors
• Empty responses

Always check for errors:

response, err := client.CreateChatCompletion(ctx, req)
if err != nil {
    log.Printf("Error: %v", err)
    return
}

Documentation

Index

• type ChatCompletionRequest
• type ChatCompletionResponse
• type ChatCompletionStreamResponse
• type Client
  • func NewClient(apiKey string, opts ...ClientOption) *Client
  • func (c *Client) CreateChatCompletion(ctx context.Context, req ChatCompletionRequest) (string, error)
  • func (c *Client) CreateChatCompletionStream(ctx context.Context, req ChatCompletionRequest) (*StreamReader, error)
  • func (c *Client) CreateChatCompletionStreamWithMarkdown(ctx context.Context, req ChatCompletionRequest, w io.Writer, ...) error
• type ClientOption
  • func WithHTTPClient(httpClient *http.Client) ClientOption
• type Message
• type StreamOptions
• type StreamReader
  • func (s *StreamReader) Close() error
  • func (s *StreamReader) Recv() (ChatCompletionStreamResponse, error)

Types

type ChatCompletionRequest

type ChatCompletionRequest struct {
	Model           string    `json:"model"`
	Messages        []Message `json:"messages"`
	Temperature     float32   `json:"temperature,omitempty"`
	ReasoningEffort string    `json:"reasoning_effort,omitempty"`
	Stream          bool      `json:"stream,omitempty"`
}

ChatCompletionRequest represents a chat completion request

type ChatCompletionResponse

type ChatCompletionResponse struct {
	ID      string `json:"id"`
	Object  string `json:"object"`
	Created int64  `json:"created"`
	Model   string `json:"model"`
	Choices []struct {
		Index        int     `json:"index"`
		Message      Message `json:"message"`
		FinishReason string  `json:"finish_reason"`
	} `json:"choices"`
	Usage struct {
		PromptTokens     int `json:"prompt_tokens"`
		CompletionTokens int `json:"completion_tokens"`
		TotalTokens      int `json:"total_tokens"`
	} `json:"usage"`
}

ChatCompletionResponse represents the API response for non-streaming requests

type ChatCompletionStreamResponse

type ChatCompletionStreamResponse struct {
	ID      string `json:"id"`
	Object  string `json:"object"`
	Created int64  `json:"created"`
	Model   string `json:"model"`
	Choices []struct {
		Index int `json:"index"`
		Delta struct {
			Role    string `json:"role,omitempty"`
			Content string `json:"content,omitempty"`
		} `json:"delta"`
		FinishReason *string `json:"finish_reason"`
	} `json:"choices"`
}

ChatCompletionStreamResponse represents a streaming chunk response

type Client

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

Client handles OpenAI API requests

func NewClient

func NewClient(apiKey string, opts ...ClientOption) *Client

NewClient creates a new OpenAI client

func (*Client) CreateChatCompletion

func (c *Client) CreateChatCompletion(
	ctx context.Context,
	req ChatCompletionRequest,
) (string, error)

CreateChatCompletion sends a non-streaming chat completion request

func (*Client) CreateChatCompletionStream

func (c *Client) CreateChatCompletionStream(
	ctx context.Context,
	req ChatCompletionRequest,
) (*StreamReader, error)

CreateChatCompletionStream sends a streaming chat completion request

func (*Client) CreateChatCompletionStreamWithMarkdown

func (c *Client) CreateChatCompletionStreamWithMarkdown(
	ctx context.Context,
	req ChatCompletionRequest,
	w io.Writer,
	opts StreamOptions,
) error

CreateChatCompletionStreamWithMarkdown sends a streaming chat completion request and renders the output incrementally as markdown using the StreamMarkdown function

type ClientOption

type ClientOption func(*Client)

ClientOption is a functional option for configuring the Client

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) ClientOption

WithHTTPClient sets a custom HTTP client

type Message

type Message struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

Message represents a single message in a chat conversation

type StreamOptions

type StreamOptions = markdown.StreamOptions

StreamOptions configures markdown streaming output for CreateChatCompletionStreamWithMarkdown.

type StreamReader

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

StreamReader provides access to streaming chat completion responses

func (*StreamReader) Close

func (s *StreamReader) Close() error

Close closes the stream

func (*StreamReader) Recv

func (s *StreamReader) Recv() (ChatCompletionStreamResponse, error)

Recv reads the next chunk from the stream