OpenRouterGateway
class OpenRouterGateway implements Gateway, RerankingGateway, StepTextGateway
Traits
Methods
Build the request body for the current text generation step.
Build the request body for the Chat Completions API.
Build the response format options for structured output.
Create an HTTP client with the provider's request options.
Select a boot-registered connection without retaining dynamic provider names.
Process a streaming response for a single text generation step.
Merge consecutive reasoning fragments while preserving separate blocks.
Get the human readable reasoning carried by a delta's reasoning details.
Generate a lowercase UUID v7 for use as a stream event ID.
Derive a filename for a nameless document from its MIME type.
Map the given Hypervel attachments to Chat Completions content parts.
Map the given Hypervel messages to Chat Completions messages format.
Map a user message to Chat Completions format.
Map an assistant message to Chat Completions format.
Map a tool result message to Chat Completions format.
Serialize a tool call DTO to Chat Completions array format.
Map a tool call or result ID to the provider's wire format.
Decode a structured output payload, tolerating markdown code fences.
Join reasoning blocks, separating each block with a blank line.
Validate the OpenRouter response data.
Parse the OpenRouter response data into a single step response.
Extract the reasoning text from an assistant message.
Extract the reasoning details to replay with the message's tool calls.
Extract URL citations from the message annotations array.
Extract and map the finish reason from the response.
Execute a callback with failoverable error handling.
Get the short Retry-After delay of a rate limited or overloaded response, if it has one.
Determine if the response is a 402, or a 429 insufficient credits or quota error rather than a rate limit.
Get the status codes that indicate a provider is transiently unavailable and the request should fail over.
Get the patterns used to detect insufficient credits or quota errors.
Get the error codes or types that indicate insufficient credits or quota on a 429 response.
Map a provider tool to an OpenRouter tool definition.
Return embedding values in input order without accepting ambiguous indices.
Parse an SSE stream body into decoded JSON data objects.
Read one line without waiting for a larger body buffer to fill.
Generate text for a single Chat Completions step.
Stream text for a single Chat Completions step.
Get the stream options sent with a streaming Chat Completions request.
Wrap PCM audio in a WAV container.
Map a web fetch tool to an OpenRouter server tool definition.
Map a web search tool to an OpenRouter server tool definition.
Generate images from the given prompt.
Generate audio from the given text.
Resolve the alias voice for the given model.
Resolve the response_format the model accepts. Gemini TTS only accepts pcm.
Map a response_format value to the HTTP audio MIME type.
Determine whether the model uses Gemini text-to-speech.
Generate text from the given audio.
Map an audio MIME type to OpenRouter's input_audio.format value.
Generate embeddings for the given inputs.
Rerank the given documents by relevance to a query.
Details
in
BuildsTextRequests at line 20
protected array
buildStepBody(Provider $provider, string $model, string|null $instructions, array $messages, array $tools, array|null $schema, TextGenerationOptions|null $options, StepContext $stepContext)
Build the request body for the current text generation step.
in
BuildsTextRequests at line 36
protected array
buildTextRequestBody(Provider $provider, string $model, string|null $instructions, array $messages, array $tools, array|null $schema, TextGenerationOptions|null $options)
Build the request body for the Chat Completions API.
in
BuildsTextRequests at line 86
protected array
buildResponseFormat(array $schema, bool $strict)
Build the response format options for structured output.
in
CreatesClient at line 21
protected PendingRequest
createClient(string $baseUrl, array $headers = [], array $configuredHeaders = [], int|null $timeout = 60, bool $throw = true)
Create an HTTP client with the provider's request options.
in
CreatesClient at line 43
protected string
httpConnection(Provider $provider)
Select a boot-registered connection without retaining dynamic provider names.
in
CreatesOpenRouterClient at line 18
protected PendingRequest
client(Provider $provider, int|null $timeout = null)
Get an HTTP client for the OpenRouter API.
in
CreatesOpenRouterClient at line 37
protected string
baseUrl(Provider $provider)
Get the base URL for the OpenRouter API.
in
HandlesTextStreaming at line 36
protected Generator
processTextStream(string $invocationId, Provider $provider, string $model, StreamInterface $streamBody)
Process a streaming response for a single text generation step.
in
HandlesTextStreaming at line 276
protected array
mergeReasoningDetails(array $merged, array $details)
Merge consecutive reasoning fragments while preserving separate blocks.
in
HandlesTextStreaming at line 309
protected string
reasoningTextIn(array $details)
Get the human readable reasoning carried by a delta's reasoning details.
in
HandlesTextStreaming at line 320
protected string
generateEventId()
Generate a lowercase UUID v7 for use as a stream event ID.
in
ResolvesDocumentFilenames at line 12
protected string
fallbackFilename(string|null $mimeType)
Derive a filename for a nameless document from its MIME type.
in
MapsAttachments at line 34
protected array
mapAttachments(Collection $attachments)
Map the given Hypervel attachments to Chat Completions content parts.
in
MapsAttachments at line 136
protected bool
isImage(UploadedFile $attachment)
Determine if the given uploaded file is an image.
in
MapsAttachments at line 153
protected bool
isAudio(UploadedFile $attachment)
Determine if the given uploaded file is an audio file.
in
MapsChatCompletionMessages at line 19
protected array
mapMessagesToChat(array $messages, string|null $instructions = null)
Map the given Hypervel messages to Chat Completions messages format.
in
MapsChatCompletionMessages at line 46
protected void
mapUserMessage(UserMessage|Message $message, array $chatMessages)
Map a user message to Chat Completions format.
in
MapsChatCompletionMessages at line 69
protected void
mapAssistantMessage(AssistantMessage|Message $message, array $chatMessages)
Map an assistant message to Chat Completions format.
in
MapsChatCompletionMessages at line 89
protected void
mapToolResultMessage(ToolResultMessage|Message $message, array $chatMessages)
Map a tool result message to Chat Completions format.
in
MapsChatCompletionMessages at line 107
protected array
serializeToolCallToChat(ToolCall $toolCall)
Serialize a tool call DTO to Chat Completions array format.
in
MapsChatCompletionMessages at line 122
protected string
mapToolCallId(string $id)
Map a tool call or result ID to the provider's wire format.
in
DecodesStructuredOutput at line 12
protected array
decodeStructuredOutput(string|null $text)
Decode a structured output payload, tolerating markdown code fences.
in
JoinsReasoning at line 16
static protected string
joinReasoning(iterable $blocks)
Join reasoning blocks, separating each block with a blank line.
in
ParsesTextResponses at line 32
protected void
validateTextResponse(array $data)
Validate the OpenRouter response data.
in
ParsesTextResponses at line 58
protected StepResponse
parseTextResponse(array $data, Provider $provider, bool $structured)
Parse the OpenRouter response data into a single step response.
in
ParsesTextResponses at line 99
protected string
extractReasoning(array $message)
Extract the reasoning text from an assistant message.
in
ParsesTextResponses at line 116
protected array
extractReasoningDetails(array $message)
Extract the reasoning details to replay with the message's tool calls.
in
ParsesTextResponses at line 126
protected Collection
extractCitations(array $message)
Extract URL citations from the message annotations array.
in
ParsesTextResponses at line 149
protected TextUsage
extractUsage(array $data)
Extract usage data from the response.
in
ParsesTextResponses at line 165
protected FinishReason
extractFinishReason(array $choice)
Extract and map the finish reason from the response.
in
HandlesFailoverErrors at line 26
protected mixed
withErrorHandling(string $providerName, Closure $callback)
Execute a callback with failoverable error handling.
in
HandlesFailoverErrors at line 91
protected int|null
retryAfterSeconds(Throwable $exception)
Get the short Retry-After delay of a rate limited or overloaded response, if it has one.
in
HandlesFailoverErrors at line 115
protected bool
isInsufficientCredits(RequestException $exception)
Determine if the response is a 402, or a 429 insufficient credits or quota error rather than a rate limit.
in
HandlesFailoverErrors at line 138
protected array
overloadedStatusCodes()
Get the status codes that indicate a provider is transiently unavailable and the request should fail over.
in
HandlesFailoverErrors at line 148
protected array
insufficientCreditPatterns()
Get the patterns used to detect insufficient credits or quota errors.
in
HandlesFailoverErrors at line 158
protected array
insufficientCreditCodes()
Get the error codes or types that indicate insufficient credits or quota on a 429 response.
in
MapsChatCompletionTools at line 22
protected array
mapTools(array $tools, Provider $provider)
Map the given tools to Chat Completions function definitions.
at line 78
protected array
mapProviderTool(ProviderTool $tool, Provider $provider)
Map a provider tool to an OpenRouter tool definition.
in
MapsChatCompletionTools at line 48
protected array
mapTool(Tool $tool)
Map a regular tool to a Chat Completions function definition.
in
MapsChatCompletionTools at line 76
protected string|array
mapToolChoice(ToolChoice $choice)
Map a tool choice to the Chat Completions tool_choice shape.
in
ParsesIndexedEmbeddings at line 17
protected array
parseIndexedEmbeddings(array $records, int $expectedCount, string $providerName)
Return embedding values in input order without accepting ambiguous indices.
in
ParsesServerSentEvents at line 24
protected Generator
parseServerSentEvents(StreamInterface $streamBody)
Parse an SSE stream body into decoded JSON data objects.
in
ParsesServerSentEvents at line 52
protected string
readLine(StreamInterface $streamBody)
Read one line without waiting for a larger body buffer to fill.
in
PerformsChatCompletionSteps at line 19
StepResponse
generateTextStep(TextProvider $provider, string $model, string|null $instructions, array $messages, array $tools, array|null $schema, TextGenerationOptions|null $options, int|null $timeout, StepContext $stepContext)
Generate text for a single Chat Completions step.
in
PerformsChatCompletionSteps at line 48
Generator
generateStreamStep(string $invocationId, TextProvider $provider, string $model, string|null $instructions, array $messages, array $tools, array|null $schema, TextGenerationOptions|null $options, int|null $timeout, StepContext $stepContext)
Stream text for a single Chat Completions step.
in
PerformsChatCompletionSteps at line 82
protected array|null
streamOptions(Provider $provider)
Get the stream options sent with a streaming Chat Completions request.
in
WrapsPcmAudio at line 12
protected string
pcmToWav(string $pcm, int $sampleRate = 24000, int $channels = 1, int $bitsPerSample = 16)
Wrap PCM audio in a WAV container.
at line 71
__construct(Dispatcher $events)
Create an OpenRouter gateway instance.
at line 90
protected array
mapWebFetchTool(WebFetch $tool, Provider $provider)
Map a web fetch tool to an OpenRouter server tool definition.
at line 105
protected array
mapWebSearchTool(WebSearch $tool, Provider $provider)
Map a web search tool to an OpenRouter server tool definition.
at line 120
ImageResponse
generateImage(ImageProvider $provider, string $model, string $prompt, array $attachments = [], string|null $size = null, string|null $quality = null, int|null $timeout = null, array $providerOptions = [])
Generate images from the given prompt.
at line 166
AudioResponse
generateAudio(AudioProvider $provider, string $model, string $text, string $voice, string|null $instructions = null, int $timeout = 30, array $providerOptions = [])
Generate audio from the given text.
at line 200
protected string
resolveVoice(string $model, string $voice)
Resolve the alias voice for the given model.
at line 220
protected string
audioResponseFormat(string $model)
Resolve the response_format the model accepts. Gemini TTS only accepts pcm.
at line 228
protected string
audioResponseMimeType(string $format)
Map a response_format value to the HTTP audio MIME type.
at line 244
protected bool
isGeminiTtsModel(string $model)
Determine whether the model uses Gemini text-to-speech.
at line 256
TranscriptionResponse
generateTranscription(TranscriptionProvider $provider, string $model, TranscribableAudio $audio, string|null $language = null, bool $diarize = false, int $timeout = 30, array $providerOptions = [])
Generate text from the given audio.
at line 309
protected string
audioFormat(string $mimeType)
Map an audio MIME type to OpenRouter's input_audio.format value.
at line 329
EmbeddingsResponse
generateEmbeddings(EmbeddingProvider $provider, string $model, array $inputs, int $dimensions, int $timeout = 30, array $providerOptions = [])
Generate embeddings for the given inputs.
at line 363
RerankingResponse
rerank(RerankingProvider $provider, string $model, array $documents, string $query, int|null $limit = null, int $timeout = 30, array $providerOptions = [])
Rerank the given documents by relevance to a query.