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
    • Function-calling
    • Additional Optional Parameters
    • OpenRouter-only Parameters
  • Creating a ChatData Instance
  • Using Facade
    • Chat Request
      • Stream Chat Request
      • Maintaining Conversation Continuity
      • Structured Output
    • Cost Request
    • Limit Request
  • Using OpenRouterRequest Class
    • Chat Request
    • Cost Request
    • Limit Request
• 💫 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.
• 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.

  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).

  Function-calling

  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.
• 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 ProviderPreferencesData DTO object for configuring 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:

• 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.

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.

Chat Request

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

Cost Request

Similarly, to retrieve the cost of a generation, create a chat request to obtain the generationId, then pass the generationId to the costRequest method:

Limit Request

Similarly, to retrieve rate limit and credits left on the API key:

💫 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.

📜 License

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