Custom providers

Custom providers (BYOK — Bring Your Own Key) let you connect to an OpenAI-compatible API endpoint with your own API key. Local providers such as Ollama are also supported.

ProviderConfig

The ProviderConfig class has the following properties.

Property	Type	Description
`baseUrl`	`string`	Required. The API endpoint URL.
`type`	`string\|null`	Provider type. `openai` (default), `azure`, or `anthropic`.
`wireApi`	`string\|null`	API format (openai/azure only). `completions` (default) or `responses`.
`apiKey`	`string\|null`	API key. Not required for local providers such as Ollama.
`bearerToken`	`string\|null`	Bearer Token authentication. Takes precedence over `apiKey`.
`bearerTokenProvider`	`callable\|null`	Callback that returns a bearer token for each provider request. Not serialized.
`azure`	`array\|null`	Azure-specific options, such as `['apiVersion' => '2024-10-21']`.

Basic usage

When using a custom provider, the model parameter is required.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ProviderConfig;
use Revolution\Copilot\Types\SessionConfig;

$response = Copilot::run(
    prompt: 'Hello!',
    config: new SessionConfig(
        model: 'gpt-4', // Required when using a custom provider
        provider: new ProviderConfig(
            baseUrl: 'https://my-api.example.com/v1',
            apiKey: config('services.openai.key'),
        ),
    ),
);

You can also specify it as an array.

$response = Copilot::run(
    prompt: 'Hello!',
    config: [
        'model' => 'gpt-4',
        'provider' => [
            'baseUrl' => 'https://my-api.example.com/v1',
            'apiKey' => config('services.openai.key'),
        ],
    ],
);

Ollama (local provider)

Local providers like Ollama don’t need an apiKey.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ProviderConfig;
use Revolution\Copilot\Types\SessionConfig;

$response = Copilot::run(
    prompt: 'Hello!',
    config: new SessionConfig(
        model: 'deepseek-coder-v2:16b',
        provider: new ProviderConfig(
            type: 'openai',
            baseUrl: 'http://localhost:11434/v1',
        ),
    ),
);

Azure OpenAI

For Azure OpenAI, keep the following in mind.

Set type to azure (not openai).
Set baseUrl to the host only (do not include paths like /openai/v1).

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ProviderConfig;
use Revolution\Copilot\Types\SessionConfig;

$response = Copilot::run(
    prompt: 'Hello!',
    config: new SessionConfig(
        model: 'gpt-4',
        provider: new ProviderConfig(
            type: 'azure', // Always use 'azure' for Azure endpoints
            baseUrl: 'https://my-resource.openai.azure.com', // Host only
            apiKey: config('services.azure.openai_key'),
            azure: [
                'apiVersion' => '2024-10-21',
            ],
        ),
    ),
);

Azure Managed Identity

Use bearerTokenProvider when your provider uses short-lived tokens, such as Azure Managed Identity. The runtime calls the callback on every provider request. The callback receives an array containing providerName and sessionId, and must return the bearer token as a string. The following example calls a token service in your application.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ProviderConfig;
use Revolution\Copilot\Types\SessionConfig;

$response = Copilot::run(
    prompt: 'Hello!',
    config: new SessionConfig(
        model: 'gpt-4',
        provider: new ProviderConfig(
            type: 'azure',
            baseUrl: 'https://my-resource.openai.azure.com',
            azure: ['apiVersion' => '2024-10-21'],
            bearerTokenProvider: fn (array $args): string => app(AzureManagedIdentityTokenProvider::class)->getToken(),
        ),
    ),
);

Handle token acquisition, caching, and refresh inside your callback.

Important notes

The model parameter is required when using a custom provider. Without it, the call errors out.

Always use type: 'azure' for Azure endpoints (*.openai.azure.com).
Specify baseUrl as the host only. The SDK builds the path automatically.

The onListModels handler

When using a custom provider in BYOK mode, you can configure client->listModels() to invoke a custom handler instead of the CLI server. Configure it with the listModelsUsing() method. Since the client is prone to being initialized before listModels() is called, always set listModelsUsing() before listModels().

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ModelInfo;

$models = Copilot::client()->listModelsUsing(function (): array {
    // Return the models available on the custom provider
    return [
        ['id' => 'my-model-1', 'name' => 'My Model 1', 'version' => '1.0'],
        ['id' => 'my-model-2', 'name' => 'My Model 2', 'version' => '2.0'],
    ];
})->listModels();

Passing null clears the handler and restores the default CLI server behavior.

// Clear the handler and revert to default behavior (asking the CLI server)
$models = Copilot::client()->listModelsUsing(null)->listModels();

When listModelsUsing() is configured, listModels() does not need to connect to the CLI server and does not use a cache either.

For the latest updates, see the GitHub repository.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter Kits

Feeds and RSS

Middleware

Custom providers