Download the PHP package lucianotonet/groq-php without Composer

Groq PHP

High-performance PHP client for GroqCloud API

A comprehensive PHP SDK that simplifies interaction with the world's fastest LLM inference platform, allowing PHP developers to easily integrate high-performance models (DeepSeek r1, Llama 3.3, Mixtral, Gemma, and more) into any PHP application.

Using on Laravel? Check this out: GroqLaravel

Features

• [x] Chat Completions
• [x] Tool Calling
• [x] Audio Transcription and Translation
• [x] Text-to-Speech
• [x] Vision
• [x] Reasoning
• [x] Files and Batch Processing
• [x] Built-in Tools & Compound (web search, code execution)
• [x] Documents (RAG) & Citations
• [x] Responses API
• [x] Prompt Caching & Content Moderation

Installation

Configuration

1. Get your API Key:

   • Go to GroqCloud Console
   • Create a new API key

2. Configure your API Key:

   • Using environment variables:

   • Or using a .env file:

Usage

1. Listing Models

List available models.

Retrieve a single model by its ID:

2. Chat (Completions)

Generate interactive chat responses.

Streaming:

JSON Mode:

Structured Outputs (json_schema):

Guarantee the response conforms to a JSON schema. In strict mode the model uses constrained decoding, so the output always matches the schema exactly.

Additional Parameters (Chat Completions):

• temperature: Controls randomness (0.0 - 2.0)
• max_completion_tokens: Maximum tokens in response
• top_p: Nucleus sampling
• frequency_penalty: Penalty for repeated tokens (-2.0 - 2.0)
• presence_penalty: Penalty for repeated topics (-2.0 - 2.0)
• stop: Stop sequences
• seed: For reproducibility

3. Tool Calling

Allows the model to call external functions/tools.

Advanced Tool Calling (with multiple tools and parallel calls):

See examples/tool-calling-advanced.php for a more complete example, including:

• Definition of multiple tools (e.g., getCurrentDateTimeTool, getCurrentWeatherTool)
• parallel_tool_calls: Controls whether tool calls can be made in parallel (currently must be forced false in code)

4. Audio (Transcription, Translation and Text-to-Speech)

Transcription and Translation

• Response formats: 'json', 'verbose_json', 'text'. The vtt and srt formats are not supported.
• language: ISO 639-1 code of the source language (optional but recommended for better accuracy). See examples/audio-transcriptions.php for a complete list of supported languages.
• temperature: Controls variability.

Text-to-Speech (TTS)

Convert text to speech using GroqCloud's Text-to-Speech API.

• Models: 'canopylabs/orpheus-v1-english' (English), 'canopylabs/orpheus-arabic-saudi' (Arabic)
• Parameters:
  • model(): The TTS model to use
  • input(): Text to convert to speech (Orpheus models accept a maximum of 200 characters)
  • voice(): Voice identifier (e.g., "troy")
  • responseFormat(): Output format. Orpheus models only support "wav" (default)
• Methods:
  • create(): Returns audio content as stream
  • save($filePath): Saves audio to a file and returns success boolean

5. Vision

Analyze images using Groq's vision models.

Vision Model: The vision functionality uses the qwen/qwen3.6-27b model by default, which supports:

• Local image analysis (up to 4MB)
• URL image analysis (up to 20MB)
• Multi-turn conversations
• Tool use
• JSON mode

6. Reasoning

Enables step-by-step reasoning tasks.

• analyze(): Takes the prompt (question/problem) and an options array.
• reasoning_format: (not supported by openai/gpt-oss models)
  • 'raw': Includes reasoning with <think> tags in content (default)
  • 'parsed': Returns reasoning in a separate reasoning field
  • 'hidden': Returns only the final answer
• include_reasoning: (bool) Whether to include reasoning in message.reasoning. Mutually exclusive with reasoning_format. For openai/gpt-oss models use this instead (e.g., 'hidden' → include_reasoning => false).
• reasoning_effort: (string) Reasoning effort for supported models — none/default for qwen/qwen3.6-27b; low/medium/high for openai/gpt-oss-*.
• system_prompt: Additional instructions for the model (optional). Added as a system message before the user message.
• Must use 'parsed' or 'hidden' format when using JSON mode
• Optional parameters: temperature, max_completion_tokens, top_p, frequency_penalty, service_tier (auto|on_demand|flex|performance|null), etc.

Reasoning Formats

The reasoning feature supports three output formats:

1. Raw Format (Default)

   • Includes reasoning steps within <think> tags in the content
   • Best for debugging and understanding the model's thought process

2. Parsed Format

   • Separates reasoning into a dedicated field
   • Ideal for applications that need to process reasoning steps separately
3. Hidden Format
   • Returns only the final answer without showing reasoning steps
   • Best for production applications where only the result matters

7. Files and Batch Processing

Process large volumes of data asynchronously using Groq's Files and Batch Processing API.

File Management

Batch Processing

File Requirements:

• Format: JSONL (JSON Lines)
• Size: Up to 100MB
• Content: Each line must be a valid JSON object with required fields:
  • custom_id: Your unique identifier for tracking the batch request
  • method: The HTTP method (currently POST only)
  • url: The API endpoint to call (one of: /v1/chat/completions, /v1/audio/transcriptions, or /v1/audio/translations)
  • body: The parameters of your request matching to any synchronous API format like messages for chat, url for audio, etc.

Example JSONL file:

Supported Features:

• File management with upload, file type and content validations
• Batch creation and management
• Progress tracking
• Error handling
• Metadata support
• Caching for downloaded files

Completion Windows:

• Available options: 24h, 48h, 72h, 96h, 120h, 144h, 168h, 7d
• Default: 24h

Batch Statuses:

• validating
• in_progress
• completed
• failed
• expired
• cancelled
• cancelling
• finalizing

8. Error Handling

The library throws GroqException for API errors. The exception contains:

• getMessage(): Descriptive error message
• getCode(): HTTP status code (or 0 for invalid API key)
• getType(): Error type (see GroqException::ERROR_TYPES for possible types)
• getHeaders(): HTTP response headers
• getResponseBody(): Response body (as object if JSON)
• getError(): Returns array with error details (message, type, code)
• getFailedGeneration(): If error type is failed_generation, returns the invalid JSON that caused the issue

The GroqException class provides static methods for creating specific exceptions like invalidRequest(), authenticationError(), etc., following a factory pattern.

9. Built-in Tools & Compound

Groq's Compound systems (compound-beta, compound-beta-mini) ship server-side tools (web search, visit website, code execution, Wolfram Alpha) that run without any local function-calling setup. Use LucianoTonet\GroqPHP\BuiltInTools to build the compound_custom payload:

See examples/built-in-tools.php for a runnable script.

10. Documents (RAG) & Citations

Provide context documents directly in the request via the documents parameter. When citation_options is enabled, the model includes citations referencing those documents:

BuiltInTools::document() builds a text document; BuiltInTools::documentFromFile() builds one backed by a file previously uploaded via the Files API.

Model support: documents and citation_options are forwarded as-is, but only models that enable them accept them. The historical RAG models (llama-3.3-70b-versatile, llama-3.1-8b-instant) were retired on 2026-08-16 for free/developer tiers, so on those tiers the current models (openai/gpt-oss-*, qwen/qwen3.6-27b, compound-beta) reject documents with not supported with this model. Enterprise accounts with a committed-spend contract may still have access to the legacy RAG models.

11. Responses API

Groq's Responses API (beta) is compatible with OpenAI's Responses API: it uses a single input field (a string or an array of input items), returns an output array of generated items, and supports structured outputs, reasoning controls and tool calling.

Streaming:

Structured outputs follow the Responses API shape (text.format with type: json_schema):

See examples/responses.php for a runnable script.

Prompt Caching & Content Moderation

Prompt Caching

Groq enables automatic prompt caching on supported models (e.g. openai/gpt-oss-120b, openai/gpt-oss-20b, kimi-k2). There is no code change and no extra cost: when a request shares a common prefix with a recent one, Groq reuses the cached computation, cutting latency and giving a 50% discount on cached input tokens.

• Caching is prefix-based and exact-match: identical content must appear at the start of the prompt.
• Place static content (system instructions, tool definitions, few-shot examples, schemas, large context) first, and dynamic content (user queries, timestamps, IDs) last, to maximize cache hits.
• Monitor hits via the usage field: cached tokens are reported under usage.prompt_tokens_details.cached_tokens (Chat Completions and Responses API).
• Cached data lives in volatile memory and expires automatically after a short period (a few hours); there is no manual cache management.

Content Moderation

Groq does not expose a separate moderation endpoint; instead it provides safeguard models that you call through the standard Chat Completions API:

• openai/gpt-oss-safeguard-20b — recommended. A policy-following reasoning model for custom Trust & Safety workflows (bring-your-own-policy). It returns a structured JSON decision.
• meta-llama/Llama-Guard-4-12B — a multimodal safeguard model that classifies content against the MLCommons 14-category taxonomy and returns safe or unsafe\nSX. Scheduled for deprecation on 2026-10-02; prefer openai/gpt-oss-safeguard-20b for new integrations.

A common pattern is to pre-screen user input (and optionally the model output) with a safeguard model before responding.

See examples/content-moderation.php for a runnable script.

Examples

The examples/ folder contains complete, working PHP scripts demonstrating each library feature. You can run them directly to see the library in action and interact with on your browser.

First, you need to copy your .env file from the root of the project to the examples folder.

Then, in the examples folder, you need to install the dependencies with:

Now, you can start the server with:

Finally, you can access the examples in your browser at http://127.0.0.1:8000.

Tests

The tests/ folder contains unit tests. Run them with composer test. By default they run against an offline mock and need no API key; set GROQ_LIVE_TESTS=1 (and a GROQ_API_KEY) to exercise the real API.

Note: The default test suite runs against an offline mock (no API credits). Live tests that hit the real Groq API run only on a nightly schedule and require GROQ_LIVE_TESTS=1 plus a GROQ_API_KEY. To run live tests locally: GROQ_LIVE_TESTS=1 composer test.

Requirements

• PHP >= 8.1
• fileinfo extension
• guzzlehttp/guzzle

Contributing

Contributions are welcome! If you find a bug, have a suggestion, or want to add functionality, please open an issue or submit a pull request.

Changelog

See CHANGELOG.md for the full changelog.

About Semantic Versioning

This package follows SemVer conventions. However, breaking changes may be released in minor versions in the following cases:

1. Changes that only affect static types and not runtime behavior.
2. Modifications to internal library components that are technically public but not intended for external use. (Please open a GitHub issue if you depend on these internals).
3. Changes that should not affect most users in practical scenarios.

License

MIT