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 PHP AI SDK lets you request structured JSON responses from Groq models using ->output(Schema::object(...)). Because most Groq-hosted models do not yet expose the json_schema response format natively, the SDK automatically adapts the request: it switches response_format to json_object and injects a system instruction — “Respond only with a valid JSON object that matches the requested schema.” — so you get reliable, schema-shaped output without any extra wiring.

​
How Structured Output Works

1
Define your schema
2
Use Schema::object() to describe the shape you want back. Nest Schema::string(), Schema::integer(), and other scalar helpers inside the properties array, and call ->required() on any fields that must be present.
3
use AiSdk\Schema;

$schema = Schema::object(
    name: 'address',
    properties: [
        Schema::string(name: 'city')->required(),
        Schema::string(name: 'country')->required(),
    ],
);
4
Pass the schema to the generate builder
5
Chain ->output($schema) onto Generate::text() before calling ->run(). The SDK resolves capability support at build time and adapts the request body accordingly.
6
use AiSdk\Generate;
use AiSdk\Groq;
use AiSdk\Schema;

$result = Generate::text()
    ->model(Groq::model('llama-3.1-8b-instant'))
    ->prompt('Extract the city and country from: Lahore, Pakistan.')
    ->output(Schema::object(
        name: 'address',
        properties: [
            Schema::string(name: 'city')->required(),
            Schema::string(name: 'country')->required(),
        ],
    ))
    ->run();
7
Read the parsed result
8
$result->output contains the decoded PHP array — no manual json_decode needed.
9
// ['city' => 'Lahore', 'country' => 'Pakistan']
var_dump($result->output);

​
The Adapted Fallback in Practice

For Llama and other Groq-hosted models that do not support json_schema, the SDK silently rewrites the request body before it hits the wire:
  1. response_format.type is changed from json_schema to json_object.
  2. The system message "Respond only with a valid JSON object that matches the requested schema." is prepended (or appended to an existing system turn).
You do not need to do anything differently — the same ->output() API works for every model. The adaptation happens inside GroqTextModel::buildBody() when the resolved CapabilitySupport->state is Adapted.
The injected instruction is appended to your existing system prompt when one is present, so your own instructions are never overwritten.

​
Checking Capability Support

Use Groq::model('...')->capability(Capability::StructuredOutput) to inspect how a specific model handles structured output before you run a generation.
Inspect structured output capability
use AiSdk\Capability;
use AiSdk\Groq;

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

// AiSdk\CapabilitySupportState::Adapted
echo $support->state->value;

// "json_schema response format is adapted to json_object with an added JSON instruction."
echo $support->strategy;
The CapabilitySupport value object exposes two properties:
PropertyTypeDescription
$stateCapabilitySupportStateSupported, Adapted, or NotSupported
$strategystringHuman-readable explanation of the adaptation, if any

​
Native vs. Adapted Support

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

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

// Adapted: uses json_object + injected instruction
echo $support->state === CapabilitySupportState::Adapted ? 'adapted' : 'other';

​
Models with Native json_schema Support

The following Groq-hosted models receive your schema as a first-class json_schema response format — no adaptation, no injected instruction:
Model IDNotes
openai/gpt-oss-20b131 072-token context
openai/gpt-oss-120b131 072-token context
moonshotai/kimi*Matches all Kimi variant IDs
All other models in the Groq catalog (Llama, etc.) receive the Adapted state.
If you are building a production pipeline that requires strict schema enforcement, prefer openai/gpt-oss-20b, openai/gpt-oss-120b, or a moonshotai/kimi* model to get native json_schema validation rather than the injected-instruction approach.

​
Complete Example

Structured output — full example
use AiSdk\Capability;
use AiSdk\Generate;
use AiSdk\Groq;
use AiSdk\Schema;

// Optionally confirm adaptation strategy before running
$support = Groq::model('llama-3.1-8b-instant')
    ->capability(Capability::StructuredOutput);

echo "Strategy: {$support->strategy}" . PHP_EOL;

// Run the generation
$result = Generate::text()
    ->model(Groq::model('llama-3.1-8b-instant'))
    ->prompt('Extract the city and country from: Lahore, Pakistan.')
    ->output(Schema::object(
        name: 'address',
        properties: [
            Schema::string(name: 'city')->required(),
            Schema::string(name: 'country')->required(),
        ],
    ))
    ->run();

// ['city' => 'Lahore', 'country' => 'Pakistan']
print_r($result->output);
$result->output returns null when the model returns malformed JSON. Always validate the value before passing it further downstream, especially when using the adapted fallback on smaller models.

Build docs developers (and LLMs) love

Get started for freeTalk to us