Skip to main content

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.

ChatUsage deserializes the raw usage object from an OpenAI-compatible API response into the portable AiSdk\Support\Usage value object used throughout the SDK. It is called inside both ChatResponseParser (for complete responses) and ChatStreamParser (when the final streaming chunk includes usage data). All fields beyond the basic prompt/completion counts are treated as optional to accommodate providers that omit the extended details.

​
Namespace

AiSdk\OpenAICompatible\Support\ChatUsage

​
Methods

​
fromArray()

public static function fromArray(array $usage): Usage
Constructs a Usage instance from the raw associative array found at the usage key of an OpenAI API response.
​
usage
array<string, mixed>
required
The raw usage object as decoded from the JSON response. Missing keys are treated as 0 (for required token counts) or null (for optional detail fields).
Returns AiSdk\Support\Usage.

​
Field mappings

​
inputTokens
int
Sourced from usage.prompt_tokens. Cast to int; defaults to 0 if absent.
​
outputTokens
int
Sourced from usage.completion_tokens. Cast to int; defaults to 0 if absent.
​
totalTokens
int|null
Sourced from usage.total_tokens. Set to null if the key is not present in the payload.
​
reasoningTokens
int|null
Sourced from usage.completion_tokens_details.reasoning_tokens. Set to null if the nested key is absent. Populated by models that expose internal chain-of-thought token counts (e.g. o3, o1).
​
cachedInputTokens
int|null
Sourced from usage.prompt_tokens_details.cached_tokens. Set to null if the nested key is absent. Populated when the provider’s prompt-caching feature was active for the request.

​
Example

use AiSdk\OpenAICompatible\Support\ChatUsage;

// Raw usage object from an OpenAI API response
$raw = [
    'prompt_tokens'     => 42,
    'completion_tokens' => 18,
    'total_tokens'      => 60,
    'completion_tokens_details' => [
        'reasoning_tokens' => 5,
    ],
    'prompt_tokens_details' => [
        'cached_tokens' => 10,
    ],
];

$usage = ChatUsage::fromArray($raw);

// $usage->inputTokens      === 42
// $usage->outputTokens     === 18
// $usage->totalTokens      === 60
// $usage->reasoningTokens  === 5
// $usage->cachedInputTokens === 10
When only the basic fields are present (as returned by many providers): 
$raw = [
    'prompt_tokens'     => 10,
    'completion_tokens' => 4,
];

$usage = ChatUsage::fromArray($raw);

// $usage->inputTokens       === 10
// $usage->outputTokens      === 4
// $usage->totalTokens       === null
// $usage->reasoningTokens   === null
// $usage->cachedInputTokens === null
If the usage key is entirely absent from an API response payload, ChatResponseParser does not call ChatUsage::fromArray() — it falls back to Usage::empty() instead, which sets all token counts to 0 or null. This prevents fatal errors when providers omit usage data on cached or filtered responses.

Build docs developers (and LLMs) love

Get started for freeTalk to us