synchronous and asynchronous chat completion streaming with unified interface
Provides dual-mode (Groq sync, AsyncGroq async) client classes that expose identical interfaces for chat completions with native streaming support via httpx. Both clients handle authentication, retries, timeouts, and error handling uniformly, with optional aiohttp backend for improved async concurrency. Streaming responses are consumed as iterators, enabling real-time token-by-token processing without buffering entire responses.
Unique: Auto-generated from OpenAPI specs via Stainless framework, ensuring 100% API surface coverage with zero manual endpoint definitions. Unified sync/async interface eliminates code duplication while maintaining identical error handling, retry logic, and timeout semantics across both client modes.
vs alternatives: Faster than hand-rolled REST clients due to Stainless code generation, and more maintainable than OpenAI SDK because API changes auto-propagate from OpenAPI specs without manual SDK updates.
type-safe request/response validation with pydantic models and typeddict parameters
All request parameters are defined as TypedDict structures and response objects as Pydantic models, providing compile-time type hints and runtime validation. Request payloads are validated before transmission, and responses are automatically deserialized and validated against schemas, catching malformed API responses early. Helper methods like to_json() and to_dict() enable flexible serialization for downstream processing.
Unique: Stainless-generated models are synchronized with OpenAPI specs, meaning schema changes in Groq's API automatically propagate to the SDK without manual model updates. Pydantic v2 integration enables discriminated unions for polymorphic response types (e.g., different message types in chat responses).
vs alternatives: More robust than requests-based clients because validation happens before transmission, catching parameter errors locally rather than as 400 errors from the API.
streaming response consumption with iterator pattern
Streaming responses (chat completions, audio) are returned as Python iterators that yield chunks as they arrive from the server. Enables real-time processing without buffering entire responses. Iterators support context managers for automatic cleanup. Chunks are Pydantic models with delta fields for incremental updates.
Unique: Streaming is implemented as Python iterators rather than callbacks, enabling natural for-loop consumption and context manager cleanup. httpx handles HTTP chunked transfer encoding transparently.
vs alternatives: More Pythonic than callback-based streaming because it uses standard iterator protocol; simpler than manual HTTP streaming because chunk parsing is handled by SDK.
environment-based api key configuration with fallback to explicit parameters
SDK automatically reads GROQ_API_KEY from environment variables during client initialization. Supports .env file loading via python-dotenv (optional). Explicit API key parameter overrides environment variable. Enables secure credential management without hardcoding secrets in source code.
Unique: API key is read once during client initialization and stored in the client instance, eliminating repeated environment lookups. Explicit parameter takes precedence over environment variable, enabling programmatic override without modifying environment.
vs alternatives: More secure than hardcoded keys because credentials are externalized; simpler than manual environment parsing because SDK handles lookup automatically.
error handling with typed exception hierarchy and api error details
SDK defines a typed exception hierarchy (APIError, APIConnectionError, APITimeoutError, RateLimitError, etc.) that maps to specific failure modes. Exceptions include response status, error message, and request details for debugging. Enables granular error handling based on failure type (e.g., retry on RateLimitError, fail fast on validation errors).
Unique: Exception types are generated from OpenAPI specs, ensuring they match actual API error responses. Each exception includes full response context (headers, body) for debugging without additional API calls.
vs alternatives: More informative than generic HTTP exceptions because it includes API-specific error details; simpler than parsing raw responses because exception types encode error semantics.
automatic retry and timeout management with exponential backoff
Both Groq and AsyncGroq clients implement built-in retry logic with exponential backoff for transient failures (5xx errors, connection timeouts). Timeout values are configurable per-request and globally, with sensible defaults. Retries respect HTTP 429 (rate limit) headers and implement jitter to prevent thundering herd problems in distributed systems.
Unique: Retry logic is built into the httpx transport layer rather than application code, ensuring consistent behavior across all API resources without per-endpoint configuration. Jitter implementation prevents synchronized retries in distributed deployments.
vs alternatives: More reliable than manual retry loops because it's transparent to application code and respects HTTP semantics (429 headers, idempotency). Simpler than tenacity/backoff libraries because it's integrated into the client.
audio transcription with file upload and format support
The audio.transcriptions resource accepts audio files (WAV, MP3, FLAC, OGG) via multipart form upload and returns transcribed text with optional timestamps. Files are streamed to Groq's API without loading entirely into memory, supporting files larger than available RAM. Language detection is automatic or can be specified explicitly.
Unique: Multipart form upload is handled transparently by httpx; SDK abstracts file streaming so developers pass file paths or file objects without managing Content-Type headers or boundary encoding. Automatic format detection from file extension.
vs alternatives: Simpler than raw httpx because file handling is encapsulated; more efficient than loading entire files into memory before transmission.
audio translation with cross-language support
The audio.translations resource accepts audio files in any supported language and translates the transcribed content to English (or specified target language). Uses the same multipart upload mechanism as transcription but adds language pair routing. Translation happens server-side after transcription, so latency includes both speech-to-text and translation steps.
Unique: Translation is performed server-side after transcription, eliminating the need for separate translation API calls. Language detection is automatic, so developers don't need to specify source language.
vs alternatives: More convenient than chaining separate transcription and translation APIs because it's a single request; reduces latency and complexity compared to multi-step pipelines.
+5 more capabilities