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.

Groq regularly launches preview checkpoints and fine-tuned variants before they appear in the SDK’s bundled catalog. Rather than waiting for a package release, aisdk/groq lets you register any model ID at runtime so that the rest of the SDK — capability checks, structured-output adaptation, tool calling — works exactly the same as for a built-in model. This page explains both registration approaches, runtime assumption helpers, and the fallback behaviour for completely unknown models.

​
Registration approaches

There are two ways to register a custom model. The terse facade signature is recommended for quick registration when you only need to declare capabilities. The ModelDefinition object is the right choice when you want to attach full metadata or plan to inspect the definition elsewhere in your application. 
use AiSdk\Capability;
use AiSdk\Groq;

Groq::registerModel('llama-5-70b', capabilities: [
    Capability::TextGeneration,
    Capability::Streaming,
    Capability::ToolCalling,
    Capability::StructuredOutput,
    Capability::TextInput,
]);
After calling registerModel, the model ID is available throughout the SDK just like any built-in model.

​
Using a registered model

1

Register the model

Call Groq::registerModel() once, typically in your application bootstrap or a service provider:
bootstrap.php
use AiSdk\Capability;
use AiSdk\Groq;

Groq::registerModel('llama-5-70b', capabilities: [
    Capability::TextGeneration,
    Capability::Streaming,
    Capability::ToolCalling,
    Capability::StructuredOutput,
    Capability::TextInput,
]);
2

Resolve the model handle

Call Groq::model() with the same ID you registered:
Resolving the handle
use AiSdk\Groq;

$model = Groq::model('llama-5-70b');
3

Verify capabilities (optional)

Inspect the declared capabilities before sending a request:
Capability checks
use AiSdk\Capability;

$model->supports(Capability::TextGeneration);   // true
$model->supports(Capability::ToolCalling);       // true
$model->supports(Capability::StructuredOutput);  // true
$model->supports(Capability::ImageInput);        // false

$model->capability(Capability::TextGeneration)->state->name; // "Supported"
4

Run a generation

Use the model with Generate exactly as you would with any built-in model:
Text generation with a custom model
use AiSdk\Generate;
use AiSdk\Groq;

$result = Generate::text('Hello')
    ->model(Groq::model('llama-5-70b'))
    ->run();

echo $result->text;

​
Capability handling for registered models

When you register a model with an explicit capabilities list, the SDK enforces those declarations strictly. Calling a capability that is not in the list throws a CapabilityNotSupportedException before any HTTP request is made:
Undeclared capability throws an exception
use AiSdk\Capability;
use AiSdk\Content;
use AiSdk\Generate;
use AiSdk\Groq;
use AiSdk\Message;
use AiSdk\ModelDefinition;

Groq::registerModel(new ModelDefinition(
    id: 'custom-groq-model',
    capabilities: [Capability::TextGeneration, Capability::Streaming],
));

// ImageInput was not declared → throws CapabilityNotSupportedException
Generate::text()
    ->messages([
        Message::user([
            Content::text('Describe this.'),
            Content::image('https://example.com/photo.png'),
        ]),
    ])
    ->model(Groq::model('custom-groq-model'))
    ->run();

​
Runtime assumption helpers

If you do not want to register a model globally but still need to use it with specific capabilities, you can annotate the model handle directly.

​
->assume()

assume() tells the SDK to treat listed capabilities as supported on this handle only, without touching the global registry. The capability source is recorded as user-assumed.
Assuming capabilities on a handle
use AiSdk\Capability;
use AiSdk\Groq;

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

$model->supports(Capability::TextGeneration);            // true (unknown-model-fallback)
$model->supports(Capability::ToolCalling);               // true
$model->supports(Capability::StructuredOutput);          // true
$model->supports(Capability::ImageInput);                // false

$model->capability(Capability::ToolCalling)->source;     // "user-assumed"

​
->allowUnknownCapabilities()

allowUnknownCapabilities() lifts all capability restrictions on the handle. Every capability — including ImageInput — is treated as supported, with source user-allowed-unknown-capabilities.
Allowing all capabilities on a handle
use AiSdk\Capability;
use AiSdk\Groq;

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

$model->supports(Capability::ToolCalling);    // true
$model->supports(Capability::StructuredOutput); // true
$model->supports(Capability::ImageInput);       // true

$model->capability(Capability::ImageInput)->source; // "user-allowed-unknown-capabilities"
allowUnknownCapabilities() bypasses all catalog and registry checks. Use it only during local experimentation. In production, prefer an explicit registerModel() call or assume() so that unexpected capability usage is caught early as an exception rather than an API error.

​
Unknown model fallback

If you call Groq::model() with an ID that is neither in the catalog nor in the registry, the SDK does not throw immediately. Instead, Capability::TextGeneration is silently allowed with source unknown-model-fallback, so you can still attempt a basic text request. All other capabilities are reported as not supported:
Unknown model fallback behaviour
use AiSdk\Capability;
use AiSdk\Groq;

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

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

$model->supports(Capability::ToolCalling);                         // false
The fallback only allows TextGeneration. Any other capability — streaming, tool calling, structured output, image input — must be declared explicitly via registerModel() or assume(), or unlocked via allowUnknownCapabilities().

​
Resetting the registry

Groq::reset() tears down the default provider instance, which also clears all models registered at runtime. If your application or test suite calls Groq::reset(), you must call registerModel() again afterwards:
Re-registering after reset
use AiSdk\Capability;
use AiSdk\Groq;

Groq::reset();

// Re-register after reset
Groq::registerModel('llama-5-70b', capabilities: [
    Capability::TextGeneration,
    Capability::Streaming,
    Capability::ToolCalling,
    Capability::StructuredOutput,
    Capability::TextInput,
]);
In test suites, call Groq::reset() in an afterEach hook to prevent registered models leaking between test cases — then re-register only what each test requires.

Build docs developers (and LLMs) love

Get started for freeTalk to us