Groq PHP

https://github.com/lucianotonet/groq-php
Admin
A high-performance PHP client and comprehensive SDK that simplifies interaction with the GroqCloud...
Tokens:84,017
Snippets:578
Trust Score:9.5
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install example dependencies with Composer

Source: https://github.com/lucianotonet/groq-php/blob/main/README.md

Changes into the examples directory and installs the required PHP dependencies via Composer. Must be run after copying the .env file.

```bash
cd examples
composer install
```

--------------------------------

### Start the PHP built-in server for examples

Source: https://github.com/lucianotonet/groq-php/blob/main/README.md

Starts a local PHP development server on 127.0.0.1:8000 to serve the example scripts. After running this, access the examples at http://127.0.0.1:8000 in a browser.

```bash
php -S 127.0.0.1:8000
```

--------------------------------

### Copy .env file to examples folder

Source: https://github.com/lucianotonet/groq-php/blob/main/README.md

Copies the project's .env file into the examples directory so the example scripts can access environment variables. Run this from the project root before setting up the examples.

```bash
cp .env examples/.env
```

--------------------------------

### setOptions usage example

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/groq.md

Example call to setOptions with a custom baseUrl and timeout.

```php
$groq->setOptions([
    'baseUrl' => 'https://proxy.example.com/openai/v1',
    'timeout' => 30000,
]);
```

--------------------------------

### Install groq-php via Composer

Source: https://github.com/lucianotonet/groq-php/blob/main/README.md

Run this command to install the groq-php package using Composer.

```bash
composer require lucianotonet/groq-php
```

--------------------------------

### Batch usage example with retrieve and getSummary

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/batches.md

Example of retrieving a batch and checking completion. Uses isCompleted() and getSummary() to print progress details. The summary includes request_counts with completed and total values.

```php
$batch = $groq->batches()->retrieve('batch_abc123');

if ($batch->isCompleted()) {
    $summary = $batch->getSummary();
    printf(
        'Batch %s finished: %d/%d requests, %.2f%% progress',
        $summary['id'],
        $summary['request_counts']['completed'],
        $summary['request_counts']['total'],
        $summary['progress']
    );
}
```

--------------------------------

### Example JSONL File for Batch Processing

Source: https://github.com/lucianotonet/groq-php/blob/main/README.md

A JSONL file example with four batch requests: two chat completions and two audio transcriptions/translations. Each line must be a valid JSON object with custom_id, method, url, and body fields. The file must be up to 100MB and use JSONL format.

```jsonl
{"custom_id": "chat-request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "openai/gpt-oss-20b", "messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What is quantum computing?"}]}}
{"custom_id": "audio-request-1", "method": "POST", "url": "/v1/audio/transcriptions", "body": {"model": "whisper-large-v3", "language": "en", "url": "https://github.com/voxserv/audio_quality_testing_samples/raw/refs/heads/master/testaudio/8000/test01_20s.wav", "response_format": "verbose_json", "timestamp_granularities": ["segment"]}}
{"custom_id": "chat-request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "openai/gpt-oss-120b", "messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Explain machine learning in simple terms."}]}}
{"custom_id":"audio-request-2","method":"POST","url":"/v1/audio/translations","body":{"model":"whisper-large-v3","language":"en","url":"https://console.groq.com/audio/batch/sample-zh.wav","response_format":"verbose_json","timestamp_granularities":["segment"]}}
```

--------------------------------

### Example — create and poll batch

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/batches.md

Creates a batch, polls until processing completes, then outputs progress and error count.

```php
$batch = $groq->batches()->create([
    'input_file_id'     => 'file_abc123',
    'endpoint'          => '/v1/chat/completions',
    'completion_window' => '24h',
    'metadata'          => ['description' => 'Customer queries'],
    'config'            => ['temperature' => 0.5],
]);

while ($batch->isProcessing()) {
    sleep(10);
    $batch = $groq->batches()->retrieve($batch['id']);
}

echo $batch->getSummary()['progress'].'% completed, '.$batch->getErrorCount().' errors';
```

--------------------------------

### .env.example environment variables

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/configuration.md

Example environment file for configuring the Groq PHP client. GROQ_API_KEY is required; GROQ_API_BASE is optional and commented out; GROQ_LIVE_TESTS controls whether the test suite runs against the real API (1) or offline mocks (0). The library does not load .env files itself.

```plaintext
GROQ_API_KEY=your_api_key_here
# GROQ_API_BASE=https://api.groq.com/openai/v1
GROQ_LIVE_TESTS=0
```

--------------------------------

### Example — error handling for batch cancel

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/batches.md

Cancels a batch and handles permissions_error and rate_limit_error exceptions.

```php
use LucianoTonet\GroqPHP\GroqException;

try {
    $batch = $groq->batches()->cancel('batch_xyz');
    echo $batch['status']; // "cancelling"
} catch (GroqException $e) {
    if ($e->getType() === 'permissions_error') {
        echo 'Batch processing requires a plan upgrade.';
    } elseif ($e->getType() === 'rate_limit_error') {
        echo 'Retry later.';
    } else {
        echo $e->getMessage();
    }
}
```

--------------------------------

### File usage example

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/files.md

Retrieves a file, checks if ready, then prints formatted size, extension, and creation date. Outputs the raw data array with toArray().

```php
$file = $groq->files()->retrieve('file_abc123');

if ($file->isReady()) {
    echo $file->getFormattedSize();   // "12.34 KB"
    echo $file->getExtension();       // "jsonl"
    echo $file->getCreatedAt()->format('Y-m-d H:i:s');
}

print_r($file->toArray());
```

--------------------------------

### Example: list all models

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/models.md

Fetches the model list and prints each model ID. The response is an array with a 'data' key containing model objects.

```php
$models = $groq->models()->list();
foreach ($models['data'] as $model) {
    echo $model['id'].PHP_EOL;
}
```

--------------------------------

### Retrieve a single model by ID with $groq->models()->retrieve()

Source: https://github.com/lucianotonet/groq-php/blob/main/README.md

Fetches a specific model using its ID. The example retrieves 'openai/gpt-oss-20b' and echoes its id.

```php
$model = $groq->models()->retrieve('openai/gpt-oss-20b');
echo $model['id'];
// Output: openai/gpt-oss-20b
```

--------------------------------

### URL Image with Options and Error Handling

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/vision.md

Example of analyzing a URL image with custom options and catching GroqException for size limit, file not found, or API errors.

```php
use LucianoTonet\GroqPHP\GroqException;

try {
    $response = $groq->vision()->analyze(
        'https://example.com/large-image.jpg',
        'What objects are visible?',
        ['temperature' => 0.7, 'max_completion_tokens' => 200]
    );
    echo $response['choices'][0]['message']['content'];
} catch (GroqException $e) {
    // ImageSizeLimitExceededException (400), FileNotFoundException (404), or API errors
    echo $e->getType().': '.$e->getMessage();
}
```

--------------------------------

### Speech create example

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/audio.md

Builds a speech request with model, input, voice, sampleRate, and speed, then outputs the WAV audio stream. Sets the Content-Type header to audio/wav before echoing the stream.

```php
$audioStream = $groq->audio()->speech()
    ->model('canopylabs/orpheus-v1-english')
    ->input('Hello from Groq PHP!')
    ->voice('troy')
    ->sampleRate(24000)
    ->speed(1.1)
    ->create();

header('Content-Type: audio/wav');
echo $audioStream;
```

--------------------------------

### Pre-screen user input with openai/gpt-oss-safeguard-20b

Source: https://github.com/lucianotonet/groq-php/blob/main/README.md

Creates a Groq client and sends a user message to the safeguard model `openai/gpt-oss-safeguard-20b` via the standard Chat Completions API. If the response content starts with 'unsafe', the request is blocked; otherwise the real model can be used. This model is recommended for custom Trust & Safety workflows and returns a structured JSON decision.

```php
use LucianoTonet\GroqPHP\Groq;

$groq = new Groq(getenv('GROQ_API_KEY'));

$screen = $groq->chat()->completions()->create([
    'model' => 'openai/gpt-oss-safeguard-20b',
    'messages' => [
        ['role' => 'user', 'content' => $userMessage],
    ],
]);

if (str_starts_with($screen['choices'][0]['message']['content'], 'unsafe')) {
    echo "Request blocked by content moderation.";
} else {
    // proceed with the real model
}
```

--------------------------------

### Create chat completion with prompt caching and inspect cached tokens

Source: https://github.com/lucianotonet/groq-php/blob/main/README.md

Uses the Groq PHP client to create a chat completion with a static system prompt as a cached prefix and a dynamic user question at the end. Cached tokens are reported under `usage.prompt_tokens_details.cached_tokens` when a cache hit occurs; the example prints the cached input token count.

```php
$response = $groq->chat()->completions()->create([
    'model' => 'openai/gpt-oss-120b',
    'messages' => [
        ['role' => 'system', 'content' => $longStaticSystemPrompt], // cached prefix
        ['role' => 'user', 'content' => $userQuestion],             // dynamic, at the end
    ],
]);

// Inspect cached tokens (populated when a cache hit occurs):
$cached = $response['usage']['prompt_tokens_details']['cached_tokens'] ?? 0;
echo "Cached input tokens: " . $cached;
```

--------------------------------

### Tool Calling with getNbaScore Function

Source: https://github.com/lucianotonet/groq-php/blob/main/README.md

Shows how to let the model call a PHP function by defining a tool, sending a user message, and handling the tool call response. The model 'openai/gpt-oss-120b' supports tool calling. The first response includes a tool_calls array; after calling the function and appending the tool message, a second completion returns the final content. The example includes simulated JSON output and a final echoed response.

```php
<?php

// Example function (simulated)
function getNbaScore($teamName) {
    // ... (simulated logic to return score) ...
    return json_encode(['team' => $teamName, 'score' => 100]); // Example
}

$messages = [
    ['role' => 'system', 'content' => "You must call the 'getNbaScore' function to answer questions about NBA game scores."],
    ['role' => 'user', 'content' => 'What is the Lakers score?']
];

$tools = [
    [
        'type' => 'function',
        'function' => [
            'name' => 'getNbaScore',
            'description' => 'Get the score for an NBA game',
            'parameters' => [
                'type' => 'object',
                'properties' => [
                    'team_name' => ['type' => 'string', 'description' => 'NBA team name'],
                ],
                'required' => ['team_name'],
            ],
        ],
    ]
];

$response = $groq->chat()->completions()->create([
        'model' => 'openai/gpt-oss-120b', // Model that supports tool calling
    'messages' => $messages,
    'tool_choice' => 'auto',
    'tools' => $tools
]);

if (isset($response['choices'][0]['message']['tool_calls'])) {
    // ... (process tool call, call function, and send response) ...
    $tool_call          = $response['choices'][0]['message']['tool_calls'][0];
    $function_args      = json_decode($tool_call['function']['arguments'], true);
    $function_response  = getNbaScore($function_args['team_name']);
            
    $messages[] = [
        'tool_call_id'  => $tool_call['id'],
        'role'          => 'tool',
        'name'          => 'getNbaScore',
        'content'       => $function_response,
    ];

    // Second call to the model with tool response:
    $response = $groq->chat()->completions()->create([
        'model' => 'openai/gpt-oss-120b',
        'messages' => $messages
    ]);
    echo $response['choices'][0]['message']['content'];
} else {
    // Direct response, no tool_calls
    echo $response['choices'][0]['message']['content'];
}

// When the model requests a tool, the first response includes:
// {
//   "choices": [
//     {
//       "message": {
//         "role": "assistant",
//         "tool_calls": [
//           { "id": "call_abc", "type": "function", "function": { "name": "getNbaScore", "arguments": "{\"team_name\":\"Lakers\"}" } }
//         ]
//       }
//     }
//   ]
// }
// After calling getNbaScore() and sending the result back, the final echoed
// content is, e.g.: "The Lakers currently have 100 points."
```

--------------------------------

### Catch GroqException and inspect error details

Source: https://github.com/lucianotonet/groq-php/blob/main/README.md

Wrap API calls in a try/catch block to handle GroqException. The exception provides getMessage(), getType(), getCode(), and getFailedGeneration() for failed_generation errors. The displayed output shows a 401 authentication_error example.

```php
try {
    // ... API call ...
} catch (\LucianoTonet\GroqPHP\GroqException $e) {
    echo "Groq Error: " . $e->getMessage() . "\n";
    echo "Type: " . $e->getType() . "\n";
    echo "Code: " . $e->getCode() . "\n";
    if ($e->getFailedGeneration()) {
        echo "Invalid JSON: " . $e->getFailedGeneration();
    }
}

// Output:
// Groq Error: Incorrect API key provided
// Type: authentication_error
// Code: 401
```

--------------------------------

### Text-to-Speech with Groq PHP (save and stream)

Source: https://github.com/lucianotonet/groq-php/blob/main/README.md

Converts text to speech using the canopylabs/orpheus-v1-english model. Method 1 saves the audio to a file with ->save('output.wav') and prints 'Audio file saved successfully!'. Method 2 uses ->create() to get a stream and outputs raw WAV bytes with Content-Type: audio/wav. Orpheus models accept a maximum of 200 characters for input and only support 'wav' output format.

```php
use LucianoTonet\GroqPHP\Groq;

$groq = new Groq(getenv('GROQ_API_KEY'));

try {
    // Method 1: Save to file
    $result = $groq->audio()->speech()
        ->model('canopylabs/orpheus-v1-english')  // 'canopylabs/orpheus-v1-english' for English, 'canopylabs/orpheus-arabic-saudi' for Arabic
        ->input('Hello, this text will be converted to speech')
        ->voice('troy')  // Voice identifier
        ->responseFormat('wav')  // Output format
        ->save('output.wav');
    
    if ($result) {
        echo "Audio file saved successfully!";
    }
    
    // Method 2: Get as stream
    $audioStream = $groq->audio()->speech()
        ->model('canopylabs/orpheus-v1-english')
        ->input('This is another example text')
        ->voice('troy')
        ->create();
    
    // Use the stream (e.g., send to browser)
    header('Content-Type: audio/wav');
    header('Content-Disposition: inline; filename="speech.wav"');
    echo $audioStream;
    
} catch (\LucianoTonet\GroqPHP\GroqException $e) {
    echo "Error: " . $e->getMessage();
}

// Method 1 prints: "Audio file saved successfully!"
// Method 2 streams raw WAV audio bytes (Content-Type: audio/wav).
```

--------------------------------

### RAG with citations example using BuiltInTools

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/built-in-tools.md

Creates a chat completion with two documents (one text, one file) and enables citation_options. The model must support documents; otherwise the API rejects with 'not supported with this model'. Prints any citations from the response.

```php
use LucianoTonet\GroqPHP\BuiltInTools;

$response = $groq->chat()->completions()->create([
    'model'            => 'llama-3.3-70b-versatile', // a model that supports documents
    'messages'         => [['role' => 'user', 'content' => 'Summarize the provided document']],
    'documents'        => [
        BuiltInTools::document('Groq is a fast inference platform.', 'doc-1'),
        BuiltInTools::documentFromFile('file_abc123', 'doc-2'),
    ],
    'citation_options' => 'enabled',
]);

print_r($response['citations'] ?? []);
```

--------------------------------

### Provide documents with citation_options enabled

Source: https://github.com/lucianotonet/groq-php/blob/main/README.md

Pass context documents via the 'documents' parameter and enable 'citation_options' to get citations in the response. BuiltInTools::document() creates a text document; documentFromFile() uses a previously uploaded file. Note: only models that support documents accept these parameters; legacy RAG models were retired on 2026-08-16 for free/developer tiers.

```php
use LucianoTonet\GroqPHP\BuiltInTools;

$response = $groq->chat()->completions()->create([
    'model' => 'llama-3.3-70b-versatile', // a model that supports documents
    'messages' => [
        ['role' => 'user', 'content' => 'Summarize the provided document'],
    ],
    'documents' => [
        BuiltInTools::document('Groq is a fast inference platform...', 'doc-1'),
    ],
    'citation_options' => 'enabled',
]);

echo $response['choices'][0]['message']['content'];
// Expected response structure (formatted):
// {
//   "choices": [
//     { "message": { "role": "assistant", "content": "Groq is a fast AI inference platform focused on low-latency LLM serving." }, "finish_reason": "stop" }
//   ],
//   "citations": [ { "document": "doc-1", "url": "...", "title": "..." } ]  // present when citation_options=enabled
// }
```

--------------------------------

### Speech save example with error handling

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/audio.md

Saves speech to output.wav and handles GroqException. Throws RuntimeException if the write fails. Catches GroqException and prints the error type and message.

```php
use LucianoTonet\GroqPHP\GroqException;

try {
    $ok = $groq->audio()->speech()
        ->input('This text will be spoken aloud.')
        ->voice('troy')
        ->save('output.wav');

    if (! $ok) {
        throw new RuntimeException('Failed writing output.wav');
    }
} catch (GroqException $e) {
    // validation_error, or request-level failures
    echo $e->getType().': '.$e->getMessage();
}
```

--------------------------------

### setDefaultModel Example

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/vision.md

Example of setting a custom default model for vision analysis.

```php
$groq->vision()->setDefaultModel('openai/gpt-oss-120b');
```

--------------------------------

### files method signature

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/groq.md

Returns a new FileManager instance.

```php
public function files(): FileManager
```

--------------------------------

### files

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/groq.md

Returns a new FileManager instance.

```APIDOC
## files

### Description
Returns a new FileManager instance.

### Method
files

### Signature
public function files(): FileManager
```

--------------------------------

### Full flow: models, chat, files, and batches

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/groq.md

Shows the complete Groq PHP client workflow: listing models, creating a chat completion, uploading a file, and creating a batch. Requires the GROQ_API_KEY environment variable.

```php
use LucianoTonet\GroqPHP\Groq;

$groq = new Groq(getenv('GROQ_API_KEY'));

$models  = $groq->models()->list();                       // GET /models
$answer  = $groq->chat()->completions()->create([         // POST /chat/completions
    'model'    => 'openai/gpt-oss-20b',
    'messages' => [['role' => 'user', 'content' => 'Hi']],
]);
$file    = $groq->files()->upload('requests.jsonl', 'batch');
$batch   = $groq->batches()->create([
    'input_file_id'    => $file['id'],
    'endpoint'         => '/v1/chat/completions',
    'completion_window'=> '24h',
]);
```

--------------------------------

### BuiltInTools::compound() usage example

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/built-in-tools.md

Builds a compound_custom payload with web search and code interpreter enabled, then passes it to Completions::create() along with search_settings. The model 'compound-beta' is used in this example.

```php
$compound = BuiltInTools::compound(
    [BuiltInTools::WEB_SEARCH, BuiltInTools::CODE_INTERPRETER],
    'latest'
);

$response = $groq->chat()->completions()->create([
    'model'           => 'compound-beta',
    'messages'        => [['role' => 'user', 'content' => 'Summarize AI news']],
    'compound_custom' => $compound,
    'search_settings' => ['exclude_domains' => ['wikipedia.org']],
]);
```

--------------------------------

### reasoning

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/groq.md

Returns a new Reasoning instance.

```APIDOC
## reasoning

### Description
Returns a new Reasoning instance.

### Method
reasoning

### Signature
public function reasoning(): Reasoning
```

--------------------------------

### BatchManager retrieve method

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/batches.md

Retrieves a batch by its ID using a GET request to /batches/{batchId}.

```php
public function retrieve(string $batchId): Batch
```

--------------------------------

### reasoning method signature

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/groq.md

Returns a new Reasoning instance.

```php
public function reasoning(): Reasoning
```

--------------------------------

### Basic initialization with Groq constructor

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/groq.md

Shows three ways to instantiate the Groq client: passing an API key, relying on the environment variable, or specifying a custom base URL. The constructor resolves the key from argument, $_ENV, or getenv, and throws GroqException if none is found.

```php
use LucianoTonet\GroqPHP\Groq;

$groq = new Groq(getenv('GROQ_API_KEY'));

// Equivalent: picks up the key from the environment automatically
$groq = new Groq();

// With a custom base URL
$groq = new Groq(getenv('GROQ_API_KEY'), [
    'baseUrl' => 'https://api.groq.com/openai/v1',
]);
```

--------------------------------

### Audio Transcription and Translation with Groq PHP

Source: https://github.com/lucianotonet/groq-php/blob/main/README.md

Transcribes audio using the whisper-large-v3 model. The transcription example uses response_format 'verbose_json' and an optional language and prompt. The translation example translates audio to English using ->translations()->create(). Response formats 'vtt' and 'srt' are not supported. The 'language' parameter is an ISO 639-1 code for the source language.

```php
use LucianoTonet\GroqPHP\Groq;

$groq = new Groq(getenv('GROQ_API_KEY'));

try {
    $transcription = $groq->audio()->transcriptions()->create([
        'file' => 'audio.mp3', /* Your audio file */
        'model' => 'whisper-large-v3',
        'response_format' => 'verbose_json', /* Or 'text', 'json' */
        'language' => 'en', /* ISO 639-1 code (optional but recommended) */
        'prompt' => 'Audio transcription...' /* (optional) */
    ]);

    echo json_encode($transcription, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
    // Output (formatted JSON):
    // {
    //   "text": "Hello, how can I help you today",
    //   "language": "english",
    //   "duration": 3.2,
    //   "segments": [ { "start": 0.0, "end": 2.1, "text": "Hello, how can I help you today" } ]
    // }
} catch (\LucianoTonet\GroqPHP\GroqException $e) {
    echo "Error: " . $e->getMessage();
}

// (Similar to transcription, but uses ->translations()->create() and always translates to English)

// Target language for translation is always English
$translation = $groq->audio()->translations()->create([
    'file' => 'audio_in_spanish.mp3',
    'model' => 'whisper-large-v3'
]);
```

--------------------------------

### vision

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/groq.md

Returns a new Vision instance.

```APIDOC
## vision

### Description
Returns a new Vision instance.

### Method
vision

### Signature
public function vision(): Vision
```

--------------------------------

### audio method signature

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/groq.md

Returns a new Audio instance bound to this Groq client.

```php
public function audio(): Audio
```

--------------------------------

### retrieve

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/batches.md

Retrieves a batch job by its ID using a GET request to the /batches/{batchId} endpoint. Returns a Batch object.

```APIDOC
## GET {baseUrl}/batches/{batchId}

### Description
Retrieves a batch job by its ID.

### Method
GET

### Endpoint
{baseUrl}/batches/{batchId}

### Parameters
#### Path Parameters
- **batchId** (string) - Required - The ID of the batch to retrieve.

### Response
#### Success Response (200)
- **Batch** (object) - A Batch object built from the decoded JSON response.

#### Response Example
{
  "id": "batch_xyz",
  "status": "completed"
}
```

--------------------------------

### speech

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/groq.md

Returns a new Speech instance. This is a direct shortcut; an identical method name exists on Audio.

```APIDOC
## speech

### Description
Returns a new Speech instance. This is a direct shortcut; an identical method name exists on Audio.

### Method
speech

### Signature
public function speech(): Speech
```

--------------------------------

### Basic Vision Call

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/vision.md

Example of analyzing a local image with a prompt and printing the assistant's response.

```php
$response = $groq->vision()->analyze('photos/sunset.jpg', 'Describe the colors in this image.');
echo $response['choices'][0]['message']['content'];
```

--------------------------------

### GET /files/{fileId}

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/endpoints.md

Retrieves a specific file by its ID. Returns a File value object.

```APIDOC
## GET /files/{fileId}

### Description
Retrieves a specific file by its ID. Returns a File value object.

### Method
GET

### Endpoint
{baseUrl}/files/{fileId}

### Parameters
#### Path Parameters
- **fileId** (string) - Required - The ID of the file to retrieve.

### Response
#### Success Response (200)
Returns a File value object with fields: `id`, `object`, `bytes`, `filename`, `purpose`, `created_at`, `status`.

```

--------------------------------

### list

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/batches.md

Lists batch jobs with optional filtering and pagination using a GET request to the /batches endpoint. Returns an array of Batch objects.

```APIDOC
## GET {baseUrl}/batches

### Description
Lists batch jobs with optional filtering and pagination.

### Method
GET

### Endpoint
{baseUrl}/batches

### Parameters
#### Query Parameters
- **limit** (int) - Optional - Max items (default: 20)
- **after** (string|null) - Optional - Pagination cursor (default: null)
- **order** (string) - Optional - Sort order (default: 'desc')
- **status** (string|null) - Optional - Filter by batch status (default: null)
- **created_after** (int|null) - Optional - Unix timestamp filter (default: null)
- **created_before** (int|null) - Optional - Unix timestamp filter (default: null)

### Response
#### Success Response (200)
- **data** (array) - Array of Batch objects.

#### Response Example
{
  "data": [
    {"id": "batch_xyz", "status": "completed"}
  ]
}
```

--------------------------------

### vision method signature

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/groq.md

Returns a new Vision instance.

```php
public function vision(): Vision
```

--------------------------------

### audio

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/groq.md

Returns a new Audio instance bound to this Groq client.

```APIDOC
## audio

### Description
Returns a new Audio instance bound to this Groq client.

### Method
audio

### Signature
public function audio(): Audio
```

--------------------------------

### responses method signature

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/groq.md

Returns a new Responses instance (Responses API, beta).

```php
public function responses(): Responses
```

--------------------------------

### GET /batches/{batchId}

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/endpoints.md

Retrieves a specific batch processing job by its ID. Returns a Batch value object.

```APIDOC
## GET /batches/{batchId}

### Description
Retrieves a specific batch processing job by its ID. Returns a Batch value object.

### Method
GET

### Endpoint
{baseUrl}/batches/{batchId}

### Parameters
#### Path Parameters
- **batchId** (string) - Required - The ID of the batch to retrieve.

### Response
#### Success Response (200)
Returns a Batch value object with fields: `id`, `object`, `endpoint`, `input_file_id`, `completion_window`, `status`, `request_counts` (`total`/`completed`/`failed`), `created_at`, `completed_at`, `expires_at`.

```

--------------------------------

### responses

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/groq.md

Returns a new Responses instance for the Responses API (beta).

```APIDOC
## responses

### Description
Returns a new Responses instance for the Responses API (beta).

### Method
responses

### Signature
public function responses(): Responses
```

--------------------------------

### GET /models/{modelId}

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/endpoints.md

Retrieves details for a specific model by its ID. The model ID is appended verbatim to the path.

```APIDOC
## GET /models/{modelId}

### Description
Retrieves details for a specific model by its ID.

### Method
GET

### Endpoint
`{baseUrl}/models/{modelId}`

### Parameters
#### Path Parameters
- **modelId** (string) - Required - The unique identifier of the model.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200)
- **id** (string) - Model identifier.
- **object** (string) - Type of object (e.g., "model").
- **owned_by** (string) - Owner of the model.

#### Response Example
```json
{
  "id": "model-id",
  "object": "model",
  "owned_by": "organization"
}
```

### Errors
Any failure results in a `GroqException` of type `RetrieveModelException` (404 for unknown IDs).
```

--------------------------------

### Analyze with reasoning (raw format)

Source: https://github.com/lucianotonet/groq-php/blob/main/README.md

Uses the reasoning()->analyze() method to perform step-by-step reasoning. The 'reasoning_format' option is set to 'raw' (the default), which includes reasoning steps within  thinking tags in the content. Requires a GROQ_API_KEY environment variable. The response structure is shown in the comment.

```php
use LucianoTonet\GroqPHP\Groq;

$groq = new Groq(getenv('GROQ_API_KEY'));

try {
    $response = $groq->reasoning()->analyze(
        'Explain the process of photosynthesis.',
        [
            'model' => 'qwen/qwen3.6-27b',
            'reasoning_format' => 'raw', // 'raw' (default), 'parsed', 'hidden'
            'temperature' => 0.6,
            'max_completion_tokens' => 10240
        ]
    );

    echo $response['choices'][0]['message']['content'];
    // Expected response structure (formatted):
    // {
    //   "choices": [
    //     { "message": { "role": "assistant", "content": " thinkingPhotosynthesis converts light... response\nPhotosynthesis is the process by which..." }, "finish_reason": "stop" }
    //   ],
    //   "usage": { "prompt_tokens": ..., "completion_tokens": ..., "total_tokens": ... }
    // }
} catch (\LucianoTonet\GroqPHP\GroqException $e) {
    echo "Error: " . $e->getMessage();
}
```

--------------------------------

### Example: retrieve a model with error handling

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/models.md

Retrieves a model by ID and handles GroqException. The error type is 'RetrieveModelException' for failures like 404.

```php
use LucianoTonet\GroqPHP\GroqException;

try {
    $model = $groq->models()->retrieve('openai/gpt-oss-20b');
    echo $model['id']; // openai/gpt-oss-20b
} catch (GroqException $e) {
    // e.g. 404 when the model id does not exist;
    // note the error TYPE is 'RetrieveModelException', not 'Not Found Error'
    echo $e->getType().': '.$e->getMessage();
}
```

--------------------------------

### apiKey

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/groq.md

Returns the resolved API key.

```APIDOC
## apiKey

### Description
Returns the resolved API key.

### Method
apiKey

### Signature
public function apiKey(): string
```

--------------------------------

### batches method signature

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/groq.md

Returns a new BatchManager instance.

```php
public function batches(): BatchManager
```

--------------------------------

### Accessing response headers and consuming chunks

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/stream.md

Shows how to get a specific header (e.g., content-type) from the stream and then consume the chunks afterwards.

```php
$stream = $groq->chat()->completions()->create([...'stream' => true]);

echo $stream->getHeader('content-type');   // e.g. "text/event-stream"

// Consume chunks afterwards:
foreach ($stream->chunks() as $chunk) { /* ... */ }
```

--------------------------------

### new Groq(?string $apiKey = null, array $options = [])

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/groq.md

Creates a new Groq client instance. Resolves the API key from the argument or environment variables, and optionally accepts custom options like a base URL.

```APIDOC
## Constructor: new Groq(?string $apiKey = null, array $options = [])

### Description
Creates a new Groq client instance. Resolves the API key from the argument or environment variables, and optionally accepts custom options like a base URL.

### Parameters
- **$apiKey** (?string) - Optional - API key; if null, resolved from `$_ENV['GROQ_API_KEY']`, then `getenv('GROQ_API_KEY')`.
- **$options** (array) - Optional - Options; `baseUrl` overrides `$_ENV['GROQ_API_BASE']`, then `getenv('GROQ_API_BASE')`.

### Throws
- **GroqException** (type `authentication_error`, code 400) - If no API key can be resolved.

### Example
```php
use LucianoTonet\GroqPHP\Groq;

$groq = new Groq(getenv('GROQ_API_KEY'));

// Equivalent: picks up the key from the environment automatically
$groq = new Groq();

// With a custom base URL
$groq = new Groq(getenv('GROQ_API_KEY'), [
    'baseUrl' => 'https://api.groq.com/openai/v1',
]);
```

### Error Handling Example
```php
use LucianoTonet\GroqPHP\Groq;
use LucianoTonet\GroqPHP\GroqException;

try {
    $groq = new Groq(); // no key in env
} catch (GroqException $e) {
    echo $e->getMessage(); // "The API key is not set. Please provide an API key..."
    echo $e->getType();    // "authentication_error"
    exit(1);
}
```
```

--------------------------------

### GET /models

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/endpoints.md

Lists all available models from the GroqCloud API. This endpoint requires only an Authorization header and returns an array of model objects.

```APIDOC
## GET /models

### Description
Lists all available models from the GroqCloud API.

### Method
GET

### Endpoint
`{baseUrl}/models`

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200)
- **data** (array) - List of model objects.
  - **id** (string) - Model identifier.
  - **object** (string) - Always "model".
  - **owned_by** (string) - Owner of the model.

#### Response Example
```json
{
  "data": [
    {
      "id": "model-id",
      "object": "model",
      "owned_by": "organization"
    }
  ]
}
```

### Errors
Any failure results in a `GroqException` of type `ListModelsException`.
```

--------------------------------

### Basic reasoning call

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/reasoning.md

Example of a basic call to analyze with parsed reasoning format. The response contains reasoning in $response['choices'][0]['message']['reasoning'].

```php
$response = $groq->reasoning()->analyze('Explain the process of photosynthesis.', [
    'model'            => 'qwen/qwen3.6-27b',
    'reasoning_format' => 'parsed',
    'temperature'      => 0.6,
    'max_completion_tokens' => 10240,
]);

// parsed → reasoning in $response['choices'][0]['message']['reasoning']
echo $response['choices'][0]['message']['content'];
```

--------------------------------

### Configure .env file with GROQ_API_KEY and optional base URL

Source: https://github.com/lucianotonet/groq-php/blob/main/README.md

Define the API key and optionally override the default API base URL in a .env file.

```bash
GROQ_API_KEY=your_key_here
GROQ_API_BASE=https://api.groq.com/openai/v1  # (Optional, if different from default)
```

--------------------------------

### list()

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/models.md

Retrieves the list of available models from the Groq API. Sends a GET request to {baseUrl}/models with an Authorization header and returns the decoded JSON response.

```APIDOC
## GET /models

### Description
Retrieves the list of available models from the Groq API.

### Method
GET

### Endpoint
{baseUrl}/models

### Parameters
None

### Request Example
No request body required.

### Response
#### Success Response (200)
- **data** (array) - List of model objects, each containing:
  - **id** (string) - Model identifier
  - **object** (string) - Always 'model'
  - **owned_by** (string) - Owner of the model

#### Response Example
{
  "data": [
    {
      "id": "openai/gpt-oss-20b",
      "object": "model",
      "owned_by": "OpenAI"
    }
  ]
}

### Errors
- **GroqException** (type `ListModelsException`) - Thrown on any failure, with message prefix `Error fetching the list of models:`
```

--------------------------------

### batches

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/groq.md

Returns a new BatchManager instance.

```APIDOC
## batches

### Description
Returns a new BatchManager instance.

### Method
batches

### Signature
public function batches(): BatchManager
```

--------------------------------

### GET /batches

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/endpoints.md

Lists batch processing jobs. Supports query parameters for filtering and pagination. Returns a list of Batch value objects.

```APIDOC
## GET /batches

### Description
Lists batch processing jobs. Supports query parameters for filtering and pagination. Returns a list of Batch value objects.

### Method
GET

### Endpoint
{baseUrl}/batches

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of batches to return. Default is 20.
- **after** (string) - Optional - Pagination cursor for results after this ID.
- **order** (string) - Optional - Sort order. Default is `desc`.
- **status** (string) - Optional - Filter batches by status.
- **created_after** (string) - Optional - Filter batches created after this timestamp.
- **created_before** (string) - Optional - Filter batches created before this timestamp.

### Response
#### Success Response (200)
Returns a list of Batch value objects with fields: `id`, `object`, `endpoint`, `input_file_id`, `completion_window`, `status`, `request_counts` (`total`/`completed`/`failed`), `created_at`, `completed_at`, `expires_at`.

```

--------------------------------

### Create a Responses API request and output text

Source: https://github.com/lucianotonet/groq-php/blob/main/README.md

Uses the Groq Responses API (beta) with a single 'input' field. Requires a GROQ_API_KEY environment variable. Prints the assistant's text output via Responses::outputText().

```php
use LucianoTonet\GroqPHP\Groq;
use LucianoTonet\GroqPHP\Responses;

$groq = new Groq(getenv('GROQ_API_KEY'));

$response = $groq->responses()->create([
    'model' => 'openai/gpt-oss-120b',
    'input' => 'Tell me a fun fact about the moon in one sentence.',
]);

echo Responses::outputText($response);
// Hello from the Responses API.
```

--------------------------------

### GET /files

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/endpoints.md

Lists files from the Groq API. Supports query parameters for filtering and pagination. Returns a list of File value objects.

```APIDOC
## GET /files

### Description
Lists files from the Groq API. Supports query parameters for filtering and pagination. Returns a list of File value objects.

### Method
GET

### Endpoint
{baseUrl}/files

### Parameters
#### Query Parameters
- **purpose** (string) - Optional - Filter files by purpose.
- **limit** (integer) - Optional - Maximum number of files to return. Default is 20.
- **after** (string) - Optional - Pagination cursor for results after this ID.
- **order** (string) - Optional - Sort order. Default is `desc`.
- **created_after** (string) - Optional - Filter files created after this timestamp.
- **created_before** (string) - Optional - Filter files created before this timestamp.

### Response
#### Success Response (200)
Returns a list of File value objects with fields: `id`, `object`, `bytes`, `filename`, `purpose`, `created_at`, `status`.

```

--------------------------------

### BuiltInTools::compound

Source: https://github.com/lucianotonet/groq-php/blob/main/README.md

Builds the `compound_custom` payload for Groq's Compound systems, enabling server-side tools like web search and code execution without local function-calling setup.

```APIDOC
## BuiltInTools::compound

### Description
Builds the `compound_custom` payload for Groq's Compound systems, enabling server-side tools like web search and code execution without local function-calling setup.

### Parameters
- `tools` (array) - Required - Array of built-in tool constants (e.g., `BuiltInTools::WEB_SEARCH`, `BuiltInTools::CODE_INTERPRETER`)

### Example
```php
use LucianoTonet\GroqPHP\Groq;
use LucianoTonet\GroqPHP\BuiltInTools;

$groq = new Groq(getenv('GROQ_API_KEY'));

$response = $groq->chat()->completions()->create([
    'model' => 'compound-beta',
    'messages' => [
        ['role' => 'user', 'content' => 'What happened in AI last week?'],
    ],
    'compound_custom' => BuiltInTools::compound([
        BuiltInTools::WEB_SEARCH,
        BuiltInTools::CODE_INTERPRETER,
    ]),
    'search_settings' => ['exclude_domains' => ['wikipedia.org']],
]);

echo $response['choices'][0]['message']['content'];
```
```

--------------------------------

### speech method signature

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/groq.md

Returns a new Speech instance. Note: identical method name exists on Audio; this is a direct shortcut.

```php
public function speech(): Speech
```

--------------------------------

### Catch native InvalidArgumentException for client-side validation

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/errors.md

Client-side validation errors are thrown as native \InvalidArgumentException, not GroqException. Example shows catching a missing file error for audio transcription.

```php
// Client-side validation errors thrown as native \InvalidArgumentException:
try {
    $groq->audio()->transcriptions()->create(['file' => 'missing.mp3']);
} catch (\InvalidArgumentException $e) {
    // "The specified file does not exist."
}
```

--------------------------------

### apiKey method signature

Source: https://github.com/lucianotonet/groq-php/blob/main/_autodocs/api-reference/groq.md

Returns the resolved API key.

```php
public function apiKey(): string
```
Tokens:
Raw