Documentation Index
Fetch the complete documentation index at: https://mintlify.com/phpaisdk/openai-compatible/llms.txt
Use this file to discover all available pages before exploring further.
aisdk/openai-compatible is a shared wire-format adapter library for the PHP AI SDK. It provides reusable request builders, response parsers, and SSE stream parsers that implement the OpenAI-compatible chat-completions and image-generation wire format. Any PHP AI SDK provider that speaks OpenAI-compatible APIs — such as Groq, xAI, or OpenRouter — can depend on this package instead of reimplementing the same serialization and parsing logic from scratch.
This is a provider-layer package. It is consumed by provider packages, not directly by end-user application code. If you are building an application, use a provider package (e.g.
aisdk/openai, aisdk/groq) which already integrates this adapter internally.What This Package Owns
aisdk/openai-compatible is deliberately narrow in scope. It owns the OpenAI wire format and nothing else:
- Request body construction — converting portable
TextModelRequestandImageRequestobjects into the exact JSON shapes expected by/chat/completionsand/images/generationsendpoints. - Response parsing — deserializing provider JSON payloads into normalized
TextModelResponseandImageResponseobjects with typed parts. - SSE stream parsing — converting a stream of raw Server-Sent Events into typed
StreamPartvalues (TextDeltaPart,ToolCallStartPart,ToolCallDeltaPart,FinishPart, etc.). - Message and tool conversion — translating portable
Messageand tool objects into their OpenAI-wire equivalents. - Usage normalization — mapping provider token-count fields (
prompt_tokens,completion_tokens, and their nested detail keys) into a uniformUsageobject. - Finish reason mapping — translating provider finish-reason strings (
stop,tool_calls,content_filter, etc.) into the portableFinishReasonenum.
What This Package Does NOT Own
The following concerns belong to the individual provider package, not to this adapter:- Authentication — API keys, OAuth tokens, and credential management.
- Model catalogs — which model IDs a provider exposes, their capabilities, and their pricing.
- Provider-specific quirks — structured-output downgrades, custom parameter names, endpoint path construction, and retry logic.
- HTTP transport — making the actual HTTP call, managing connections, and handling HTTP-level errors.
Public API
| Class | Description |
|---|---|
ChatRequestBuilder | Builds an OpenAI-compatible /chat/completions request body from a portable TextModelRequest. |
ChatResponseParser | Parses a /chat/completions JSON payload into a normalized TextModelResponse with typed parts. |
ChatStreamParser | Converts an iterable of raw SSE events into a Generator of typed StreamPart values. |
ImageRequestBuilder | Builds an OpenAI-compatible /images/generations request body from a portable ImageRequest. |
ImageResponseParser | Parses an /images/generations JSON payload into a normalized ImageResponse. |
ChatMessageConverter | Converts portable Message objects into the OpenAI messages array format, including multimodal content. |
ChatToolConverter | Converts portable tool definitions and tool-choice values into OpenAI wire shapes. |
MapsFinishReason | Maps raw provider finish-reason strings to the portable FinishReason enum. |
ChatUsage | Normalizes OpenAI-style token-count fields (including reasoning and cached-input detail keys) into a Usage value object. |
Where to Go Next
Quickstart
Build a minimal provider using
ChatRequestBuilder, ChatResponseParser, and ChatStreamParser end-to-end.Building a Provider
Full walkthrough of creating a production provider package on top of
aisdk/core and aisdk/openai-compatible.ChatRequestBuilder API
Reference for every parameter accepted by
ChatRequestBuilder::build(), including reasoning, tools, and structured output.ImageRequestBuilder API
Reference for
ImageRequestBuilder::build() options, aspect-ratio inference, and provider raw overrides.