rodiumai/laravel-sdk

Official PHP / Laravel SDK for the Rodium AI API — unified access to AI models (OpenAI, Anthropic, Google, DeepSeek…) with RODI credit billing and Mobile Money top-ups.

OpenAI-compatible REST API: same endpoints and payloads as documented at rodiumai.io/docs.

Links

Table of contents

• Requirements
• Installation
• Configuration
• Quick start
• Chat completions
• Streaming & real-time chat (SSE)
• Models catalogue
• Embeddings
• Images (POST /v1/images/generations)
• Videos (POST /v1/videos/generations)
• Audio
• Anthropic Messages
• Wallet & pricing
• Error handling
• SDK reference
• Local development
• Migration 0.1.x → 0.2.0
• Testing
• License

Requirements

• PHP 8.1+ with the json extension
• Laravel 10–13 (optional — RodiumAIClient works in plain PHP)
• Rodium AI account + API key (rd_sk_…): dashboard

Installation

composer require rodiumai/laravel-sdk:^0.3

Publish config (optional):

php artisan vendor:publish --tag=rodiumai-config

The ServiceProvider and RodiumAI Facade are auto-discovered.

Configuration

.env:

RODIUMAI_API_KEY=rd_sk_your_secret_key
RODIUMAI_BASE_URL=https://api.rodiumai.io/v1
RODIUMAI_DEFAULT_MODEL=openai/gpt-4o
RODIUMAI_TIMEOUT=30
# RODIUMAI_LOCALE=fr   # optional — SDK error hints (en, fr, es)

Never commit .env or API keys.

Quick start

Laravel (Facade)

use RodiumAI\Facades\RodiumAI;

$response = RodiumAI::model('openai/gpt-4o')
    ->temperature(0.7)
    ->maxTokens(300)
    ->chat('Explain Rodium AI in two sentences.');

echo $response->content;
echo $response->costRodi(); // RODI cost from usage.cost_rodi

Plain PHP

use RodiumAI\RodiumAIClient;

$client = new RodiumAIClient(apiKey: getenv('RODIUMAI_API_KEY'));
$response = $client->chat('Hello!');
echo $response->content;

Chat completions

POST /v1/chat/completions — OpenAI-compatible. All OpenAI fields pass-through (tools, response_format, …).

Parameters

use RodiumAI\Data\ChatMessage;

$messages = [
    ChatMessage::system('You are a Laravel assistant.'),
    ChatMessage::user('What is a Service Provider?'),
];

$response = RodiumAI::model('openai/gpt-4o')
    ->temperature(0.5)
    ->maxTokens(500)
    ->chat($messages, [
        'tools' => [/* OpenAI tool definitions */],
        'response_format' => ['type' => 'json_object'],
    ]);

echo $response->content;
echo $response->costRodi();

Multi-turn conversation

$history = [
    ChatMessage::user('My name is Amina.'),
    ChatMessage::assistant('Nice to meet you, Amina!'),
    ChatMessage::user('What is my name?'),
];
$response = RodiumAI::chat($history);

Multimodal vision

$b64 = base64_encode(file_get_contents('invoice.png'));

$response = RodiumAI::chat([[
    'role' => 'user',
    'content' => [
        ['type' => 'text', 'text' => 'Extract the total amount.'],
        ['type' => 'image_url', 'image_url' => ['url' => "data:image/png;base64,{$b64}"]],
    ],
]], ['model' => 'openai/gpt-4o']);

HTTP(S) image URLs work in chat (not in image/video generation).

Function calling

$response = RodiumAI::chat('Weather in Lomé?', [
    'model' => 'openai/gpt-4o',
    'tools' => [[
        'type' => 'function',
        'function' => [
            'name' => 'get_weather',
            'parameters' => [
                'type' => 'object',
                'properties' => ['city' => ['type' => 'string']],
                'required' => ['city'],
            ],
        ],
    ]],
    'tool_choice' => 'auto',
]);

Smart routing

$response = RodiumAI::model('rodiumai/smart')->chat('Summarize RODI credits.');
$routing = $response->routing();

See Smart routing guide.

Streaming & real-time chat (SSE)

No WebSocket — real-time discussion uses SSE only.

foreach (RodiumAI::model('openai/gpt-4o')->stream('Tell a short story.') as $delta) {
    echo $delta;
}

Real-time chat loop

$history = [];

$ask = function (string $userText) use (&$history) {
    $history[] = ChatMessage::user($userText);
    $parts = '';
    foreach (RodiumAI::stream($history) as $delta) {
        echo $delta; // push to UI
        $parts .= $delta;
    }
    $history[] = ChatMessage::assistant($parts);
    return $parts;
};

$ask('Bonjour!');
$ask('Rappelle-moi ma première question.');

Laravel StreamedResponse

return response()->stream(function () {
    foreach (RodiumAI::stream('Hello') as $delta) {
        echo 'data: ' . json_encode(['delta' => $delta]) . "\n\n";
        ob_flush();
        flush();
    }
    echo "data: [DONE]\n\n";
}, 200, ['Content-Type' => 'text/event-stream', 'Cache-Control' => 'no-cache']);

Models catalogue

$catalogue = RodiumAI::models();
$catalogue->ids();
$catalogue->chatModels();
$catalogue->byProvider('anthropic');
$catalogue->findById('openai/gpt-4o');

$info = RodiumAI::modelInfo('openai/gpt-4o');
$info->contextWindow;
$info->pricing();

$coding = RodiumAI::codingModels();

Each model includes rodiumai_pricing, rodiumai_capabilities (modalities, streaming, tools, vision).

Embeddings

POST /v1/embeddings

$response = RodiumAI::embeddings('Hello world', [
    'model' => 'openai/text-embedding-3-small',
]);

$vector = $response->firstEmbedding();

// Batch
$response = RodiumAI::embeddings(['Sentence A', 'Sentence B'], [
    'model' => 'openai/text-embedding-3-small',
]);

Images (POST /v1/images/generations)

Reference images: base64, data URL, or gs:// — no remote HTTP fetch.

Text-to-image

$image = RodiumAI::images([
    'model' => 'openai/gpt-image-1',
    'prompt' => 'A red fox in the snow',
    'size' => '1024x1024',
    'quality' => 'medium',
]);
$b64 = $image->firstB64();

Image-to-image

$ref = base64_encode(file_get_contents('product.png'));

$image = RodiumAI::images([
    'model' => 'google/gemini-3.1-flash-image',
    'prompt' => 'Soft white studio background',
    'image' => ['b64_json' => $ref, 'mime_type' => 'image/png'],
]);

Inpainting

$image = RodiumAI::images([
    'model' => 'openai/gpt-image-1',
    'prompt' => 'Replace sky with sunset',
    'image' => ['b64_json' => $sourceB64],
    'mask' => ['b64_json' => $maskB64],
]);

Videos (POST /v1/videos/generations)

Always pass 'timeout' => 600 — jobs can take minutes.

Text-to-video

$video = RodiumAI::videos([
    'model' => 'google/veo-3.1-generate-preview',
    'prompt' => 'Ocean waves at golden hour',
    'duration_seconds' => 8,
    'timeout' => 600,
]);

Image-to-video

$frame = base64_encode(file_get_contents('storyboard.png'));

$video = RodiumAI::videos([
    'model' => 'google/veo-3.1-generate-preview',
    'prompt' => 'Subtle pulse animation',
    'duration_seconds' => 8,
    'image' => ['b64_json' => $frame, 'mime_type' => 'image/png'],
    'timeout' => 600,
]);

Interpolation (Veo)

$video = RodiumAI::videos([
    'model' => 'google/veo-3.1-generate-preview',
    'prompt' => 'Smooth morph between frames',
    'image' => ['b64_json' => $startB64],
    'last_frame' => ['b64_json' => $endB64],
    'timeout' => 600,
]);

Audio

Transcriptions — multipart

$transcript = RodiumAI::transcribe('/path/to/audio.mp3', [
    'model' => 'google/gemini-2.5-flash',
    'language' => 'fr',
]);
echo $transcript->text;

Speech — binary response

$audioBytes = RodiumAI::speech([
    'model' => 'openai/tts-1',
    'input' => 'Hello from RodiumAI',
    'voice' => 'nova',
    'response_format' => 'mp3',
]);
file_put_contents('speech.mp3', $audioBytes);

Anthropic Messages

POST /v1/messages

$response = RodiumAI::messages([
    'model' => 'anthropic/claude-sonnet-4-6',
    'max_tokens' => 1024,
    'system' => 'You are concise.',
    'messages' => [
        ['role' => 'user', 'content' => 'Explain RODI credits.'],
    ],
]);

echo $response->content;

Streaming: 'stream' => true — Anthropic SSE events.

Wallet & pricing

$wallet = RodiumAI::wallet();
echo $wallet->balanceRodi;

$pricing = RodiumAI::pricing();
$pricing->findByModel('openai/gpt-4o');

Error handling

See docs/api/errors.

use RodiumAI\Exceptions\InsufficientCreditsException;
use RodiumAI\Exceptions\RateLimitException;
use RodiumAI\Facades\RodiumAI;

try {
    RodiumAI::chat('Test');
} catch (InsufficientCreditsException $e) {
    logger()->warning('Insufficient RODI', ['code' => $e->errorCode()]);
} catch (RateLimitException $e) {
    sleep($e->retryAfter() ?? 30);
}

SDK reference

Fluent builder: model(), temperature(), topP(), maxTokens(), systemPrompt(), language().

DTOs: ChatResponse, ChatMessage, ModelInfo, ModelCollection, EmbeddingResponse, ImageResponse, VideoResponse, TranscriptionResponse, MessageResponse, WalletResponse, PricingCollection.

Technical mapping: docs/api-alignment.md.

Local development

Point the SDK at a local gateway (e.g. Docker Compose on port 8001):

RODIUMAI_BASE_URL=http://localhost:8001/v1
RODIUMAI_API_KEY=rd_sk_dev_...

Migration 0.1.x → 0.2.0

Require ^0.2 in composer.json.

Testing

composer install
composer test                 # PHPUnit (mocked HTTP)
export RODIUMAI_API_KEY="rd_sk_..."
php bin/smoke-test.php        # Live API walkthrough

License

MIT — see LICENSE.