README

PHP client for the Voyage AI API — text embeddings, multimodal embeddings (text, images, video), and reranking.

Installation

composer require 0xmrmasry/voyage-ai

Configuration

Set your API key via environment variable:

VOYAGE_API_KEY=your-api-key

Or pass it directly:

$voyage = \VoyageAI\Voyage::client('your-api-key');

Usage

Text Embeddings

use VoyageAI\Voyage;
use VoyageAI\Enums\{InputType, OutputDtype};

$voyage = Voyage::client(getenv('VOYAGE_API_KEY'));

$response = $voyage->embeddings()->create(
    input: ['I like cats', 'I also like dogs'],
    model: 'voyage-4-large',
);

foreach ($response->data as $result) {
    echo "Index: {$result->index}, Dims: " . count($result->embedding) . "\n";
}

echo "Tokens used: {$response->usage->totalTokens}\n";

With Options

$response = $voyage->embeddings()->create(
    input: 'Represent this sentence for searching relevant passages',
    model: 'voyage-4-large',
    options: [
        'input_type' => InputType::Query,
        'truncation' => true,
        'output_dimension' => 256,
        'output_dtype' => OutputDtype::Float,
    ],
);

Quantized Embeddings (int8, uint8, binary, ubinary)

$response = $voyage->embeddings()->create(
    input: 'Test for quantization',
    model: 'voyage-4-large',
    options: [
        'output_dtype' => OutputDtype::Int8,
    ],
);
// $response->data[0]->embedding is now array of ints (-128..127)

Reranking

$response = $voyage->reranking()->create(
    query: 'talk about rain',
    documents: [
        'sunny day at the beach',
        'rainy day in the city',
        'snowy mountain peak',
    ],
    model: 'rerank-2.5',
);

// Results sorted by descending relevance
foreach ($response->data as $result) {
    echo "Document {$result->index}: score {$result->relevanceScore}\n";
}

With Options

$response = $voyage->reranking()->create(
    query: 'best fruit',
    documents: ['apple', 'banana', 'car'],
    model: 'rerank-2.5-lite',
    options: [
        'top_k' => 2,
        'return_documents' => true,
        'truncation' => true,
    ],
);

foreach ($response->data as $result) {
    echo "{$result->document}: {$result->relevanceScore}\n";
}

Multimodal Embeddings

use VoyageAI\Resources\{MultimodalInput, TextContent, ImageUrlContent, VideoUrlContent};

$response = $voyage->multimodal()->create(
    inputs: [
        new MultimodalInput([
            new TextContent('This is a banana.'),
            new ImageUrlContent('https://example.com/banana.jpg'),
        ]),
    ],
    model: 'voyage-multimodal-3.5',
);

With Video

use VoyageAI\Resources\{MultimodalInput, TextContent, ImageUrlContent, VideoUrlContent};

$response = $voyage->multimodal()->create(
    inputs: [
        new MultimodalInput([
            new TextContent('A bunny running in a field.'),
            new ImageUrlContent('https://example.com/bunny.jpg'),
            new VideoUrlContent('https://example.com/bunny.mp4'),
        ]),
    ],
    model: 'voyage-multimodal-3.5',
);

Base64 Images and Video

use VoyageAI\Resources\{MultimodalInput, TextContent, ImageBase64Content, VideoBase64Content};

$response = $voyage->multimodal()->create(
    inputs: [
        new MultimodalInput([
            new TextContent('A photo of a cat.'),
            new ImageBase64Content('data:image/jpeg;base64,/9j/4AAQSkZJRg...'),
            new VideoBase64Content('data:video/mp4;base64,AAAAIGZ0eXBpc29t...'),
        ]),
    ],
    model: 'voyage-multimodal-3.5',
    options: [
        'input_type' => InputType::Document,
        'truncation' => true,
    ],
);

Custom Base URL

$voyage = Voyage::client(
    apiKey: 'your-key',
    baseUrl: 'https://your-proxy.example.com/v1',
);

Available Models

Text Embedding Models

Multimodal Embedding Models

Reranking Models

Error Handling

All API errors throw VoyageAI\Exceptions\VoyageException with an $httpStatusCode property:

try {
    $response = $voyage->embeddings()->create('Hello', 'invalid-model');
} catch (\VoyageAI\Exceptions\VoyageException $e) {
    echo "Error ({$e->httpStatusCode}): {$e->getMessage()}\n";
}

Requirements

• PHP 8.1+
• Guzzle 7 (installed automatically via Composer)

License

MIT