openai

package module
v1.1.1 Latest Latest
Warning

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

 Go to latest Published: Aug 11, 2026 License: MIT Imports: 15 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.
  • Structured output: ai.Format maps onto the provider's own response_format (JSON mode or a JSON Schema); read it back with resp.JSON(&v).
  • Native ChatCompletion and ChatCompletionStream with the full option set (response_format, seed, n, ...), plus the responses API.
  • Image generation fitted to the model, with ImageData.Bytes() for the image.
  • 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.
  • Hosted web search: ai.Request.Hosted routes to the responses endpoint, which is where that tool lives, and normalizes the result back to the chat vocabulary.

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.")},
})

Structured output

ai.Request.Format maps onto the provider's response_format, so a request for JSON is enforced rather than merely asked for, and ai.Response.JSON decodes the reply. Plain JSON mode also puts ai.Format.Instruction into the system prompt, because the endpoint rejects it unless the word "json" appears in the messages.

ai.Request.Hosted maps onto this provider's hosted web search tool: 

resp, err := c.Generate(ctx, &ai.Request{
    Model:    openai.ModelGPT4oMini,
    Messages: []ai.Message{ai.UserText("What shipped this week?")},
    Hosted:   []ai.Hosted{{Kind: ai.HostedWebSearch}},
})
for _, c := range resp.Citations() { ... }

That tool lives on the responses endpoint, not on chat completions, so Generate and Stream go to the responses endpoint when, and only when, a request asks for something hosted. Every other call sends the same bytes to chat completions as it always did. The two endpoints do not describe an outcome in the same words, so ai.Response.StopReason and ai.Usage are normalized to the chat vocabulary and a caller never has to know which one answered; ai.Response.Raw still holds what the endpoint actually said.

Two things do not survive that endpoint. This provider filters by allowed domains only, so ai.HostedWeb.BlockDomains and MaxUses are ai.ErrNoHosted; so are ai.Request.Stop sequences, which the responses endpoint has no field for and which are too load-bearing to drop quietly.

The sources come back as ai.Citation values on the text they support. This provider reports an index range but not what it counts in, so the range is kept only where every plausible unit agrees, which is text that is entirely ASCII; anywhere else the sources arrive without a range rather than with one that might cut a word in half. A stream never carries a range, because the indices are counted against an answer that has not finished arriving.

Images

GenerateImage fits the request to the model: the gpt-image family always answers with base64 and rejects response_format, so asking one of those models for a URL is refused here rather than by the provider. ImageData.Bytes returns the image itself.

Asking what this driver can do

Capabilities describes this driver for the decision taken before a call: whether to offer a feature at all, and whether it needs one request or two. 

if ai.SupportsHosted(c, ai.Hosted{Kind: ai.HostedWebSearch}) { ... }

It is a hint and not a permission - support also depends on the model, the account and the region - so ai.ErrNoHosted and ai.ErrNoFormat remain the source of truth and a caller still handles them. What changes is that a refusal the provider only reports as a 400 now arrives as those same sentinels, wrapped around the original ai.APIError, so one errors.Is covers a limitation this driver knew in advance and one it learned over the wire.

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 (
	ModelGPTImage1 = "gpt-image-1"
	ModelDallE3    = "dall-e-3"
	ModelDallE2    = "dall-e-2"
)

Image model identifiers. Any model string is accepted.

View Source 
const (
	ImageFormatURL     = "url"
	ImageFormatB64JSON = "b64_json"
)

The values ImageRequest.ResponseFormat accepts.

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

View Source 
var (
	// ErrNoImageRequest is returned by GenerateImage for a nil request.
	ErrNoImageRequest = errors.New("openai: image request is nil")

	// ErrImageFormat is returned before the request is sent, when the chosen
	// model cannot return images in the format asked for.
	ErrImageFormat = errors.New("openai: model cannot return that image format")

	// ErrNoImageBytes is returned by ImageData.Bytes for an image the provider
	// returned as a URL. Fetch the URL, or ask for ImageFormatB64JSON.
	ErrNoImageBytes = errors.New("openai: image was returned as a URL")
)

Errors reported for an image request or its result.

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) Capabilities added in v1.1.0 

func (c *Client) Capabilities() ai.Capabilities

Capabilities describes what this driver can be asked for. It is a hint for the decision taken before a call - whether to offer a feature, and whether it needs one request or two - and never a substitute for handling ai.ErrNoHosted, ai.ErrNoFormat or ai.ErrFormatWithHosted, because support also depends on the model, the account and the region.

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 into memory. It is the convenience form of FileContentTo and reads the body under a hard ceiling; use FileContentTo for a file that may exceed it.

func (*Client) FileContentTo added in v0.2.0 

func (c *Client) FileContentTo(ctx context.Context, id string, w io.Writer) error

FileContentTo downloads a file's contents and writes them to w, streaming the body rather than buffering it in memory. Prefer it for large files.

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.

A request that asks for a hosted capability goes to the responses endpoint instead, because that is the only one that can run one. What comes back is the same shape either way; see the responses path for what is normalized.

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.

The request is fitted to the model first. The gpt-image family always answers with base64 and rejects response_format outright, so for those models the field is dropped when it asks for base64, and asking them for a URL is reported as ErrImageFormat before anything is sent - rather than becoming a successful reply whose URL is empty. Every other model receives the request unchanged.

Read the image with ImageData.Bytes.

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. It is the convenience form of SpeechTo and reads the body under a hard ceiling; use SpeechTo for a long input whose audio may exceed it.

func (*Client) SpeechTo added in v0.2.0 

func (c *Client) SpeechTo(ctx context.Context, req *SpeechRequest, w io.Writer) error

SpeechTo synthesizes audio for the given text and writes it to w, streaming the body rather than buffering it in memory. Prefer it for long inputs.

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.

A request that asks for a hosted capability streams from the responses endpoint instead, for the same reason Client.Generate does: it is the only one that can run one. Splitting only Generate would leave a caller able to search in one call and not the other, which is not a shared interface.

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.

func (ImageData) Bytes added in v0.3.0 

func (d ImageData) Bytes() ([]byte, error)

Bytes returns the decoded image. It reads what the provider put inline and does no I/O: an image delivered as a URL returns ErrNoImageBytes, because fetching it is a network call with the caller's own timeouts, redirects and proxy rules, not something a field accessor should decide.

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 is ImageFormatURL or ImageFormatB64JSON. Models that
	// always answer with base64 do not accept the field at all; see
	// [Client.GenerateImage] for what happens then.
	ResponseFormat string `json:"response_format,omitempty"`

	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 IncompleteDetails added in v1.0.0 

type IncompleteDetails struct {
	Reason string `json:"reason,omitempty"`
}

IncompleteDetails says why a response stopped before it was finished.

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 ResponseAnnotation added in v1.0.0 

type ResponseAnnotation struct {
	Type       string `json:"type"`
	URL        string `json:"url,omitempty"`
	Title      string `json:"title,omitempty"`
	StartIndex int    `json:"start_index,omitempty"`
	EndIndex   int    `json:"end_index,omitempty"`
}

ResponseAnnotation marks a stretch of output text. A "url_citation" names a source a hosted search used.

type ResponseContent added in v1.0.0 

type ResponseContent struct {
	Type        string               `json:"type"`
	Text        string               `json:"text,omitempty"`
	Annotations []ResponseAnnotation `json:"annotations,omitempty"`
}

ResponseContent is one content part of a message output item.

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"`
	ID        string            `json:"id,omitempty"`
	Status    string            `json:"status,omitempty"`
	Role      string            `json:"role,omitempty"`
	Content   []ResponseContent `json:"content,omitempty"`
	CallID    string            `json:"call_id,omitempty"`
	Name      string            `json:"name,omitempty"`
	Arguments string            `json:"arguments,omitempty"`
}

ResponseOutput is one output item from the responses API. Type selects which fields apply: "message" carries Content, "function_call" carries CallID, Name and Arguments, and a provider-run item such as "web_search_call" records work this endpoint did on its own.

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"`

	// Annotation carries one source, on a
	// "response.output_text.annotation.added" event.
	Annotation *ResponseAnnotation `json:"annotation,omitempty"`
}

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 ResponseText added in v1.0.0 

type ResponseText struct {
	Format json.RawMessage `json:"format,omitempty"`
}

ResponseText carries the response format for this endpoint.

type ResponseTool added in v1.0.0 

type ResponseTool struct {
	Type string `json:"type"`

	Name        string          `json:"name,omitempty"`
	Description string          `json:"description,omitempty"`
	Parameters  json.RawMessage `json:"parameters,omitempty"`

	// Filters narrows a search, and UserLocation biases it.
	Filters      *WebSearchFilters     `json:"filters,omitempty"`
	UserLocation *ResponseUserLocation `json:"user_location,omitempty"`
}

ResponseTool is one entry of the tools list. Type selects which of the remaining fields apply: "function" uses Name, Description and Parameters, while a provider-run tool such as "web_search" uses the fields below them.

type ResponseUserLocation added in v1.0.0 

type ResponseUserLocation struct {
	Type     string `json:"type"`
	City     string `json:"city,omitempty"`
	Region   string `json:"region,omitempty"`
	Country  string `json:"country,omitempty"`
	Timezone string `json:"timezone,omitempty"`
}

ResponseUserLocation biases search results towards a place. Type is "approximate".

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"`
	TopP            *float64 `json:"top_p,omitempty"`
	Store           *bool    `json:"store,omitempty"`
	Stream          bool     `json:"stream,omitempty"`

	// Tools carries both the caller's functions and the provider's own tools,
	// such as web search. Without it this endpoint cannot be asked to search,
	// which is the reason the shared path uses it at all.
	Tools      []ResponseTool `json:"tools,omitempty"`
	ToolChoice any            `json:"tool_choice,omitempty"`

	// Text is where this endpoint takes the response format, unlike chat
	// completions which takes a response_format of its own.
	Text *ResponseText `json:"text,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"`

	// IncompleteDetails says why a response stopped short, when it did.
	IncompleteDetails *IncompleteDetails `json:"incomplete_details,omitempty"`
}

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").

type WebSearchFilters added in v1.0.0 

type WebSearchFilters struct {
	AllowedDomains []string `json:"allowed_domains,omitempty"`
}

WebSearchFilters narrows a hosted search. This provider offers a list of domains to keep and none to exclude.

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.