Skip to main content

Documentation Index

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

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

The VoyageAI facade is a final static class in the AiSdk namespace that gives you a concise, zero-boilerplate entry point to the VoyageAI provider. Instead of constructing a VoyageAIProvider and VoyageAIOptions by hand, you call VoyageAI::create() once and then use VoyageAI::model() anywhere in your application. The facade stores a single provider instance as a private static property — the singleton — which can be replaced with create() or cleared entirely with reset(). 
use AiSdk\VoyageAI;

VoyageAI::create(['apiKey' => 'pa-...']);

$model = VoyageAI::model('voyage-4-large');

​
Class Signature

namespace AiSdk;

final class VoyageAI
{
    private static ?VoyageAIProvider $default = null;

    public static function create(array $config = []): VoyageAIProvider {}
    public static function default(): VoyageAIProvider {}
    public static function reset(): void {}
    public static function model(string $modelId): Model {}
}

​
Methods

​
VoyageAI::create()

Creates a new VoyageAIProvider from the given configuration array, stores it as the default singleton, and returns it. Calling create() a second time replaces the existing singleton.
​
config
array<string, mixed>
default:"[]"
Configuration array passed directly to VoyageAIOptions::fromArray(). Supports apiKey, baseUrl, headers, and sdk keys. If apiKey is omitted the VOYAGE_API_KEY environment variable is used.
Returns VoyageAIProvider — the newly created and registered provider instance. 
use AiSdk\VoyageAI;

// Minimal — relies on the VOYAGE_API_KEY env var
$provider = VoyageAI::create();

// Explicit API key
$provider = VoyageAI::create(['apiKey' => 'pa-...']);

// Custom base URL and extra headers
$provider = VoyageAI::create([
    'apiKey'  => 'pa-...',
    'baseUrl' => 'https://proxy.example.com/v1',
    'headers' => ['X-Request-ID' => 'abc-123'],
]);
create() unconditionally overwrites the singleton. If you need to preserve an existing provider, read it from VoyageAI::default() before calling create() again.

​
VoyageAI::default()

Returns the current default VoyageAIProvider. If no provider has been created yet, it lazily calls VoyageAI::create() with an empty config — which means the VOYAGE_API_KEY environment variable must be set, or a RuntimeException is thrown. Returns VoyageAIProvider — the singleton provider. 
use AiSdk\VoyageAI;

// Safe if VOYAGE_API_KEY is set in the environment
$provider = VoyageAI::default();

// Or set it up explicitly first
VoyageAI::create(['apiKey' => 'pa-...']);
$provider = VoyageAI::default(); // returns the provider created above
Calling default() without having called create() first, and without a VOYAGE_API_KEY environment variable, will throw an exception. Prefer create() with an explicit key in application bootstrapping code.

​
VoyageAI::model()

Resolves a model through the default provider and returns a Model instance ready to be used with Generate::embedding(). This is the most commonly used method — it delegates to VoyageAI::default()->model($modelId).
​
modelId
string
required
The Voyage AI model identifier, for example 'voyage-4-large', 'voyage-3-lite', or any future opaque model ID string. The SDK does not validate this string against a fixed list; any non-empty string is accepted.
Returns AiSdk\Contracts\Model — a VoyageAIEmbeddingModel instance bound to the given ID. 
use AiSdk\Generate;
use AiSdk\VoyageAI;

VoyageAI::create(['apiKey' => 'pa-...']);

$result = Generate::embedding('The quick brown fox')
    ->model(VoyageAI::model('voyage-4-large'))
    ->run();

​
VoyageAI::reset()

Sets the singleton back to null. The next call to default() or model() after reset() will lazily recreate the provider (or throw if no API key is available). Returns void 
use AiSdk\VoyageAI;

VoyageAI::create(['apiKey' => 'pa-...']);
// ... use the provider ...

VoyageAI::reset(); // singleton is now null
Always call VoyageAI::reset() in your test suite’s afterEach hook to prevent provider state from leaking between tests.

​
Singleton Lifecycle

The diagram below summarises how the singleton is managed across the four methods.

create()

Builds a fresh VoyageAIProvider and stores it as the singleton. Always replaces whatever was there before.

default()

Returns the singleton. If it is null, calls create([]) first (lazy initialisation).

model()

Thin shortcut: calls default() and then delegates to the provider’s model() method.

reset()

Sets the singleton to null. The next call to default() or model() starts fresh.
use AiSdk\VoyageAI;

// 1. Bootstrap once (e.g. in a service provider)
VoyageAI::create(['apiKey' => env('VOYAGE_API_KEY')]);

// 2. Use anywhere — no need to pass the provider around
$modelA = VoyageAI::model('voyage-4-large');
$modelB = VoyageAI::model('voyage-3-lite');

// 3. Override for a specific scope (e.g. a different API key mid-request)
$old = VoyageAI::default();
VoyageAI::create(['apiKey' => 'pa-secondary-...']);
// ... do scoped work ...
// restore not possible without re-creating, so plan ahead
VoyageAI::reset();

Build docs developers (and LLMs) love

Get started for freeTalk to us