How to Use OpenRouter with Laravel: Free Models, Fallbacks and Error Handling

'openrouter' => [
    'key'      => env('OPENROUTER_API_KEY'),
    'base_url' => env('OPENROUTER_BASE_URL', 'https://openrouter.ai/api/v1'),
    'model'    => env('OPENROUTER_MODEL', 'openrouter/free'),
    'fallbacks' => array_filter(explode(',', env('OPENROUTER_FALLBACKS', ''))),
    'timeout'  => (int) env('OPENROUTER_TIMEOUT', 60),
    'site_url' => env('APP_URL'),
    'app_name' => env('APP_NAME'),
],

OPENROUTER_API_KEY=sk-or-v1-...
OPENROUTER_MODEL=openrouter/free
OPENROUTER_FALLBACKS=
OPENROUTER_TIMEOUT=60

namespace App\Services;

use App\Exceptions\OpenRouterException;
use Illuminate\Http\Client\PendingRequest;
use Illuminate\Http\Client\Response;
use Illuminate\Support\Facades\Http;

class OpenRouter
{
    public function chat(array $messages, ?string $model = null, array $options = []): array
    {
        $payload = array_merge([
            'model'    => $model ?? config('services.openrouter.model'),
            'messages' => $messages,
        ], $options);

        if ($fallbacks = config('services.openrouter.fallbacks')) {
            $payload['models'] = $fallbacks;
        }

        $response = $this->client()->post('/chat/completions', $payload);

        return $this->parse($response);
    }

    public function ask(string $prompt, ?string $system = null): string
    {
        $messages = array_values(array_filter([
            $system ? ['role' => 'system', 'content' => $system] : null,
            ['role' => 'user', 'content' => $prompt],
        ]));

        return $this->chat($messages)['content'];
    }

    protected function client(): PendingRequest
    {
        return Http::baseUrl(config('services.openrouter.base_url'))
            ->withToken(config('services.openrouter.key'))
            ->withHeaders([
                'HTTP-Referer' => config('services.openrouter.site_url'),
                'X-Title'      => config('services.openrouter.app_name'),
            ])
            ->acceptJson()
            ->timeout(config('services.openrouter.timeout'));
    }

    protected function parse(Response $response): array
    {
        $data = $response->json();

        // Errors can arrive as a non-2xx status OR inside a 200 body
        if ($response->failed() || isset($data['error'])) {
            throw OpenRouterException::fromResponse($response->status(), $data['error'] ?? []);
        }

        return [
            'content' => $data['choices'][0]['message']['content'] ?? '',
            'model'   => $data['model'] ?? null,   // the model that actually answered
            'usage'   => $data['usage'] ?? [],
        ];
    }
}

$summary = app(\App\Services\OpenRouter::class)
    ->ask("Summarise in one sentence:\n\n" . $post->body, 'You are a concise technical editor.');

namespace App\Exceptions;

use RuntimeException;

class OpenRouterException extends RuntimeException
{
    public function __construct(
        string $message,
        public readonly int $status,
        public readonly array $metadata = [],
    ) {
        parent::__construct($message, $status);
    }

    public static function fromResponse(int $status, array $error): self
    {
        $code = (int) ($error['code'] ?? $status);

        return new self($error['message'] ?? "OpenRouter error $code", $code, $error['metadata'] ?? []);
    }

    /** Worth retrying later: rate limits, timeouts, provider outages */
    public function isRetryable(): bool
    {
        return in_array($this->status, [408, 429, 502, 503], true);
    }

    /** Out of credits: retrying will never help */
    public function isBillingProblem(): bool
    {
        return $this->status === 402;
    }
}

OPENROUTER_MODEL=vendor/primary-model:free
OPENROUTER_FALLBACKS=vendor/second-model:free,vendor/paid-model

namespace App\Jobs;

use App\Exceptions\OpenRouterException;
use App\Models\Post;
use App\Services\OpenRouter;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;

class GenerateSummary implements ShouldQueue
{
    use Queueable;

    public int $tries = 4;
    public int $timeout = 120;

    public function __construct(public Post $post) {}

    public function backoff(): array
    {
        return [10, 30, 90];   // seconds between attempts
    }

    public function handle(OpenRouter $openRouter): void
    {
        try {
            $summary = $openRouter->ask("Summarise in two sentences:\n\n" . $this->post->body);
        } catch (OpenRouterException $e) {
            if ($e->isBillingProblem()) {
                $this->fail($e);   // stop now: retries can't fix a 402
                return;
            }

            throw $e;              // 429, 502, 503... retried with backoff
        }

        $this->post->update(['summary' => $summary]);
    }
}

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;

Route::post('/chat/stream', function (Request $request) {
    $upstream = Http::withToken(config('services.openrouter.key'))
        ->withOptions(['stream' => true])
        ->timeout(120)
        ->post(config('services.openrouter.base_url') . '/chat/completions', [
            'model'    => config('services.openrouter.model'),
            'stream'   => true,
            'messages' => [['role' => 'user', 'content' => $request->input('message')]],
        ]);

    return response()->stream(function () use ($upstream) {
        $body = $upstream->toPsrResponse()->getBody();
        $buffer = '';

        while (! $body->eof()) {
            $buffer .= $body->read(1024);

            while (($pos = strpos($buffer, "\n")) !== false) {
                $line = trim(substr($buffer, 0, $pos));
                $buffer = substr($buffer, $pos + 1);

                // Skip keep-alive comments like ": OPENROUTER PROCESSING"
                if ($line === '' || str_starts_with($line, ':')) {
                    continue;
                }

                if ($line === 'data: [DONE]') {
                    return;
                }

                $chunk = json_decode(substr($line, 6), true);

                // Errors mid-stream arrive inside a 200 response
                if (isset($chunk['error'])) {
                    echo "event: error\ndata: " . json_encode($chunk['error']['message']) . "\n\n";
                    flush();
                    return;
                }

                $text = $chunk['choices'][0]['delta']['content'] ?? '';
                if ($text !== '') {
                    echo 'data: ' . json_encode($text) . "\n\n";
                    flush();
                }
            }
        }
    }, 200, [
        'Content-Type'      => 'text/event-stream',
        'Cache-Control'     => 'no-cache',
        'X-Accel-Buffering' => 'no',   // stop Nginx buffering the stream
    ]);
});

composer require moe-mizrak/laravel-openrouter
php artisan vendor:publish --tag=laravel-openrouter

use App\Exceptions\OpenRouterException;
use App\Services\OpenRouter;
use Illuminate\Support\Facades\Http;

it('returns the model answer', function () {
    Http::fake([
        'openrouter.ai/*' => Http::response([
            'model'   => 'vendor/model:free',
            'choices' => [['message' => ['content' => 'Hello from the model']]],
        ]),
    ]);

    expect(app(OpenRouter::class)->ask('Hi'))->toBe('Hello from the model');
});

it('treats 402 as a billing problem', function () {
    Http::fake([
        'openrouter.ai/*' => Http::response(['error' => ['code' => 402, 'message' => 'Insufficient credits']], 402),
    ]);

    $e = null;

    try {
        app(OpenRouter::class)->ask('Hi');
    } catch (OpenRouterException $caught) {
        $e = $caught;
    }

    expect($e)->not->toBeNull()
        ->and($e->isBillingProblem())->toBeTrue()
        ->and($e->isRetryable())->toBeFalse();
});