OpenAI Dive

OpenAI Dive is an unofficial, community-maintained Rust crate that wraps the OpenAI HTTP API in a fully async, strongly typed client. It goes well beyond chat completions, exposing Responses, Images, Audio, Videos, Files, Embeddings, Moderations, Uploads, Fine-tuning, Batches, Administration, Usage, and Realtime WebSocket endpoints behind a consistent client.<domain>().<action>() pattern built on reqwest and tokio.

Because it targets the OpenAI HTTP surface rather than a proprietary transport, the same client works against any OpenAI-compatible API — the maintainers explicitly document swapping the base URL to talk to DeepSeek, and expose extra_body/query_params escape hatches on request parameters for non-standard provider extensions. Cargo feature flags (reqwest, stream, download, realtime, rustls-tls) let consumers compile out unused transport code, keeping the crate lean for narrower use cases like fine-tuning-only or embeddings-only integrations.

What You Get

• A single Client struct (Client::new, new_from_env, set_base_url, set_organization, set_project) that authenticates once and exposes every API domain as a typed sub-client, e.g. client.chat(), client.images(), client.responses().
• Builder-pattern request types for every endpoint (via derive_builder), so complex payloads like ChatCompletionParametersBuilder are constructed with compile-time-checked required fields instead of loosely typed maps.
• First-class streaming support behind the stream feature, using reqwest-eventsource for server-sent events on chat/response completions.
• A dedicated realtime feature exposing the GPT-4o-class Realtime API over WebSockets via reqwest-websocket, including typed client and server event enums.
• 45+ runnable examples across the workspace (examples/chat, examples/responses, examples/audio, examples/administration, examples/deepseek, etc.) mirroring every documented capability.
• A closed APIError enum (auth, rate-limit, not-found, server, parse, stream, websocket, and more) so callers can pattern-match on failure modes instead of inspecting raw HTTP status codes.

Common Use Cases

• Building a Rust backend service that calls GPT models for chat, structured outputs, or function calling without hand-rolling HTTP request/response types.
• Streaming token-by-token chat completions into a Rust CLI or server using the stream feature and reqwest-eventsource.
• Talking to OpenAI-compatible third-party APIs (e.g. DeepSeek) from the same codebase by swapping set_base_url and using the extra_body/query_params escape hatches.
• Running batch or fine-tuning jobs from Rust tooling via the Batches and Fine-tuning endpoint wrappers instead of shelling out to the Python SDK.
• Building a realtime voice or live-transcription integration against the GPT-4o Realtime WebSocket API from a Rust application.

Under The Hood

Architecture The crate is a layered client SDK: a single Client struct in api.rs owns the reqwest::Client, base URL, API key, and optional organization/project headers, plus generic post/get/delete helpers that build requests and run them through check_status_code and format_response (in helpers.rs) to turn non-2xx responses into typed APIError variants. Roughly eighteen domain modules under v1/endpoints/ (chat, responses, images, audio, files, fine_tuning, batch, administration, usage, realtime, and more) each define a thin wrapper type (e.g. Chat<'a> holding &Client) with async methods like create/create_wrapped that call the shared transport helpers and deserialize into request/response DTOs defined in the parallel v1/resources/ tree. Cargo feature flags gate the transport layer (reqwest, endpoints, helpers, api modules only compile with the reqwest feature) while error, models, and resources stay always-available, so downstream crates can depend on the typed models without pulling in an HTTP stack. Because every endpoint module calls the same Client::post/get/delete surface directly, a change to the core transport abstraction would ripple through all eighteen-plus endpoint files.

Tech Stack Rust 2021 edition, organized as a Cargo workspace with the library crate (openai_dive) plus 45+ standalone example crates. HTTP transport is reqwest 0.12 (optional, default-features = false, with json/stream/multipart features), async runtime is tokio 1 (optional), streaming uses reqwest-eventsource 0.6, and the realtime feature adds reqwest-websocket 0.4. Serialization runs on serde/serde_json plus serde_html_form for query-string encoding, bytes (with the serde feature) for binary payloads like audio and file uploads, and derive_builder 0.20 powers the *ParametersBuilder pattern used across every request type. Optional features add base64/futures for streamed downloads and rustls-tls as an alternative to the default TLS backend. CI runs three separate GitHub Actions workflows — cargo build (default, no-default-features, and rustls variants), cargo clippy, and cargo fmt — on every push and pull request; the crate is published to crates.io and documented on docs.rs.

Code Quality Error handling is explicit and typed throughout: every public method returns Result<T, APIError>, and APIError is a closed enum of about a dozen variants (authentication, rate-limit, not-found, server, parse, stream, websocket, and more) mapped directly from HTTP status codes rather than a boxed/dynamic error type. Naming is consistent — PascalCase types, snake_case methods, and a uniform {Domain}Parameters/{Domain}Response pairing per endpoint, with derive_builder-generated builders enforcing required fields at compile time. Test coverage is thin: only 8 test functions were found in the whole crate, confined to resources/audio.rs and resources/chat.rs, exercising serde (de)serialization of enum-heavy message content rather than transport or error-handling behavior; there is no coverage for api.rs, helpers.rs, or the sixteen-plus other endpoint modules. Linting is enforced in CI via cargo clippy and cargo fmt (with a project rustfmt.toml) on every push and pull request.

API Design The public API reads as a fluent domain-per-method surface — client.chat().create(parameters), client.images().create(parameters), client.realtime().connect() — with builder types for every non-trivial request so callers get compile-time feedback on missing required fields instead of runtime JSON errors. Escape hatches (extra_body, query_params) are deliberately exposed on parameter structs so the same typed client works against OpenAI-compatible third-party providers without library changes. Documentation is unusually thorough for a community SDK: the crate-level doc comment in lib.rs mirrors the full README with runnable examples for every endpoint family, and the workspace ships 45+ standalone example crates covering everything from basic chat to realtime WebSocket sessions and DeepSeek compatibility, keeping the learning curve low despite the API’s breadth.