Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/phpaisdk/groq/llms.txt

Use this file to discover all available pages before exploring further.

The aisdk/groq package is the official Groq provider for the PHP AI SDK. It connects to Groq’s OpenAI-compatible API so you can generate text with models like llama-3.3-70b-versatile using the same fluent interface as every other provider in the SDK.

​
Prerequisites

Install the package and export your Groq API key before running any examples.
1

Install the package

Terminal
composer require aisdk/groq
2

Set your API key

.env
GROQ_API_KEY=gsk-...
The provider reads GROQ_API_KEY automatically. No further configuration is required for most projects.

​
Basic Text Generation

Pass a prompt directly to Generate::text() and chain ->model() with a Groq::model() call. Calling ->run() blocks until the full response is returned.
basic.php
use AiSdk\Generate;
use AiSdk\Groq;

$result = Generate::text('Explain closures in PHP.')
    ->model(Groq::model('llama-3.3-70b-versatile'))
    ->run();

echo $result->text;

​
Adding a System Prompt

Chain ->instructions() to set a system-level prompt that shapes the model’s behaviour for the entire conversation, then use ->prompt() for the user turn.
with-instructions.php
use AiSdk\Generate;
use AiSdk\Groq;

$result = Generate::text()
    ->model(Groq::model('llama-3.3-70b-versatile'))
    ->instructions('You are a concise technical writer. Use plain language and short sentences.')
    ->prompt('Explain closures in PHP.')
    ->run();

echo $result->text;
->instructions() maps to the system role in the underlying chat request. It is evaluated before the user turn so the model has full context when it starts generating.

​
The Response Object

->run() returns a TextModelResponse. The three most useful members are text, usage, and providerMetadata.
response-inspection.php
use AiSdk\Generate;
use AiSdk\Groq;

$result = Generate::text('Summarise the history of PHP in two sentences.')
    ->model(Groq::model('llama-3.3-70b-versatile'))
    ->run();

// Generated text
echo $result->text;

// Token counts
echo $result->usage->inputTokens;   // tokens consumed by the prompt
echo $result->usage->outputTokens;  // tokens produced by the model

// Groq-specific metadata
$meta = $result->providerMetadata['groq'];
echo $meta['id'];                   // e.g. "chatcmpl_groq"
echo $meta['model'];                // e.g. "llama-3.3-70b-versatile"
echo $meta['choice_finish_reason']; // e.g. "stop"
FieldTypeDescription
$result->textstringThe model’s reply
$result->usage->inputTokensintPrompt tokens consumed
$result->usage->outputTokensintCompletion tokens produced
$result->providerMetadata['groq']['id']stringUnique completion ID returned by the Groq API
$result->providerMetadata['groq']['model']stringModel ID echoed back by the API
$result->providerMetadata['groq']['choice_finish_reason']stringWhy the model stopped — stop, length, etc.

​
Setting a Default Model

If your application always uses the same model, register it once with Generate::model(). Every subsequent Generate::text() call will use it automatically so you do not need to repeat ->model() at each call site.
bootstrap.php
use AiSdk\Generate;
use AiSdk\Groq;

// Call once — in a service provider, bootstrap file, or container binding.
Generate::model(Groq::model('llama-3.3-70b-versatile'));
anywhere-in-your-app.php
use AiSdk\Generate;

// No ->model() needed — the default is already set.
$result = Generate::text('What is the capital of France?')->run();

echo $result->text; // "The capital of France is Paris."
You can still override the default on a per-call basis by chaining ->model() explicitly. The explicit call takes precedence over the registered default.

​
Provider-Specific Options

The ->providerOptions() escape hatch lets you forward raw request fields directly to the Groq API. This is useful for parameters that are not yet surfaced as first-class SDK options, such as top_k.
provider-options.php
use AiSdk\Generate;
use AiSdk\Groq;

$result = Generate::text('Write a creative opening line for a fantasy novel.')
    ->model(Groq::model('llama-3.3-70b-versatile'))
    ->providerOptions('groq', [
        'raw' => ['top_k' => 40],
    ])
    ->run();

echo $result->text;
Any key–value pairs nested under 'raw' are merged into the JSON body before the HTTP request is sent.
Raw options bypass SDK-level validation. Check the Groq API reference to confirm that the field and value you are passing are valid for the model you have selected.

​
Programmatic API Key Configuration

If you prefer not to rely on environment variables — for example in a multi-tenant application — pass the key directly to Groq::create().
programmatic-config.php
use AiSdk\Groq;

$provider = Groq::create([
    'apiKey'  => 'gsk-...',
    'baseUrl' => 'https://api.groq.com/openai/v1', // optional; this is the default
]);

​
Error Handling

The SDK maps HTTP status codes to typed exceptions. A 429 Too Many Requests response from Groq throws \AiSdk\Exceptions\RateLimitException, which you can catch and handle independently from other errors.
rate-limit-handling.php
use AiSdk\Exceptions\RateLimitException;
use AiSdk\Generate;
use AiSdk\Groq;

try {
    $result = Generate::text('Hello!')
        ->model(Groq::model('llama-3.3-70b-versatile'))
        ->run();

    echo $result->text;
} catch (RateLimitException $e) {
    // Groq returned 429 — back off and retry.
    echo 'Rate limit reached. Please wait before retrying.';
}
Consider implementing exponential back-off when catching RateLimitException in production. Groq’s free tier has per-minute token limits that are easy to hit during development.

​
Available Models

The models below ship with the aisdk/groq package and are ready to use with Groq::model().
Model IDStreamingTool CallingStructured OutputImage Input
llama-3.1-8b-instant✅ Native✅ Native⚡ Adapted❌
llama-3.3-70b-versatile✅ Native✅ Native❌❌
meta-llama/llama-4-scout*✅ Native✅ Native❌✅ Native
meta-llama/llama-4-maverick*✅ Native✅ Native❌✅ Native
moonshotai/kimi*✅ Native✅ Native✅ Native❌
openai/gpt-oss-20b✅ Native✅ Native✅ Native❌
openai/gpt-oss-120b✅ Native✅ Native✅ Native❌
Adapted structured output means the SDK automatically downgrades json_schema to json_object and injects a JSON instruction into the system prompt. The output is still parsed and returned as a structured value — you do not need to handle the downgrade yourself.

Build docs developers (and LLMs) love

Get started for freeTalk to us