Download the PHP package moe-mizrak/laravel-openrouter without Composer

Laravel OpenRouter

This Laravel package provides an easy-to-use interface for integrating OpenRouter into your Laravel applications. OpenRouter is a unified interface for Large Language Models (LLMs) that allows you to interact with various AI models through a single API.

Table of Contents

• 🤖 Requirements
• 🏁 Get Started
• 🧩 Configuration
• 🎨 Usage
  • Understanding ChatData DTO
  • LLM Parameters
  • Tool Calling Parameters
  • Additional Optional Parameters
  • OpenRouter-only Parameters
  • Provider Preferences
  • Creating a ChatData Instance
  • Using Facade
  • Chat Request
    • Stream Chat Request
    • Maintaining Conversation Continuity
    • Tool & Function Calling
    • Structured Output
    • Web Search
    • File/Document Inputs
    • Audio Inputs
    • Prompt caching
  • Cost Request
  • Limit Request
  • Using OpenRouterRequest Class
• 💫 Contributing
• 📜 License

🤖 Requirements

• PHP 8.2 or higher: Use version v2.x.x (latest compatible version)
  • Uses spatie laravel-data
• PHP 8.1: Use version v1.0.9.
  • Uses spatie data-transfer-object
  • For correct way to use DTOs, refer to v1.0.9 README.

🏁 Get Started

You can install the package via composer:

You can publish the config file with:

This is the contents of the published config file:

🧩 Configuration

After publishing the package configuration file, you'll need to add the following environment variables to your .env file:

[!NOTE]

• OPENROUTER_API_ENDPOINT: The endpoint URL for the OpenRouter API (default: https://openrouter.ai/api/v1/).
• OPENROUTER_API_KEY: Your API key for accessing the OpenRouter API. You can obtain this key from the OpenRouter dashboard.
• OPENROUTER_API_TIMEOUT: Request timeout in seconds. Increase value to 120 - 180 if you use long-thinking models like openai/o1 (default: 20)
• OPENROUTER_API_TITLE: Optional - Site URL for rankings on openrouter.ai
• OPENROUTER_API_REFERER: Optional - Site referer for rankings on openrouter.ai

🎨 Usage

This package provides two ways to interact with the OpenRouter API:

• Using the LaravelOpenRouter facade
• Instantiating the OpenRouterRequest class directly.

Both methods utilize the ChatData DTO class to structure the data sent to the API.

Understanding ChatData DTO

The ChatData class is used to encapsulate the data required for making chat requests to the OpenRouter API. Here's a breakdown of the key properties:

• messages (array|null): An array of MessageData objects representing the chat messages. This field is XOR-gated with the prompt field.
• prompt (string|null): A string representing the prompt for the chat request. This field is XOR-gated with the messages field.
• model (string|null): The name of the model to be used for the chat request. If not specified, the user's default model will be used. This field is XOR-gated with the models field.
• response_format (ResponseFormatData|null): An instance of the ResponseFormatData class representing the desired format for the response.
• usage (bool|null): A boolean indicating whether to include usage information in the response. Default is false because enabling usage accounting will add a few hundred milliseconds to the response as the API calculates token counts and costs.
• stop (array|string|null): A value specifying the stop sequence for the chat generation.
• stream (bool|null): A boolean indicating whether streaming should be enabled or not.
• include_reasoning (bool|null): Whether to return the model's reasoning (Note: this parameter is deprecated, use reasoning parameter instead. For backward compatibility, package still supports the include_reasoning parameter)
• reasoning (ReasoningData|null): An instance of the ReasoningData class for reasoning configuration. It provides a transparent look into the reasoning steps taken by a model.
• cache_control (OpenRouter Prompt Caching.
• session_id (string|null): A string representing the session ID for maintaining conversation continuity across multiple requests. When provided, OpenRouter will attempt to route the request to the same provider and model used in previous interactions with the same session ID, helping to maintain context and coherence in multi-turn conversations. For more details, see OpenRouter Broadcast.
• debug (DebugData|null): An instance of the DebugData class for debugging options (e.g., echo_upstream_body to include raw upstream responses in the output for troubleshooting).

LLM Parameters

These properties control various aspects of the generated response (more info):

• max_tokens (int|null): The maximum number of tokens that can be generated in the completion. Default is 1024.
• temperature (float|null): A value between 0 and 2 controlling the randomness of the output.
• top_p (float|null): A value between 0 and 1 for nucleus sampling, an alternative to temperature sampling.
• top_k (float|null): A value between 1 and infinity for top-k sampling (not available for OpenAI models).
• frequency_penalty (float|null): A value between -2 and 2 for penalizing new tokens based on their existing frequency.
• presence_penalty (float|null): A value between -2 and 2 for penalizing new tokens based on whether they appear in the text so far.
• repetition_penalty (float|null): A value between 0 and 2 for penalizing repetitive tokens.
• seed (int|null): A value for deterministic sampling (OpenAI models only, in beta).

Tool-calling Parameters

Only natively suported by OpenAI models. For others, we submit a YAML-formatted string with these tools at the end of the prompt.

• tool_choice (string|array|null): A value specifying the tool choice for function calling (OpenAI models only).
• tools (array|null): An array of ToolCallData objects for function calling.

Additional optional parameters

• logit_bias (array|null): An array for modifying the likelihood of specified tokens appearing in the completion.

OpenRouter-only parameters

• transforms (array|null): An array for configuring prompt transforms.
• plugins (array|null): An array of PluginData objects for configuring plugins such as web search or file parsing.
• web_search_options (WebSearchOptionsData|null): An instance of the WebSearchOptionsData DTO object for configuring web search (e.g. search_context_size: SearchContextSizeType::LOW).
• models (array|null): An array of models to automatically try if the primary model is unavailable. This field is XOR-gated with the model field.
• route (string|null): A value specifying the route type (e.g., RouteType::FALLBACK).
• provider (ProviderPreferencesData|null): An instance of the Provider Preferences).

Provider Preferences

The OpenRouter Provider Selection.

Example with advanced provider preferences:

Creating a ChatData Instance

This is a sample chat data instance (Refer to spatie laravel-data how to create, use DTOs):

Using Facade

The LaravelOpenRouter facade offers a convenient way to make OpenRouter API requests.

Chat Request

To send a chat request, create an instance of ChatData and pass it to the chatRequest method:

• Stream Chat Request

  Streaming chat request is also supported and can be used as following by using chatStreamRequest function:

You do not need to specify 'stream' = true in ChatData since chatStreamRequest does it for you.

• Maintaining Conversation Continuity

  If you want to maintain conversation continuity meaning that historical chat will be remembered and considered for your new chat request, you need to send historical messages along with the new message:

Expected response:

• Tool & Function Calling

  (Please also refer to OpenRouter Document Function Calling for more details and models supporting tool calling)

Tool calls (also known as function calls) give an LLM access to external tools. The LLM does not call the tools directly. Instead, it suggests the tool to call.

[!NOTE] The user then calls the tool separately and provides the results back to the LLM. Finally, the LLM formats the response into an answer to the user’s original question.

This is an example of how to use tool calling with OpenRouter:

Basically it follows these steps:

1. Define the tools and send the initial chat request including the tools and tool_choice optional parameters.
2. If the LLM suggests a tool call, extract the tool call information from the response and make the actual tool call separately.
3. Provide the tool result back to the LLM by creating a new chat request that includes the original user message, the assistant's tool call message, and the tool response message including the tool_call_id which is the ID generated by the model/LLM for the tool call.
4. Send the new chat request to get the final response from the LLM.

• Structured Output

  (Please also refer to OpenRouter Document Structured Output for models supporting structured output, also for more details)

If you want to receive the response in a structured format, you can specify the type property for response_format (ChatData object.

Additionally, it's recommended to set the require_parameters property for provider (ChatData object.

[!CAUTION] When using structured outputs, you may encounter these scenarios:

• Model doesn’t support structured outputs
• Invalid schema

Also: If you face an error, remove require_parameters property of provider to see the result.

Check out Requiring Providers to Support All Parameters for more details.

You can also specify the response_format as json_schema to receive the response in a specified schema format (Advisable to set 'strict' => true in json_schema array for strict schema):

[!TIP] You can also use prompt engineering to obtain structured output and control the format of responses.

• Web Search

  (Please also refer to OpenRouter Document Web Search for more details)

Web Search feature works on any model on OpenRouter.

You can incorporate relevant web search results for any model on OpenRouter by activating and customizing the web plugin, or by appending :online to the model slug. e.g., model: "openai/gpt-4o:online" or model: "openai/gpt-oss-20b:free:online".

web_search_options parameter in ChatData is optional, where you can customize the web search behavior as search_context_size can be set to low, medium, or high depending on how much web search context you want to include in the response.

• SearchContextSizeType::LOW is for minimal search context, suitable for basic queries.
• SearchContextSizeType::MEDIUM is for moderate amount of web search context.
• SearchContextSizeType::HIGH is for extensive web search context.

:online is a shortcut for using the web plugin, and is exactly equivalent to:

engine parameter in PluginData is optional, where you can specify the web search engine to be used:

• native: Always uses the model provider’s built-in web search capabilities
• exa: Uses Exa’s search API for web results
• undefined: Uses native search if available for the provider, otherwise falls back to Exa

And here is how annotations are included in the response when using web search where annotations contains type: url_citation and url_citation: {url, title, content, start_index, end_index}:

• File/Document Inputs

  (Please also refer to OpenRouter Document File Inputs for more details)

You can provide file input by using the FileContentData DTO class as following:

[!NOTE]

• plugins parameter in ChatData is optional.
• If you don’t explicitly specify an engine, OpenRouter will default first to the model’s native file processing capabilities, and if that’s not available, it will use the "mistral-ocr" engine.

Using base64-encoded files:

[!TIP]

• File input feature works on any model on OpenRouter.
• The filename parameter is optional but recommended for context.

• Audio Inputs

  (Please also refer to OpenRouter Document Audio Inputs for models supporting audio inputs, also for more details)

Audio input is supported by some models in OpenRouter. You can provide audio input by using the AudioContentData DTO class as following:

[!NOTE] Only mp3 and wav formats are supported for audio inputs.

And make sure to provide valid base64-encoded audio data.

• Prompt caching

OpenRouter supports prompt caching on supported providers/models to decrease cost and latency on repeated requests. This package supports both approaches described in OpenRouter docs:

• Top-level caching (recommended for multi-turn conversations): set ChatData::$cache_control.
• Explicit cache breakpoint (fine-grained control): set TextContentData::$cache_control on the large text block(s) you want to cache (e.g. RAG data, CSV data, long instructions, etc.).

OpenRouter docs: Prompt Caching

Top-level example (automatic caching):

Explicit breakpoint example (cache a large text block):

Cost Request

To retrieve the cost of a generation, first make a chat request and obtain the generationId. Then, pass the generationId to the costRequest method:

Limit Request

To retrieve rate limit and credits left on the API key:

Using OpenRouterRequest Class

You can also inject the OpenRouterRequest class in the constructor of your class and use its methods directly.

💫 Contributing

We welcome contributions! If you'd like to improve this package, simply create a pull request with your changes. Your efforts help enhance its functionality and documentation.

Please read our Contributing Guide for details on our development process, commit conventions, and how to submit pull requests.

📜 License

Laravel OpenRouter is an open-sourced software licensed under the MIT license.