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.

VoyageAIOptions is an immutable configuration value-object that carries every setting the VoyageAI provider needs to communicate with the Voyage AI API. Constructing a VoyageAIOptions instance is the only way to supply an API key, a custom base URL, extra HTTP headers, or a test-friendly HTTP client to the SDK. All properties are declared public readonly, so the object is safe to share and cache — changing settings always means creating a new instance.

​
Class Declaration

namespace AiSdk\VoyageAI;

use AiSdk\Support\Sdk;

final class VoyageAIOptions
{
    public const string DEFAULT_BASE_URL = 'https://api.voyageai.com/v1';
    public const string PROVIDER_NAME    = 'voyageai';

    public function __construct(
        public readonly string  $apiKey,
        public readonly string  $baseUrl = self::DEFAULT_BASE_URL,
        public readonly array   $headers = [],
        public readonly ?Sdk    $sdk     = null,
    ) {}

    public static function fromArray(array $config = []): self {}
    public function authHeaders(): array {}
}

​
Constants

​
DEFAULT_BASE_URL
string
'https://api.voyageai.com/v1' — the production Voyage AI REST endpoint. Used as the default value for $baseUrl and as the fallback in fromArray() when neither the baseUrl config key nor the VOYAGE_BASE_URL environment variable is set.
​
PROVIDER_NAME
string
'voyageai' — the canonical string identifier for this provider within the PHP AI SDK. Returned by VoyageAIProvider::name() and used as the key for provider-scoped options in Generate::embedding()->providerOptions('voyageai', [...]).

​
Constructor Parameters

​
apiKey
string
required
Your Voyage AI API key (begins with pa-). This is the only required parameter. It is included in every outbound HTTP request via the Authorization: Bearer {apiKey} header. Never commit this value to source control; use an environment variable instead.
​
baseUrl
string
default:"https://api.voyageai.com/v1"
The root URL for all API requests. Override this when routing through an API gateway, a caching proxy, or a local mock server. Trailing slashes are stripped automatically by fromArray(); when using the constructor directly, pass a clean URL without a trailing slash.
​
headers
array<string, string>
default:"[]"
Arbitrary HTTP headers to merge into every outgoing request alongside the Authorization header. Useful for adding tracing headers (X-Request-ID), custom routing headers required by a proxy, or any other static header your infrastructure needs.
​
sdk
Sdk|null
default:"null"
An optional AiSdk\Support\Sdk instance that wraps a PSR-18 HTTP client and a PSR-17 HTTP factory. When null (the default), the provider uses the SDK’s auto-discovered HTTP client. Pass an Sdk instance backed by a fake client to intercept HTTP calls in tests without making real network requests.

​
fromArray() Static Factory

public static function fromArray(array $config = []): self
The recommended way to construct VoyageAIOptions. The factory method handles environment-variable fallbacks and URL normalisation so you don’t have to.
​
config
array<string, mixed>
default:"[]"
An associative array with any of the keys: apiKey, baseUrl, headers, sdk. All keys are optional — the factory reads environment variables when keys are absent.
Resolution rules:
Config keyEnv variable fallbackHard default
apiKeyVOYAGE_API_KEY(throws if missing)
baseUrlVOYAGE_BASE_URLDEFAULT_BASE_URL
headers—[]
sdk—null
If neither config['apiKey'] nor the VOYAGE_API_KEY environment variable is set, fromArray() throws a RuntimeException. Set the environment variable or pass the key explicitly.
The baseUrl value — whether from the config array or the environment variable — has its trailing slash stripped before being stored, so joining it with a path such as /embeddings always produces a well-formed URL. 
use AiSdk\VoyageAI\VoyageAIOptions;

// Relies entirely on environment variables
$opts = VoyageAIOptions::fromArray();

// Explicit key, everything else from env / defaults
$opts = VoyageAIOptions::fromArray(['apiKey' => 'pa-...']);

// Full explicit configuration
$opts = VoyageAIOptions::fromArray([
    'apiKey'  => 'pa-...',
    'baseUrl' => 'https://proxy.example.com/v1/',  // trailing slash is stripped
    'headers' => ['X-Org-Id' => 'my-org'],
]);

echo $opts->baseUrl; // 'https://proxy.example.com/v1'

​
authHeaders() Method

public function authHeaders(): array
Returns the complete set of HTTP headers that should be sent with every API request. The result is a merge of the built-in Authorization header and any custom headers supplied at construction time. 
$opts = VoyageAIOptions::fromArray([
    'apiKey'  => 'pa-abc123',
    'headers' => ['X-Request-ID' => 'req-456'],
]);

$opts->authHeaders();
// [
//     'Authorization' => 'Bearer pa-abc123',
//     'X-Request-ID'  => 'req-456',
// ]
If a key in the custom headers array conflicts with 'Authorization', it will overwrite the auto-generated bearer token. Avoid using 'Authorization' as a custom header key.

​
Full Configuration Example

use AiSdk\VoyageAI\VoyageAIOptions;
use AiSdk\VoyageAI\VoyageAIProvider;

$options = VoyageAIOptions::fromArray([
    'apiKey'  => $_ENV['VOYAGE_API_KEY'],
    'baseUrl' => 'https://api.voyageai.com/v1',
    'headers' => [
        'X-Request-ID' => uniqid('req-', true),
    ],
]);

$provider = new VoyageAIProvider($options);
$model    = $provider->model('voyage-4-large');

Build docs developers (and LLMs) love

Get started for freeTalk to us