groq
RepositoryFreeThe official Python library for the groq API
Capabilities13 decomposed
synchronous and asynchronous chat completion streaming with unified interface
Medium confidenceProvides 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.
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.
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
Medium confidenceAll 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.
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).
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
Medium confidenceStreaming 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.
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.
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
Medium confidenceSDK 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.
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.
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
Medium confidenceSDK 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).
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.
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
Medium confidenceBoth 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.
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.
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
Medium confidenceThe 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.
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.
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
Medium confidenceThe 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.
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.
More convenient than chaining separate transcription and translation APIs because it's a single request; reduces latency and complexity compared to multi-step pipelines.
text-to-speech synthesis with audio format selection
Medium confidenceThe audio.speech resource converts text input to audio using Groq's speech synthesis models. Returns binary audio data in specified format (MP3, WAV, OGG, FLAC). Voice selection and speaking rate are configurable. Response is a binary stream that can be written directly to file or piped to audio playback systems.
Returns raw binary audio stream rather than base64-encoded data, enabling direct file writing and streaming without decoding overhead. Format selection is transparent to the client; httpx handles Content-Type negotiation.
More efficient than APIs returning base64 because binary streaming avoids encoding/decoding overhead; simpler than managing raw audio buffers because SDK handles format conversion.
batch operation submission, retrieval, and cancellation
Medium confidenceThe batches resource enables asynchronous processing of multiple requests in a single batch job. Supports create() to submit batch files (JSONL format), retrieve() to poll job status, and cancel() to stop in-progress jobs. Batch results are stored server-side and retrieved via file IDs. Useful for non-time-critical bulk processing (e.g., embedding large datasets, batch inference).
Batch API abstracts JSONL serialization and file upload, allowing developers to pass Python objects that are automatically converted to JSONL format. Status polling is explicit (no webhooks), giving clients full control over retry logic.
More cost-effective than individual API calls because batches have lower per-request pricing; simpler than managing JSONL files manually because SDK handles serialization.
file upload and management with lifecycle operations
Medium confidenceThe files resource provides create() to upload files, list() to enumerate uploaded files, retrieve() to fetch file metadata, and delete() to remove files. Files are stored server-side and referenced by ID in batch operations and other API calls. Supports binary file uploads via multipart form encoding.
File operations are resource-based (create, list, retrieve, delete) following REST conventions, making them intuitive for developers familiar with standard CRUD patterns. File IDs are opaque strings managed by Groq, eliminating client-side file path management.
Simpler than managing files in external storage (S3, GCS) because file lifecycle is integrated into the SDK; more convenient than raw HTTP uploads because multipart encoding is handled automatically.
model listing and metadata retrieval
Medium confidenceThe models resource provides list() to enumerate available models and retrieve() to fetch metadata for a specific model. Returns model identifiers, context windows, pricing, and availability status. Useful for dynamic model selection based on capabilities or cost constraints.
Model metadata is returned as Pydantic models with helper methods, enabling type-safe access to capabilities. No caching; each call fetches fresh data from API, ensuring up-to-date information.
More reliable than hardcoded model lists because it reflects actual API state; simpler than parsing documentation because metadata is structured and queryable.
text embedding generation with vector output
Medium confidenceThe embeddings resource converts text input to dense vector embeddings using Groq's embedding models. Accepts single strings or lists of strings and returns vectors of fixed dimensionality. Useful for semantic search, clustering, and similarity comparisons. Vectors are returned as lists of floats.
Embeddings are returned as Pydantic models with vector field as list of floats, enabling direct use with numpy/scipy for similarity calculations. No special vector format; standard Python lists for maximum compatibility.
Simpler than managing separate embedding services because it's integrated into the SDK; more convenient than raw API calls because batch handling is transparent.
Capabilities are decomposed by AI analysis. Each maps to specific user intents and improves with match feedback.
Related Artifactssharing capabilities
Artifacts that share capabilities with groq, ranked by overlap. Discovered automatically through the match graph.
openai
The official Python library for the openai API
Unofficial API in Python
[TLS-based API (Python)](https://github.com/rawandahmad698/PyChatGPT)
cohere
Python AI package: cohere
WeKnora
LLM-powered framework for deep document understanding, semantic retrieval, and context-aware answers using RAG paradigm.
magentic
Seamlessly integrate LLMs as Python functions
Unofficial API in JS/TS
[Unofficial API in Dart](https://github.com/MisterJimson/chatgpt_api_dart)
Best For
- ✓Python developers building LLM applications requiring low-latency inference
- ✓Teams building async-first services with high concurrency requirements
- ✓Developers migrating from other LLM SDKs (OpenAI, Anthropic) seeking API parity
- ✓Teams using strict type checking (mypy, pyright) in production codebases
- ✓Developers building frameworks or libraries that wrap Groq SDK
- ✓Projects requiring audit trails of API requests/responses with guaranteed schema compliance
- ✓Real-time chat interfaces (web, mobile, CLI)
- ✓Streaming audio processing pipelines
Known Limitations
- ⚠Streaming responses consume memory proportional to token generation rate; no built-in backpressure handling for slow consumers
- ⚠Synchronous client blocks event loop in async contexts; requires explicit thread pool for concurrent sync calls
- ⚠aiohttp backend requires separate installation and configuration; httpx is default but may have different timeout semantics
- ⚠Pydantic validation adds ~5-10ms overhead per request for complex nested parameters
- ⚠TypedDict is Python 3.8+ only; no support for Python 3.7 or earlier
- ⚠Custom validation rules beyond Pydantic's built-in validators require subclassing models
Requirements
Input / Output
UnfragileRank
UnfragileRank is computed from adoption signals, documentation quality, ecosystem connectivity, match graph feedback, and freshness. No artifact can pay for a higher rank.
Repository Details
Package Details
About
The official Python library for the groq API
Categories
Alternatives to groq
Are you the builder of groq?
Claim this artifact to get a verified badge, access match analytics, see which intents users search for, and manage your listing.
Get the weekly brief
New tools, rising stars, and what's actually worth your time. No spam.
Data Sources
Looking for something else?
Search →