GroqTextModel: PHP Driver for Groq Chat Completions

GroqTextModel is the low-level driver that executes text generation against Groq’s OpenAI-compatible /chat/completions endpoint. It is instantiated by GroqProvider::textModel() (and by the Groq::model() facade shorthand) and is the object you pass to the Generate fluent builder’s ->model() call. The class resolves capability metadata from a custom ModelRegistry when one is present, falling back to the built-in ModelCatalog loaded from the bundled resources/models.json file. For models that do not natively support the json_schema response format, it transparently rewrites the request body to json_object and injects a system-level JSON instruction, so callers never need to branch on provider limitations themselves.

Class reference

Namespace: AiSdk\Groq\Models
Implements: TextModelInterface
Extends: BaseModel
Package: aisdk/groq

Public methods

`provider()`

Returns the canonical provider name string used throughout the SDK.

Checking the provider name

use AiSdk\Groq;

Groq::create(['apiKey' => 'gsk-...']);

$model = Groq::model('llama-3.3-70b-versatile');

echo $model->provider(); // 'groq'

return

string

Always returns 'groq'.

`modelId()`

Returns the model identifier string that was supplied at construction time.

Reading back the model ID

$model = Groq::model('llama-3.3-70b-versatile');

echo $model->modelId(); // 'llama-3.3-70b-versatile'

return

string

The exact model ID string passed to Groq::model() or GroqProvider::textModel().

`capabilities()`

Returns the full list of capabilities that the model supports or has adapted support for. Resolution order:

A custom ModelRegistry entry registered via Groq::registerModel(), if one exists for this model ID.
The built-in ModelCatalog sourced from resources/models.json.

Listing all capabilities of a model

use AiSdk\Groq;

Groq::create(['apiKey' => 'gsk-...']);

$capabilities = Groq::model('llama-3.3-70b-versatile')->capabilities();
// Returns an array of AiSdk\Capability enum values

return

array<int, Capability>

An array of AiSdk\Capability enum cases representing every capability the model exposes (including adapted ones).

`capability()`

Returns a detailed CapabilitySupport object that describes exactly how a single capability is supported — fully, via an adaptation, or not at all. Resolution order:

Any capability forced via ->assume() or ->allowUnknownCapabilities() on the model handle (inherited from BaseModel).
A custom ModelRegistry entry for this model ID.
The built-in ModelCatalog.
Special fallback: if the capability is TextGeneration and the model is entirely unknown to both the registry and the catalog, returns Supported with source 'unknown-model-fallback'.

capability

Capability

required

The AiSdk\Capability enum case to look up — e.g. Capability::StructuredOutput, Capability::ImageInput, Capability::ToolCalling.

return

CapabilitySupport

A CapabilitySupport value object with the following properties:

Property	Type	Description
`->state`	`CapabilitySupportState`	`Supported`, `Adapted`, or `NotSupported`
`->strategy`	`string`	Human-readable explanation of the adaptation (empty string when not adapted)
`->source`	`string`	Where the support declaration came from (e.g. `'model-catalog'`, `'user-assumed'`, `'unknown-model-fallback'`)

Inspecting structured output support

use AiSdk\Capability;
use AiSdk\CapabilitySupportState;
use AiSdk\Groq;

Groq::create(['apiKey' => 'gsk-...']);

// llama-3.1-8b-instant uses adapted structured output
$support = Groq::model('llama-3.1-8b-instant')->capability(Capability::StructuredOutput);

echo $support->state->name;    // 'Adapted'
echo $support->strategy;       // 'json_schema response format is adapted to json_object ...'

// openai/gpt-oss-20b has native support
$support = Groq::model('openai/gpt-oss-20b')->capability(Capability::StructuredOutput);

echo $support->state->name;    // 'Supported'

->supports(Capability $c): bool is a convenience method inherited from BaseModel that returns true when the capability state is either Supported or Adapted.

`generate()`

Sends a synchronous POST request to /chat/completions and returns a fully-resolved TextModelResponse.

request

TextModelRequest

required

The assembled request object produced by the Generate fluent builder. Contains messages, optional tool definitions, response format, and generation parameters.

return

TextModelResponse

A value object with:

Property	Type	Description
`->text`	`string`	The model’s text reply
`->usage`	`TokenUsage`	`->inputTokens` and `->outputTokens`
`->output`	`mixed`	Decoded JSON when a structured output schema was requested
`->providerMetadata`	`array`	Raw Groq response fields keyed under `'groq'` (e.g. `id`, `model`, `choice_finish_reason`)

Generating text with the Groq provider

use AiSdk\Generate;
use AiSdk\Groq;

Groq::create(['apiKey' => 'gsk-...']);

$result = Generate::text('Explain quantum entanglement in one sentence.')
    ->model(Groq::model('llama-3.3-70b-versatile'))
    ->run();

echo $result->text;
echo $result->usage->inputTokens;
echo $result->providerMetadata['groq']['id'];

`stream()`

Sends a streaming POST request to /chat/completions with stream: true and yields text chunks as a Generator. The ChatStreamParser reads server-sent events and emits each decoded delta string.

request

TextModelRequest

required

Same request object as generate(). The streaming flag is set internally before the request is sent.

return

Generator<string>

Yields string chunks as they arrive from the API. Each yielded value is a decoded content delta from one SSE event.

Streaming a response chunk by chunk

use AiSdk\Generate;
use AiSdk\Groq;

Groq::create(['apiKey' => 'gsk-...']);

$stream = Generate::text('Write a haiku about PHP.')
    ->model(Groq::model('llama-3.3-70b-versatile'))
    ->stream();

foreach ($stream as $chunk) {
    echo $chunk;
    ob_flush();
    flush();
}

Use ->stream() on the Generate builder rather than calling stream() on the model directly. The builder handles chunked HTTP transport setup via the configured Sdk instance.

Structured output adaptation

Several Groq-hosted models do not support the OpenAI json_schema response format natively. GroqTextModel detects this at request time and applies a transparent two-step adaptation so callers can use Schema::object() with any model:

Format rewrite — response_format.type is changed from json_schema to json_object.
Instruction injection — The string "Respond only with a valid JSON object that matches the requested schema." is injected as a system message. If a system message already exists, the instruction is appended to its content with a blank line separator.

The adaptation requires the model to reliably follow system-level JSON instructions. This is generally sufficient for instruction-tuned Llama models, but responses may occasionally be malformed. Consider using a model with native structured_output support (such as openai/gpt-oss-20b) for strict schema adherence in production.

Structured output with automatic json_object adaptation

use AiSdk\Generate;
use AiSdk\Groq;
use AiSdk\Schema;

Groq::create(['apiKey' => 'gsk-...']);

// llama-3.1-8b-instant has Adapted StructuredOutput — the SDK rewrites
// the request body to json_object automatically.
$result = Generate::text('Extract the city and country from: Lahore, Pakistan.')
    ->model(Groq::model('llama-3.1-8b-instant'))
    ->output(Schema::object(
        name: 'address',
        properties: [
            Schema::string(name: 'city')->required(),
            Schema::string(name: 'country')->required(),
        ],
    ))
    ->run();

// $result->output is the decoded PHP array
echo $result->output['city'];    // 'Lahore'
echo $result->output['country']; // 'Pakistan'

The table below summarises which built-in models use each strategy:

Model	StructuredOutput state
`llama-3.1-8b-instant`	`Adapted` (json_object rewrite)
`llama-3.3-70b-versatile`	`NotSupported`
`meta-llama/llama-4-scout*`	`NotSupported`
`meta-llama/llama-4-maverick*`	`NotSupported`
`moonshotai/kimi*`	`Supported`
`openai/gpt-oss-20b`	`Supported`
`openai/gpt-oss-120b`	`Supported`

Working with custom and unknown models

Registering a custom model

Use Groq::registerModel() to declare capabilities for a model not listed in the bundled catalog. The registered definition is consulted before the catalog on every capability lookup.

Registering a custom fine-tuned model

use AiSdk\Capability;
use AiSdk\Groq;
use AiSdk\ModelDefinition;

Groq::create(['apiKey' => 'gsk-...']);

// Verbose form with a ModelDefinition object
Groq::registerModel(new ModelDefinition(
    id: 'my-fine-tuned-llama',
    capabilities: [
        Capability::TextGeneration,
        Capability::Streaming,
        Capability::ToolCalling,
    ],
));

// Terse facade shorthand
Groq::registerModel('my-fine-tuned-llama', capabilities: [
    Capability::TextGeneration,
    Capability::Streaming,
    Capability::ToolCalling,
]);

Assuming capabilities on the fly

For a model handle you do not want to register globally, ->assume() (inherited from BaseModel) injects specific capabilities into the handle without touching the registry.

Assuming capabilities for a single handle

use AiSdk\Capability;
use AiSdk\Groq;

Groq::create(['apiKey' => 'gsk-...']);

$model = Groq::model('my-new-model')->assume([
    Capability::ToolCalling,
    Capability::StructuredOutput,
]);

$model->supports(Capability::ToolCalling);   // true  (source: 'user-assumed')
$model->supports(Capability::ImageInput);    // false

Bypassing all capability checks

->allowUnknownCapabilities() marks the model handle as permissive — every capability lookup returns Supported regardless of what the catalog says.

Allowing all capabilities for experimental use

use AiSdk\Capability;
use AiSdk\Groq;

Groq::create(['apiKey' => 'gsk-...']);

$model = Groq::model('my-new-model')->allowUnknownCapabilities();

$model->supports(Capability::ImageInput);    // true  (source: 'user-allowed-unknown-capabilities')
$model->supports(Capability::StructuredOutput); // true

->allowUnknownCapabilities() disables all SDK-side capability guards. The Groq API will still return errors if the model does not actually support the requested feature.

Unknown model fallback

If a model ID is not found in either the registry or the catalog, capability(Capability::TextGeneration) still returns Supported with source 'unknown-model-fallback'. All other capabilities return NotSupported unless overridden with ->assume() or ->allowUnknownCapabilities().

Unknown models always allow basic text generation

use AiSdk\Capability;
use AiSdk\Groq;

Groq::create(['apiKey' => 'gsk-...']);

$model = Groq::model('totally-unknown-model');

$model->supports(Capability::TextGeneration);            // true
$model->capability(Capability::TextGeneration)->source;  // 'unknown-model-fallback'
$model->supports(Capability::ToolCalling);               // false

Error handling

HTTP status	SDK exception
`429`	`AiSdk\Exceptions\RateLimitException`
`4xx` / `5xx`	`AiSdk\Exceptions\ProviderException`
Capability not declared	`AiSdk\Exceptions\CapabilityNotSupportedException`

Catching a rate limit error

use AiSdk\Exceptions\RateLimitException;
use AiSdk\Generate;
use AiSdk\Groq;

Groq::create(['apiKey' => 'gsk-...']);

try {
    $result = Generate::text('Hello')
        ->model(Groq::model('llama-3.3-70b-versatile'))
        ->run();
} catch (RateLimitException $e) {
    // Back off and retry
}

Facade

Model

Class reference

Public methods

`provider()`

`modelId()`

`capabilities()`

`capability()`

`generate()`

`stream()`

Structured output adaptation

Working with custom and unknown models

Registering a custom model

Assuming capabilities on the fly

Bypassing all capability checks

Unknown model fallback

Error handling

Build docs developers (and LLMs) love

Facade

Model

Documentation Index

​Class reference

​Public methods

​provider()

​modelId()

​capabilities()

​capability()

​generate()

​stream()

​Structured output adaptation

​Working with custom and unknown models

​Registering a custom model

​Assuming capabilities on the fly

​Bypassing all capability checks

​Unknown model fallback

​Error handling

Build docs developers (and LLMs) love

Class reference

Public methods

`provider()`

`modelId()`

`capabilities()`

`capability()`

`generate()`

`stream()`

Structured output adaptation

Working with custom and unknown models

Registering a custom model

Assuming capabilities on the fly

Bypassing all capability checks

Unknown model fallback

Error handling