openai

Overview ¶

Package openai implements reusable OpenAI wire adapters for native and compatible provider endpoints.

A nonempty Config BaseURL overrides OPENAI_BASE_URL; an absent environment value uses the SDK production endpoint. Construction validates and freezes only that effective URL. Official SDK service constructors apply the binding's explicit credentials, endpoint, headers, and HTTP client without inheriting unrelated SDK environment settings.

Chat Completions accepts typed tools with identifiable calls. Deprecated functions cannot be replayed as modern tool results. Native credential, response identity and tool or embedding indexes never default to another response or input. Core embeddings use numeric float vectors.

Unary JSON responses and HTTP error envelopes are admitted within Core's httpclient.DefaultMaxJSONResponseBytes before SDK decoding. Successful SSE uses that budget per wire event, including its framing, and has no aggregate ceiling. SpeechModelConfig.MaxResponseBytes bounds Call's aggregate audio; Stream remains incremental. An oversized result never becomes partial success.

Modalities exposed:

• chat (Chat Completions) via NewChatCompletions — tool calling, streaming, native request extensions, vision input, audio input/output;
• chat (Responses) via NewResponses — ordered reasoning and tool replay, streaming, multimodal input, and complete-request input-token counting through the native Responses endpoint;
• embedding via NewEmbeddingModel — text-embedding-3-small/large with dimension truncation;
• image via NewImageModel — GPT image generation;
• moderation via NewModerationModel — omni-moderation-latest;
• speech via NewSpeechModel — tts-1, tts-1-hd, gpt-4o-mini-tts;
• audio transcription via NewTranscriptionModel — whisper-1, gpt-4o-transcribe, gpt-4o-mini-transcribe;
• audio translation via NewAudioTranslationModel — whisper-1 translating any source language to English (implements transcription.Model).

ChatCompletions.ListModels and Responses.ListModels discover IDs visible to the same credential, endpoint, and HTTP client. Discovery uses the SDK's Models endpoint with caller-supplied count, byte, and context budgets. Results are complete or fail without exposing partial IDs; catalog enrichment, selection, sorting, and deduplication remain consumer policy.

Model id constants aren't exported here — they're maintained by openai-go (openai.ChatModelGPT5_6Sol, openai.EmbeddingModelTextEmbedding3Large, etc.). Import openai-go directly when you need them.

Provider-specific fields not modeled by Core reach the wire through request extensions scoped to the endpoint provider. Raw response details use that same namespace, so compatible endpoints never leak OpenAI provider metadata. Core ownership does not depend on endpoint support: unsupported Core options remain reserved in raw extensions and dialect callbacks. Responses rejects native frequency_penalty, presence_penalty, top_k, and stop. Image dimensions belong to Core and project to size; seed and negative_prompt remain unsupported. Image response_format selects native delivery, independently of Core's image MIME OutputFormat, and remains available through the extension. Audio transcription and translation extensions use the SDK's typed multipart fields. Unknown fields, nulls, and empty arrays are rejected because the SDK cannot preserve them in that form. Their response_format must select JSON; text, srt, and vtt require a different decoder. Image, transcription, and translation calls own their unary mode, so extensions cannot enable streaming. Image output formats are PNG, JPEG, and WebP. Reported response formats own the generated media's MIME type; an absent format uses the requested format or the provider's PNG default. Unknown response formats are invalid responses.

Chat Completions owns its single output. Neither a raw request extension nor a compatible dialect can set n. Core Options.TopK is projected only when the binding's SupportsTopK facet is enabled. Neither raw extensions nor request callbacks may supply top_k. Standard Chat Completions requests stream_options.include_usage by default for both Call and Stream. Explicit false or null stream_options are respected; compatible providers retain their own request policy. Missing provider usage remains unknown, never a fabricated zero. Generated Chat audio retains its bytes and provider replay ID together. Assistant audio with an inline payload uses Media.ID for replay; provider references remain valid without an inline payload. Responses rejects assistant media history that its input projection cannot represent. Responses tools use non-strict mode to preserve the caller's optional JSON Schema properties. Inline file inputs and tool outputs retain their declared MIME in a data URL; bare base64 cannot establish the file type expected by the Responses API.

Strict output schemas keep the caller's accepted values: representable allOf intersections are lowered once for Chat Completions and Responses. Optional properties, open objects, and unsupported constraints fail locally with chat.ErrUnsupportedOutputFormat rather than changing the domain contract.

Responses Call and Stream share terminal-state mapping: incomplete generation preserves its stop reason, failed generation returns an error, and a stream ending before a terminal response returns chat.ErrInvalidResponse. Each Responses reasoning segment keeps a distinct Core Part. Part.Text owns visible summary or content text; ReasoningState retains segment identities and one completed native item without text copies. Replay requires that complete state and its Core text parts from the same provider. Frames carry the issuing binding's provider namespace; foreign state is omitted from native replay. Unscoped frames and full native items are rejected. Preserve signed content and native fields when replaying. Completed reasoning must agree with streamed text and its item completion; contradictory or unfinished items cannot produce a successful terminal delta. Assistant message identity and phase remain separate from visible text so commentary and final answers retain their original boundaries during replay.

Provider packages with an OpenAI-compatible endpoint reuse the protocol through NewChatCompletions and select one typed DialectConfig. This keeps provider-only fields such as reasoning_content out of OpenAI's native behavior while sharing the standard wire mapping. Construction freezes that configuration; its provider namespace supplies both extension keys and the reasoning codec's replay issuer. Later configuration edits cannot relabel previously constructed adapters. APIKey alone supplies credentials; Headers cannot replace or add a second authentication source. Moderation reads the native category flags and scores before the SDK's scalar fields can erase absence. Each reported category needs both a flag and score; future category names are retained. Slash and hyphen normalization must not collide, and missing flags never become false.