Laravel OpenRouter

https://github.com/moe-mizrak/laravel-openrouter
Admin
A Laravel package that simplifies integration with OpenRouter, providing a unified interface for...
Tokens:75,024
Snippets:424
Trust Score:7.7
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install dependencies with Composer

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/CONTRIBUTING.md

Installs the project dependencies using Composer. Run this after cloning the repository to set up the development environment.

```bash
composer install
```

--------------------------------

### Facade usage example

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/openrouter-request.md

Example of using the facade statically. It creates a ChatData instance and calls chatRequest, limitRequest, costRequest, chatStreamRequest, and filterStreamingResponse, with inline comments showing the return types.

```php
use MoeMizrak\Laravelopenrouter\Facades\LaravelOpenRouter;
use MoeMizrak\Laravelopenrouter\DTO\ChatData;
use MoeMizrak\Laravelopenrouter\DTO\MessageData;
use MoeMizrak\Laravelopenrouter\Types\RoleType;

$chatData = new ChatData(
    messages: [new MessageData(role: RoleType::USER, content: 'Hello!')],
    model: 'mistralai/mistral-7b-instruct:free',
);

$response = LaravelOpenRouter::chatRequest($chatData);           // ErrorData|ResponseData
$limit = LaravelOpenRouter::limitRequest();                       // LimitResponseData
$cost = LaravelOpenRouter::costRequest($response->id ?? '');      // CostResponseData
$promise = LaravelOpenRouter::chatStreamRequest($chatData);       // PromiseInterface
$parsed = LaravelOpenRouter::filterStreamingResponse($rawChunk);  // ResponseData[]
```

--------------------------------

### PHP: Make GET request to auth/key

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/endpoints.md

Shows how to construct the request path and send a GET request to the auth/key endpoint using the HTTP client. The response is later processed by OpenRouterHelper::formLimitResponse().

```php
// The path for the rate limit or credits left request.
$limitPath = 'auth/key';

$response = app(ClientInterface::class)->request('GET', $limitPath);
```

--------------------------------

### Example — manual construction for testing

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/usage-data.md

Shows how to manually construct a UsageData instance with nested PromptTokensDetailsData and CompletionTokensDetailsData for testing. Then converts it to an array with toArray().

```php
use MoeMizrak\Laravelopenrouter\DTO\CompletionTokensDetailsData;
use MoeMizrak\Laravelopenrouter\DTO\PromptTokensDetailsData;
use MoeMizrak\Laravelopenrouter\DTO\UsageData;

$usage = new UsageData(
    prompt_tokens: 23,
    completion_tokens: 100,
    total_tokens: 123,
    cost: 0.00000114,
    prompt_tokens_details: new PromptTokensDetailsData(
        cached_tokens: 10,
        cache_write_tokens: 15,
    ),
    completion_tokens_details: new CompletionTokensDetailsData(
        reasoning_tokens: 30,
        accepted_prediction_tokens: 90,
    ),
);

$array = $usage->toArray();
```

--------------------------------

### Usage example for formLimitResponse (PHP)

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/openrouter-helper.md

Shows how to call formLimitResponse with a raw response and output the free tier status and remaining limit.

```php
use MoeMizrak\Laravelopenrouter\Helpers\OpenRouterHelper;

$limit = (new OpenRouterHelper())->formLimitResponse($rawResponse);

echo 'Free tier: ' . var_export($limit->is_free_tier, true) . PHP_EOL;
echo 'Remaining: ' . ($limit->limit_remaining ?? 'unlimited');
```

--------------------------------

### Basic streaming example using chatStreamRequest

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/openrouter-request.md

Example usage of chatStreamRequest. It creates a ChatData with a user message and model, waits for the promise to get a stream, then reads chunks until EOF. The stream can be forwarded or parsed with filterStreamingResponse().

```php
use MoeMizrak\Laravelopenrouter\OpenRouterRequest;
use MoeMizrak\Laravelopenrouter\DTO\ChatData;
use MoeMizrak\Laravelopenrouter\DTO\MessageData;
use MoeMizrak\Laravelopenrouter\Types\RoleType;

$promise = app(OpenRouterRequest::class)->chatStreamRequest(
    new ChatData(
        messages: [new MessageData(role: RoleType::USER, content: 'Count to ten.')],
        model: 'deepseek/deepseek-chat-v3.1',
        max_tokens: 1000,
    )
);

$stream = $promise->wait(); // GuzzleHttp\Psr7\Stream

while (! $stream->eof()) {
    $chunk = $stream->read(1024);
    // forward $chunk to the client, or parse it with filterStreamingResponse()
}
```

--------------------------------

### Example — guarding requests by remaining credits

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/limit-response-data.md

Shows how to abort with HTTP 402 when remaining credits are below 0.01, treating null as unlimited. Then proceeds with a chat request.

```php
use MoeMizrak\Laravelopenrouter\Facades\LaravelOpenRouter;

$limit = LaravelOpenRouter::limitRequest();

// limit_remaining is null when the key has no credit limit — treat as unlimited
if ($limit->limit_remaining !== null && $limit->limit_remaining < 0.01) {
    abort(402, 'Out of OpenRouter credits.');
}

$response = LaravelOpenRouter::chatRequest($chatData);
```

--------------------------------

### UsageData usage example

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/usage-data.md

Example of reading usage data from a chat response using the LaravelOpenRouter facade.

```APIDOC
## UsageData usage example

### Description
Example of reading usage data from a chat response using the LaravelOpenRouter facade.

### Example
```php
use MoeMizrak\Laravelopenrouter\Facades\LaravelOpenRouter;

$response = LaravelOpenRouter::chatRequest($chatData);

$usage = $response->usage; // null unless the API returned usage

if ($usage !== null) {
    echo "prompt: {$usage->prompt_tokens}, completion: {$usage->completion_tokens}, total: {$usage->total_tokens}" . PHP_EOL;
    echo "cost: $" . number_format($usage->cost ?? 0, 8) . PHP_EOL;
    echo "cached tokens: " . ($usage->prompt_tokens_details?->cached_tokens ?? 0) . PHP_EOL;
    echo "reasoning tokens: " . ($usage->completion_tokens_details?->reasoning_tokens ?? 0) . PHP_EOL;
}
```
```

--------------------------------

### Usage example for formCostsResponse (PHP)

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/openrouter-helper.md

Shows how to instantiate a GuzzleHttp client, fetch a generation cost from OpenRouter, pass the raw response to formCostsResponse, and output the total_cost.

```php
use GuzzleHttp\Client;
use MoeMizrak\Laravelopenrouter\Helpers\OpenRouterHelper;

$http = new Client(['base_uri' => 'https://openrouter.ai/api/v1/']);
$raw = $http->get('generation?id=gen-xyz', [
    'headers' => ['Authorization' => 'Bearer ' . $apiKey],
]);

$cost = (new OpenRouterHelper())->formCostsResponse($raw);
echo $cost->total_cost;
```

--------------------------------

### Web search plugin example

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/tool-plugin-dtos.md

Example of using PluginData with id 'web' for a web search. Sets max_results to 5, engine to 'undefined', and web_search_options with medium search context. The response annotations contain url_citation entries.

```php
use MoeMizrak\Laravelopenrouter\DTO\ChatData;
use MoeMizrak\Laravelopenrouter\DTO\MessageData;
use MoeMizrak\Laravelopenrouter\DTO\PluginData;
use MoeMizrak\Laravelopenrouter\DTO\WebSearchOptionsData;
use MoeMizrak\Laravelopenrouter\Types\RoleType;
use MoeMizrak\Laravelopenrouter\Types\SearchContextSizeType;

$chatData = new ChatData(
    messages: [new MessageData(role: RoleType::USER, content: 'Latest AI developments?')],
    model: 'openai/gpt-4o', // or 'openai/gpt-4o:online' which is equivalent to this plugin set
    plugins: [
        new PluginData(
            id: 'web',
            max_results: 5,
            engine: 'undefined', // "native" | "exa" | "undefined"
        ),
    ],
    web_search_options: new WebSearchOptionsData(
        search_context_size: SearchContextSizeType::MEDIUM,
    ),
);

$response = LaravelOpenRouter::chatRequest($chatData);
$annotations = Arr::get($response->choices[0], 'message.annotations', []); // url_citation entries
```

--------------------------------

### Example — public PDF with file-parser plugin

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/content-dtos.md

Shows how to create a FileContentData instance with a public PDF URL and optionally attach the file-parser plugin with a PDF engine.

```php
use MoeMizrak\Laravelopenrouter\DTO\FileContentData;
use MoeMizrak\Laravelopenrouter\DTO\FileUrlData;
use MoeMizrak\Laravelopenrouter\DTO\PluginData;

$fileContent = new FileContentData(
    file: new FileUrlData(
        file_data: 'https://example.com/report.pdf',
        filename: 'quarterly-report.pdf',
    ),
);

// Optionally attach the file-parser plugin:
$plugins = [
    new PluginData(
        id: 'file-parser',
        pdf: ['engine' => 'pdf-text'], // pdf-text | mistral-ocr | native
    ),
];
```

--------------------------------

### limitRequest usage example

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/openrouter-request.md

Example of retrieving the rate limit and remaining credits for the configured API key. The response includes usage, limit_remaining, and rate_limit fields; null-coalescing is used to display 'n/a' when values are missing.

```php
use MoeMizrak\Laravelopenrouter\OpenRouterRequest;

$limit = app(OpenRouterRequest::class)->limitRequest();

echo 'Credits used: ' . ($limit->usage ?? 'n/a');
echo 'Credits remaining: ' . ($limit->limit_remaining ?? 'n/a');
echo 'Rate limit: ' . ($limit->rate_limit?->requests ?? 'n/a')
    . ' per ' . ($limit->rate_limit?->interval ?? 'n/a');
```

--------------------------------

### PHP: Use LaravelOpenRouter facade to get limit

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/endpoints.md

Example of using the LaravelOpenRouter facade to retrieve the rate limit and credits left. The limit_remaining property may be null, in which case 'unlimited' is echoed.

```php
use MoeMizrak\Laravelopenrouter\Facades\LaravelOpenRouter;

$limit = LaravelOpenRouter::limitRequest();
echo 'Credits remaining: ' . ($limit->limit_remaining ?? 'unlimited');
```

--------------------------------

### Install laravel-openrouter via Composer

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/README.md

Install the package via Composer. Requires PHP 8.2 or higher for v2.x.x, or PHP 8.1 for v1.0.9.

```bash
composer require moe-mizrak/laravel-openrouter
```

--------------------------------

### Using OpenRouterHelper::formChatResponse()

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/openrouter-helper.md

Example of instantiating OpenRouterHelper directly and calling formChatResponse() with a decoded JSON array. The resulting ResponseData exposes id and usage cost via array access on choices.

```php
use MoeMizrak\Laravelopenrouter\Helpers\OpenRouterHelper;

$decoded = json_decode($rawJson, true);
$responseData = (new OpenRouterHelper())->formChatResponse($decoded);

echo $responseData->id; // e.g. "gen-..."
echo $responseData->usage?->cost;
```

--------------------------------

### Build cost request path and send GET request

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/endpoints.md

Constructs the cost path with the generation ID and sends a GET request using the ClientInterface. Used internally by OpenRouterRequest::costRequest().

```php
// The path for the cost and stats request. e.g. generation?id=$GENERATION_ID
$costPath = 'generation?id=' . $generationId;

$response = app(ClientInterface::class)->request('GET', $costPath);
```

--------------------------------

### costRequest usage example

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/openrouter-request.md

Example of retrieving the cost of a generation by its ID. The generation ID is taken from ResponseData::$id of a previous chatRequest; it may be null for some free models, so the code checks before calling costRequest.

```php
use MoeMizrak\Laravelopenrouter\OpenRouterRequest;

$request = app(OpenRouterRequest::class);

$response = $request->chatRequest($chatData);
$generationId = $response->id; // may be null for some free models

if ($generationId) {
    $cost = $request->costRequest($generationId);
    echo 'Total cost: $' . number_format($cost->total_cost, 8);
}
```

--------------------------------

### Full-featured ChatData request example

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/chatdata.md

Constructs a ChatData instance with messages, model, response_format, max_tokens, temperature, reasoning, plugins, web_search_options, route, models, and provider, then converts it to an array for use as a JSON payload.

```php
use MoeMizrak\Laravelopenrouter\DTO\ChatData;
use MoeMizrak\Laravelopenrouter\DTO\MessageData;
use MoeMizrak\Laravelopenrouter\DTO\PluginData;
use MoeMizrak\Laravelopenrouter\DTO\ProviderPreferencesData;
use MoeMizrak\Laravelopenrouter\DTO\ReasoningData;
use MoeMizrak\Laravelopenrouter\DTO\ResponseFormatData;
use MoeMizrak\Laravelopenrouter\DTO\TextContentData;
use MoeMizrak\Laravelopenrouter\DTO\WebSearchOptionsData;
use MoeMizrak\Laravelopenrouter\Types\EffortType;
use MoeMizrak\Laravelopenrouter\Types\RoleType;
use MoeMizrak\Laravelopenrouter\Types\RouteType;
use MoeMizrak\Laravelopenrouter\Types\SearchContextSizeType;

$chatData = new ChatData(
    messages: [
        new MessageData(
            role: RoleType::USER,
            content: [
                new TextContentData(text: 'Summarize this document.'),
            ],
        ),
    ],
    model: 'openai/gpt-4o',
    response_format: new ResponseFormatData(type: 'json_object'),
    max_tokens: 1024,
    temperature: 0.7,
    reasoning: new ReasoningData(effort: EffortType::HIGH),
    plugins: [new PluginData(id: 'web', max_results: 5)],
    web_search_options: new WebSearchOptionsData(search_context_size: SearchContextSizeType::MEDIUM),
    route: RouteType::FALLBACK,
    models: ['openai/gpt-4o-mini'],
    provider: new ProviderPreferencesData(only: ['openai']),
);

$body = $chatData->convertToArray(); // ready to be used as the JSON payload
```

--------------------------------

### Example — image input using ImageContentPartData

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/content-dtos.md

Shows how to create a ChatData object with a user message containing an image content part. The image URL and detail are provided via ImageUrlData, and the model is set to 'openai/gpt-4o'.

```php
use MoeMizrak\Laravelopenrouter\DTO\ChatData;
use MoeMizrak\Laravelopenrouter\DTO\ImageContentPartData;
use MoeMizrak\Laravelopenrouter\DTO\ImageUrlData;
use MoeMizrak\Laravelopenrouter\DTO\MessageData;
use MoeMizrak\Laravelopenrouter\Types\RoleType;

$chatData = new ChatData(
    messages: [
        new MessageData(
            role: RoleType::USER,
            content: [
                new ImageContentPartData(
                    image_url: new ImageUrlData(
                        url: 'https://example.com/image.jpg',
                        detail: 'high',
                    ),
                ),
            ],
        ),
    ],
    model: 'openai/gpt-4o',
);
```

--------------------------------

### GET /auth/key

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/endpoints.md

Retrieve rate limit and credits left on the API key. Called by OpenRouterRequest::limitRequest().

```APIDOC
## GET /auth/key

### Description
Retrieve rate limit and credits left on the API key. Called by `OpenRouterRequest::limitRequest()`.

### Method
GET

### Endpoint
/auth/key

### Parameters
No parameters documented.

### Request Example
No request body documented.

### Response
#### Success Response (200)
- **data.label** (string|null) - Maps to `LimitResponseData::$label`
- **data.usage** (float|null) - Maps to `LimitResponseData::$usage`
- **data.limit_remaining** (float|null) - Maps to `LimitResponseData::$limit_remaining`
- **data.limit** (int|null) - Maps to `LimitResponseData::$limit`
- **data.is_free_tier** (bool|null) - Maps to `LimitResponseData::$is_free_tier`
- **data.rate_limit.requests** (int|null) - Maps to `RateLimitData::$requests`
- **data.rate_limit.interval** (string|null) - Maps to `RateLimitData::$interval`

#### Response Example
No explicit response example provided.

### Authentication
Bearer token.

### Error Handling
No error-body translation; HTTP failures surface as Guzzle exceptions.

### Example
```php
use MoeMizrak\Laravelopenrouter\Facades\LaravelOpenRouter;

$limit = LaravelOpenRouter::limitRequest();
echo 'Credits remaining: ' . ($limit->limit_remaining ?? 'unlimited');
```
```

--------------------------------

### Example — basic call

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/limit-response-data.md

Shows how to retrieve and display the API key limit data using LaravelOpenRouter::limitRequest(). Outputs label, usage, remaining credits, credit limit, free tier status, and rate limit if present. Also demonstrates toArray() returning a null-filtered array.

```php
use MoeMizrak\Laravelopenrouter\Facades\LaravelOpenRouter;

$limit = LaravelOpenRouter::limitRequest();

echo 'Key: ' . $limit->label . PHP_EOL;
echo 'Credits used: ' . ($limit->usage ?? 'n/a') . PHP_EOL;
echo 'Credits remaining: ' . ($limit->limit_remaining ?? 'unlimited') . PHP_EOL;
echo 'Credit limit: ' . ($limit->limit ?? 'unlimited') . PHP_EOL;
echo 'Free tier: ' . var_export($limit->is_free_tier, true) . PHP_EOL;

if ($limit->rate_limit) {
    echo 'Rate limit: ' . $limit->rate_limit->requests . ' requests per ' . $limit->rate_limit->interval . PHP_EOL;
}

$array = $limit->toArray(); // null-filtered array
```

--------------------------------

### Example: strict JSON schema with ResponseFormatData

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/tool-plugin-dtos.md

Shows how to create a ChatData instance with a response_format of type json_schema, including a strict schema for an article object. It uses ProviderPreferencesData with require_parameters set to true.

```php
use MoeMizrak\Laravelopenrouter\DTO\ChatData;
use MoeMizrak\Laravelopenrouter\DTO\MessageData;
use MoeMizrak\Laravelopenrouter\DTO\ProviderPreferencesData;
use MoeMizrak\Laravelopenrouter\DTO\ResponseFormatData;
use MoeMizrak\Laravelopenrouter\Types\RoleType;

$chatData = new ChatData(
    messages: [new MessageData(role: RoleType::USER, content: 'Tell me a story.')],
    model: 'mistralai/mistral-7b-instruct:free',
    response_format: new ResponseFormatData(
        type: 'json_schema',
        json_schema: [
            'name' => 'article',
            'strict' => true,
            'schema' => [
                'type' => 'object',
                'properties' => [
                    'title' => ['type' => 'string', 'description' => 'article title'],
                    'details' => ['type' => 'string', 'description' => 'article detail'],
                ],
                'required' => ['title', 'details'],
                'additionalProperties' => false,
            ],
        ],
    ),
    provider: new ProviderPreferencesData(require_parameters: true),
);
```

--------------------------------

### Basic costRequest() call with chatRequest()

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/cost-response-data.md

Basic call example: performs a chat request, obtains the generation ID, then calls costRequest() with that ID. Prints the model, total cost formatted to 8 decimal places, latency, streamed flag, and usage. The cost fields may be null if the upstream response lacks data.

```php
use MoeMizrak\Laravelopenrouter\Facades\LaravelOpenRouter;

$response = LaravelOpenRouter::chatRequest($chatData);
$generationId = $response->id;

if ($generationId) {
    $cost = LaravelOpenRouter::costRequest($generationId);

    echo "Model: {$cost->model}" . PHP_EOL;
    echo "Total cost: $" . number_format($cost->total_cost, 8) . PHP_EOL;
    echo "Latency: {$cost->latency} ms" . PHP_EOL;
    echo "Streamed: " . var_export($cost->streamed, true) . PHP_EOL;
    echo "Usage: {$cost->usage}" . PHP_EOL;
}
```

--------------------------------

### Example: TextContentData with explicit cache breakpoint

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/content-dtos.md

Shows how to create a ChatData with a user message containing three TextContentData parts, where the middle part includes a CacheControlData with a TTL of '1h' to cache large reference text.

```php
use MoeMizrak\Laravelopenrouter\DTO\CacheControlData;
use MoeMizrak\Laravelopenrouter\DTO\ChatData;
use MoeMizrak\Laravelopenrouter\DTO\MessageData;
use MoeMizrak\Laravelopenrouter\DTO\TextContentData;
use MoeMizrak\Laravelopenrouter\Types\RoleType;

$chatData = new ChatData(
    messages: [
        new MessageData(
            role: RoleType::USER,
            content: [
                new TextContentData(text: 'Given the book below:'),
                new TextContentData(
                    text: 'HUGE_TEXT_BODY...',
                    cache_control: new CacheControlData(ttl: '1h'),
                ),
                new TextContentData(text: 'What triggered the collapse?'),
            ],
        ),
    ],
    model: 'anthropic/claude-sonnet-4.6',
);
```

--------------------------------

### Reading a streaming chunk

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/response-data.md

Example of reading a streaming chunk. Accesses delta content and role from the choices array. Notes that streaming usage arrives in the final chunk.

```php
use MoeMizrak\Laravelopenrouter\DTO\ResponseData;

/** @var ResponseData $chunk */
$delta = $chunk->choices[0]['delta']['content'] ?? '';
$role = $chunk->choices[0]['delta']['role'] ?? '';

// Streaming usage arrives in the final chunk:
$totalTokens = $chunk->usage?->total_tokens;
```

--------------------------------

### Audio transcription example using AudioContentData

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/content-dtos.md

Shows how to create a ChatData message with text and audio content for transcription. Uses AudioContentData with InputAudioData containing base64-encoded audio and format 'mp3'. The model is set to 'mistralai/voxtral-small-24b-2507'.

```php
use MoeMizrak\Laravelopenrouter\DTO\AudioContentData;
use MoeMizrak\Laravelopenrouter\DTO\ChatData;
use MoeMizrak\Laravelopenrouter\DTO\InputAudioData;
use MoeMizrak\Laravelopenrouter\DTO\MessageData;
use MoeMizrak\Laravelopenrouter\DTO\TextContentData;
use MoeMizrak\Laravelopenrouter\Types\RoleType;

$chatData = new ChatData(
    messages: [
        new MessageData(
            role: RoleType::USER,
            content: [
                new TextContentData(text: 'Please transcribe this audio file.'),
                new AudioContentData(
                    input_audio: new InputAudioData(
                        data: base64_encode(file_get_contents('/path/to/audio.mp3')),
                        format: 'mp3', // AudioFormatType::MP3
                    ),
                ),
            ],
        ),
    ],
    model: 'mistralai/voxtral-small-24b-2507',
);
```

--------------------------------

### Reading a chat response

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/response-data.md

Example of reading a chat response. Accesses message content, tool calls, and annotations from the choices array. Shows how to retrieve id, usage cost, prompt tokens, and convert to array.

```php
use MoeMizrak\Laravelopenrouter\DTO\ResponseData;

/** @var ResponseData $response */
$content = $response->choices[0]['message']['content'] ?? null; // string|null
$toolCalls = $response->choices[0]['message']['tool_calls'] ?? null;
$citations = $response->choices[0]['message']['annotations'] ?? null;

$id = $response->id;                         // used for costRequest
$cost = $response->usage?->cost;             // credit usage, if usage accounting enabled
$promptTokens = $response->usage?->prompt_tokens;

$array = $response->toArray();               // nulls filtered
```

--------------------------------

### costRequest() error handling with Guzzle exceptions

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/cost-response-data.md

Error handling example for HTTP-level failures. Catches ClientException for 4xx errors (e.g., 404 unknown generation) and RequestException for transport-level failures (timeout, DNS). Also checks for null id to detect when no cost data was returned.

```php
use GuzzleHttp\Exception\ClientException;
use GuzzleHttp\Exception\RequestException;
use MoeMizrak\Laravelopenrouter\Facades\LaravelOpenRouter;

try {
    $cost = LaravelOpenRouter::costRequest('gen-does-not-exist');
    // If the upstream returned no data, fields are null:
    if ($cost->id === null) {
        echo 'No cost data returned for this generation ID.';
    }
} catch (ClientException $e) {
    // 4xx, e.g. 404 unknown generation
    echo 'Cost lookup failed: ' . $e->getMessage();
} catch (RequestException $e) {
    // Transport-level failure (timeout, DNS, …)
    echo 'Request failed: ' . $e->getMessage();
}
```

--------------------------------

### Example — reading usage from chat response

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/usage-data.md

Shows how to access usage data from a chat response. The usage property is null unless the API returned usage. Uses null-safe operators to access nested details like cached_tokens and reasoning_tokens.

```php
use MoeMizrak\Laravelopenrouter\Facades\LaravelOpenRouter;

$response = LaravelOpenRouter::chatRequest($chatData);

$usage = $response->usage; // null unless the API returned usage

if ($usage !== null) {
    echo "prompt: {$usage->prompt_tokens}, completion: {$usage->completion_tokens}, total: {$usage->total_tokens}" . PHP_EOL;
    echo "cost: $" . number_format($usage->cost ?? 0, 8) . PHP_EOL;
    echo "cached tokens: " . ($usage->prompt_tokens_details?->cached_tokens ?? 0) . PHP_EOL;
    echo "reasoning tokens: " . ($usage->completion_tokens_details?->reasoning_tokens ?? 0) . PHP_EOL;
}
```

--------------------------------

### filterStreamingResponse usage example

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/openrouter-helper.md

Example of parsing a streaming chunk with filterStreamingResponse. The chunk contains a data: JSON payload and a data: [DONE] terminator; the example prints the content 'Hello'.

```php
use MoeMizrak\Laravelopenrouter\Helpers\OpenRouterHelper;

$helper = new OpenRouterHelper();

$chunk = "data: {\"id\":\"gen-1\",\"model\":\"m/m\",\"object\":\"chat.completion.chunk\",\"created\":1718885921,\"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":\"Hello\"},\"finish_reason\":null}]}\n\ndata: [DONE]\n";

$responses = $helper->filterStreamingResponse($chunk);

foreach ($responses as $responseData) {
    $text = $responseData->choices[0]['delta']['content'] ?? ($responseData->choices[0]['message']['content'] ?? '');
    echo $text;
}
// Prints: Hello
```

--------------------------------

### costRequest error handling example

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/openrouter-request.md

Example of error handling for costRequest. Catches GuzzleHttp\Exception\ClientException, e.g. a 404 when the generation ID is unknown, and logs the error with the status code.

```php
use GuzzleHttp\Exception\ClientException;

try {
    $cost = app(OpenRouterRequest::class)->costRequest('gen-xxxxxxxxxx');
} catch (ClientException $e) {
    // e.g. 404 when the generation ID is unknown
    logger()->error('Cost lookup failed', ['status' => $e->getCode()]);
}
```

--------------------------------

### PromptTokensDetailsData Constructor

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/usage-data.md

Creates a new PromptTokensDetailsData instance with optional token detail parameters. Includes parameters for cached, cache write, audio, and video tokens.

```APIDOC
## Constructor

### Signature
```php
public function __construct(
    public ?int $cached_tokens = null,
    public ?int $cache_write_tokens = null,
    public ?int $audio_tokens = null,
    public ?int $video_tokens = null
)
```

### Parameters
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| cached_tokens | `int|null` | no | `null` | Number of cached tokens used in the prompt. |
| cache_write_tokens | `int|null` | no | `null` | Number of tokens written to cache. |
| audio_tokens | `int|null` | no | `null` | Number of audio tokens used in the prompt. |
| video_tokens | `int|null` | no | `null` | Number of video tokens used in the prompt. |

### Method `toArray()`
Returns an array with the four keys, excluding any with `null` values.

```

--------------------------------

### jsonDecode usage example

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/openrouter-helper.md

Example usage of jsonDecode to extract an error message from a response. The response is decoded into an associative array, and the error message is retrieved safely with a null coalescing operator.

```php
$array = (new OpenRouterHelper())->jsonDecode($response);
$error = $array['error']['message'] ?? null;
```

--------------------------------

### Run tests with Composer or PHPUnit

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/CONTRIBUTING.md

Shows two ways to run the test suite: using the Composer script 'composer test' or directly invoking PHPUnit via 'vendor/bin/phpunit'. The comment indicates the first command runs all tests.

```bash
# Run all tests
composer test

# Or directly with PHPUnit
vendor/bin/phpunit
```

--------------------------------

### UsageData constructor with docblocks

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/usage-data.md

Constructor for UsageData with nullable parameters for prompt_tokens, completion_tokens, total_tokens, cost, prompt_tokens_details, and completion_tokens_details. Note: the docblocks for prompt_tokens and completion_tokens are swapped relative to OpenRouter semantics as documented in the source.

```php
public function __construct(
    /** Equivalent to "native_tokens_completion" in the /generation API */
    public ?int $prompt_tokens = null,
    /** Equivalent to "native_tokens_prompt" */
    public ?int $completion_tokens = null,
    /** Sum of the above two fields ($prompt_tokens and $completion_tokens) */
    public ?int $total_tokens = null,
    /** Credit usage of the request */
    public ?float $cost = null,
    /** Detailed breakdown of prompt tokens (cached, audio, video) */
    public ?PromptTokensDetailsData $prompt_tokens_details = null,
    /** Detailed breakdown of completion tokens (reasoning, image) */
    public ?CompletionTokensDetailsData $completion_tokens_details = null
) {
    parent::__construct(...func_get_args());
}
```

--------------------------------

### Manual construction of OpenRouterRequest with new OpenRouterHelper()

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/openrouter-request.md

Demonstrates manual construction of OpenRouterRequest, equivalent to what the Laravel container does. Normally you do not construct it manually; resolve from the container instead.

```php
// Manual construction (equivalent to what the container does)
$request = new OpenRouterRequest(new OpenRouterHelper());
```

--------------------------------

### PromptTokensDetailsData constructor

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/usage-data.md

Constructor for PromptTokensDetailsData with optional cached_tokens, cache_write_tokens, audio_tokens, and video_tokens parameters. Calls parent constructor with all arguments.

```php
public function __construct(
    /** Number of cached tokens used in the prompt. */
    public ?int $cached_tokens = null,
    /** Number of tokens written to cache. */
    public ?int $cache_write_tokens = null,
    /** Number of audio tokens used in the prompt. */
    public ?int $audio_tokens = null,
    /** Number of video tokens used in the prompt. */
    public ?int $video_tokens = null
) {
    parent::__construct(...func_get_args());
}
```

--------------------------------

### TextContentData

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/content-dtos.md

Documentation for the TextContentData DTO class, including its constructor parameters and an example usage with a cache breakpoint.

```APIDOC
## TextContentData

### Description
Plain-text content part for messages, with an optional per-block cache breakpoint. It extends `DataTransferObject` and exposes a public `convertToArray(): array` that serializes properties with `null` values filtered.

### Constructor
```php
public function __construct(
    #[AllowedValues([self::ALLOWED_TYPE])]
    public string $type = self::ALLOWED_TYPE,
    public string $text,
    public ?CacheControlData $cache_control = null,
) {
    parent::__construct(...func_get_args());
}
```

### Parameters
- **type** (`string`) - Optional - Default: `'text'` - Content type; must equal `'text'` (validated by `AllowedValues`).
- **text** (`string`) - Required - Text of the content.
- **cache_control** (`CacheControlData|null`) - Optional - Default: `null` - Cache breakpoint for this block (e.g. caching large reference text).

### Example — explicit cache breakpoint
```php
use MoeMizrak\Laravelopenrouter\DTO\CacheControlData;
use MoeMizrak\Laravelopenrouter\DTO\ChatData;
use MoeMizrak\Laravelopenrouter\DTO\MessageData;
use MoeMizrak\Laravelopenrouter\DTO\TextContentData;
use MoeMizrak\Laravelopenrouter\Types\RoleType;

$chatData = new ChatData(
    messages: [
        new MessageData(
            role: RoleType::USER,
            content: [
                new TextContentData(text: 'Given the book below:'),
                new TextContentData(
                    text: 'HUGE_TEXT_BODY...',
                    cache_control: new CacheControlData(ttl: '1h'),
                ),
                new TextContentData(text: 'What triggered the collapse?'),
            ],
        ),
    ],
    model: 'anthropic/claude-sonnet-4.6',
);
```
```

--------------------------------

### GET /generation?id={generationId}

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/endpoints.md

Retrieves cost and stats for a previous generation. Called by OpenRouterRequest::costRequest().

```APIDOC
## GET /generation?id={generationId}

### Description
Retrieve cost and stats for a previous generation. Called by `OpenRouterRequest::costRequest()`.

### Method
GET

### Endpoint
`generation?id={generationId}`

### Parameters
#### Path Parameters
- **generationId** (string) - Required - The ID of the generation to retrieve cost and stats for.

### Response
#### Success Response (200)
- **data.id** (string) - Maps to `CostResponseData::$id`
- **data.model** (string) - Maps to `CostResponseData::$model`
- **data.total_cost** (float) - Maps to `CostResponseData::$total_cost`
- **data.origin** (string) - Maps to `CostResponseData::$origin`
- **data.created_at** (string) - Maps to `CostResponseData::$created_at`
- **data.streamed** (bool|null) - Maps to `CostResponseData::$streamed`
- **data.cancelled** (bool|null) - Maps to `CostResponseData::$cancelled`
- **data.finish_reason** (string|null) - Maps to `CostResponseData::$finish_reason`
- **data.generation_time** (int|null) - Maps to `CostResponseData::$generation_time`
- **data.provider_name** (string|null) - Maps to `CostResponseData::$provider_name`
- **data.tokens_prompt** (int|null) - Maps to `CostResponseData::$tokens_prompt`
- **data.tokens_completion** (int|null) - Maps to `CostResponseData::$tokens_completion`
- **data.native_tokens_prompt** (int|null) - Maps to `CostResponseData::$native_tokens_prompt`
- **data.native_tokens_completion** (int|null) - Maps to `CostResponseData::$native_tokens_completion`
- **data.num_media_prompt** (int|null) - Maps to `CostResponseData::$num_media_prompt`
- **data.num_media_completion** (int|null) - Maps to `CostResponseData::$num_media_completion`
- **data.app_id** (int|null) - Maps to `CostResponseData::$app_id`
- **data.latency** (int|null) - Maps to `CostResponseData::$latency`
- **data.moderation_latency** (int|null) - Maps to `CostResponseData::$moderation_latency`
- **data.upstream_id** (string|null) - Maps to `CostResponseData::$upstream_id`
- **data.usage** (float|null) - Maps to `CostResponseData::$usage`

### Authentication
Bearer token.

### Error Handling
HTTP failures surface as Guzzle exceptions (e.g. `ClientException` on 404 for unknown generation IDs).

### Example
```php
use MoeMizrak\Laravelopenrouter\Facades\LaravelOpenRouter;

$cost = LaravelOpenRouter::costRequest($generationId);
echo $cost->total_cost;
```
```

--------------------------------

### filterStreamingResponse

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/openrouter-request.md

Documentation for the filterStreamingResponse method of the OpenRouterRequest class, including parameters, return type, exceptions, and a usage example.

```APIDOC
## filterStreamingResponse

### Description
Filters a raw streaming response string and maps it into an array of `ResponseData` DTOs (the same shape as `chatRequest` responses).

### Method
filterStreamingResponse

### Endpoint
`OpenRouterRequest::filterStreamingResponse(string $streamingResponse): array`

### Parameters
- **streamingResponse** (string) - Required - Raw chunk(s) read from the stream, e.g. `"data: {...}\n\ndata: {...}\n"`

### Return
`array` of `ResponseData` — one per complete `data:` JSON line (or buffered multi-line JSON) found in the input. The last chunk `data: [DONE]` is ignored because it is not valid JSON.

### Throws
- `ReflectionException` - Propagated from `OpenRouterHelper::formChatResponse()` while constructing DTOs

### Example — streaming with filtering
```php
use MoeMizrak\Laravelopenrouter\OpenRouterRequest;

$promise = app(OpenRouterRequest::class)->chatStreamRequest($chatData);
$stream = $promise->wait();

while (! $stream->eof()) {
    $raw = $stream->read(1024);

    foreach (app(OpenRouterRequest::class)->filterStreamingResponse($raw) as $responseData) {
        $delta = $responseData->choices[0]['delta']['content'] ?? '';
        echo $delta;
        ob_flush();
        flush();
    }
}
```
```

--------------------------------

### Chat request with explicit web plugin configuration

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/README.md

Equivalent to the ':online' shortcut, this configures the web plugin explicitly with PluginData. The engine parameter is optional: 'native' uses the provider's built-in search, 'exa' uses Exa's API, and 'undefined' falls back to native or Exa. max_results is optional and defaults to 5.

```php
$chatData = new ChatData(
    messages: [
        new MessageData(
            role: RoleType::USER,
            content: 'What are the latest developments in AI?',
        ),
    ],
    model: 'openai/gpt-4o',
    plugins: [
        new PluginData(
            id: 'web',
            max_results: 5, // Optional: number of search results to retrieve
            engine: 'undefined', // Optional: "native", "exa", or "undefined"
        ),
    ],
    web_search_options: new WebSearchOptionsData(
        search_context_size: SearchContextSizeType::MEDIUM, // Optional: low, medium, high
    ),
);
```

--------------------------------

### Retrieve cost via LaravelOpenRouter facade

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/endpoints.md

Example usage of the costRequest method to fetch cost data for a generation and access the total_cost property.

```php
use MoeMizrak\Laravelopenrouter\Facades\LaravelOpenRouter;

$cost = LaravelOpenRouter::costRequest($generationId);
echo $cost->total_cost;
```

--------------------------------

### convertToArray

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/messagedata.md

Documentation for the convertToArray method of the MessageData DTO, including examples for basic user messages, multimodal content, and tool-call round trips.

```APIDOC
## convertToArray

### Description
Converts the MessageData DTO into an array payload suitable for API requests, filtering out null values and applying transformations to nested content parts, tool calls, and other properties.

### Method
convertToArray

### Endpoint
N/A (PHP method)

### Parameters
None

### Request Example
```php
use MoeMizrak\Laravelopenrouter\DTO\MessageData;
use MoeMizrak\Laravelopenrouter\Types\RoleType;

$message = new MessageData(
    role: RoleType::USER,
    content: 'What is the weather in Tokyo?',
);

$array = $message->convertToArray();
// ['content' => 'What is the weather in Tokyo?', 'role' => 'user']
```

### Response
#### Success Response (array)
- **content** (string|array) - The message content, either a scalar string or an array of content parts.
- **role** (string) - The role of the message (e.g., 'user', 'assistant', 'tool').
- **tool_calls** (array|null) - Array of tool call data, each converted via its own convertToArray().
- **tool_call_id** (string|null) - The ID of the tool call this message responds to.
- **name** (string|null) - The name of the tool or function.
- **refusal** (string|null) - Not serialized.
- **reasoning** (string|null) - Not serialized.

#### Response Example
```php
['content' => 'What is the weather in Tokyo?', 'role' => 'user']
```
```

--------------------------------

### Run tests with Composer

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/CONTRIBUTING.md

Runs the test suite to verify everything is working. This is the primary command for running tests in the project.

```bash
composer test
```

--------------------------------

### Create advanced ProviderPreferencesData with all options

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/provider-preferences.md

Constructs a ProviderPreferencesData instance with fallbacks, required parameters, data collection denial, allowed providers, quantizations, sorting, throughput percentiles, latency, and max price. Uses DTOs and enums from the package.

```php
use MoeMizrak\Laravelopenrouter\DTO\MaxPriceData;
use MoeMizrak\Laravelopenrouter\DTO\PercentileData;
use MoeMizrak\Laravelopenrouter\DTO\ProviderPreferencesData;
use MoeMizrak\Laravelopenrouter\DTO\ProviderSortData;
use MoeMizrak\Laravelopenrouter\Types\DataCollectionType;
use MoeMizrak\Laravelopenrouter\Types\ProviderSortType;
use MoeMizrak\Laravelopenrouter\Types\QuantizationType;

$provider = new ProviderPreferencesData(
    allow_fallbacks: true,
    require_parameters: true,
    data_collection: DataCollectionType::DENY,
    only: ['openai', 'anthropic'],
    quantizations: [QuantizationType::FP16, QuantizationType::BF16],
    sort: new ProviderSortData(
        by: ProviderSortType::PRICE,
        partition: true,
    ),
    preferred_min_throughput: new PercentileData(
        p50: 100.0,
        p90: 50.0,
    ),
    preferred_max_latency: 2.5,
    max_price: new MaxPriceData(
        prompt: 0.001,
        completion: 0.002,
    ),
);
```

--------------------------------

### InputAudioData constructor

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/content-dtos.md

Defines the InputAudioData constructor with a required base64-encoded data string and an optional format parameter. The format defaults to null and supports 'mp3' and 'wav' as per AudioFormatType.

```php
// src/DTO/InputAudioData.php
public function __construct(
    /** base64 encoded audio data */
    public string $data,
    /** Supported audio formats are: mp3, wav. */
    public ?string $format = null
) {
    parent::__construct(...func_get_args());
}
```

--------------------------------

### Example - top-level caching with CacheControlData

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/_autodocs/api-reference/content-dtos.md

Shows how to use CacheControlData for top-level caching in a ChatData instance. It sets the cache_control property with type 'ephemeral' and an optional TTL of '1h'.

```php
use MoeMizrak\Laravelopenrouter\DTO\CacheControlData;
use MoeMizrak\Laravelopenrouter\DTO\ChatData;
use MoeMizrak\Laravelopenrouter\DTO\MessageData;
use MoeMizrak\Laravelopenrouter\Types\RoleType;

$chatData = new ChatData(
    messages: [new MessageData(role: RoleType::USER, content: 'What triggered the collapse?')],
    model: 'anthropic/claude-sonnet-4.6',
    cache_control: new CacheControlData(
        type: CacheControlData::ALLOWED_TYPE, // "ephemeral"
        ttl: '1h',                            // optional
    ),
);
```

--------------------------------

### Expected Response Content for Continuity Example

Source: https://github.com/moe-mizrak/laravel-openrouter/blob/master/README.md

Expected response content after sending the historical message and new message. The content is retrieved from the response choices using Arr::get.

```php
$content = Arr::get($response->choices[0], 'message.content');
// content = You are Moe, a fictional character and AI Necromancer, as per the context of the conversation we've established. In reality, you are the user interacting with me, an assistant designed to help answer questions and engage in friendly conversation.
```
Tokens:
Raw