How to Represent Multimodal Consumption in a Single Usage Record

A multimodal request should produce one versioned request-level usage envelope containing separate, unit-aware components for text, image, audio, and video consumption. Keep the logical request identity, provider and model context, lifecycle status, and timestamps in the shared envelope; record each modality’s input, output, cached, and provider-defined quantities separately. Do not collapse tokens, images, pixels, seconds, frames, or bytes into an ambiguous total.

The Short Answer: One Request Envelope, Separate Modality Measurements

The most practical design is a parent-child structure:

1. One envelope represents the logical request. It provides the stable record used for reconciliation, observability, and cost allocation.
2. One or more components represent measured consumption. Each component identifies its modality, direction or usage category, quantity, unit, source, and estimation status.
3. Raw provider usage remains available. The original provider payload can coexist with normalized fields for audit and future adapter changes.
4. Pricing remains separate from physical consumption. Cost should be attached only when known and should identify its currency and rate source.

This is a proposed implementation pattern rather than a universal API standard. Providers differ in how they define tokens, images, pixels, media duration, frames, bytes, cached work, and billable units. A normalization layer should preserve those differences instead of creating false equivalence.

What belongs at the request level

The shared envelope should answer questions that apply to the complete interaction rather than any individual modality:

• Which logical request or interaction generated the usage?
• Which application, tenant, project, or cost center initiated it?
• Which provider and model handled it?
• When did processing begin, update, and reach a terminal state?
• Did it succeed, partially succeed, fail, or remain pending?
• Was it part of a batch, retry sequence, stream, or asynchronous job?
• Which schema version and adapter produced the normalized record?

These fields let downstream systems group related activity without forcing every text, image, audio, or video measurement into the same unit.

Why text, image, audio, and video should not share one scalar total

A single scalar such as total_tokens loses essential meaning when a request includes unlike media. For example, a provider might report text in tokens, image input in pixels or image counts, audio in seconds, and video in frames or bytes. Adding those quantities together would produce a number with no stable operational or financial interpretation.

Even when a provider internally converts media into token-like billing units, the record should distinguish between:

• the physical or provider-reported media measurement;
• any normalized quantity calculated by an adapter;
• the provider’s billable quantity, if available; and
• the monetary cost calculated from a particular rate.

That separation makes it possible to update pricing logic without rewriting historical consumption and to compare provider behavior without implying that unlike units are interchangeable.

Define Stable Identity, Context, and Lifecycle Fields

A usage record must survive retries, streaming updates, batches, and delayed media jobs. That requires stable identity at the logical-request level and separate identifiers for individual execution attempts.

Request, interaction, attempt, batch, and provider identifiers

Recommended identifiers include:

• request_id: The stable identity of the logical request in the consuming application.
• interaction_id: An optional identity for a longer conversation, agent run, or workflow containing multiple requests.
• attempt_id: A unique identity for one execution attempt, including retries or provider failover.
• batch_id: An optional identity linking requests submitted or processed as a batch.
• provider_request_id: The identifier returned by the provider, when one is supplied.
• idempotency_key: A key used to recognize repeated delivery or processing of the same event.

The logical request_id should not be reused as the attempt identity. A request routed to one provider and then retried against another is still one business request, but it has multiple attempts with potentially distinct consumption.

Whether failed-attempt consumption is included in chargeback depends on the provider’s reporting and the organization’s accounting policy. It should not simply disappear from telemetry. Retaining attempt-level detail allows finance and platform teams to distinguish end-user consumption from retry overhead.

Model, provider, timestamps, status, and schema version

A useful envelope should also carry context and lifecycle metadata:

• provider and model identifiers as reported or configured;
• optional region, endpoint, deployment, or adapter identifiers;
• creation, first-response, completion, and finalization timestamps where available;
• a status such as pending, streaming, succeeded, partially_succeeded, failed, or cancelled;
• a terminal or finalized indicator;
• schema and adapter versions;
• application, tenant, project, environment, and cost-allocation tags where appropriate.

Field names and lifecycle states will vary by implementation. What matters is that consumers can distinguish an intermediate update from a finalized record and understand which transformation produced the normalized data.

Reconcile streaming, retries, batches, and asynchronous jobs

A robust reconciliation design should follow several rules:

1. Upsert streamed usage rather than inserting a new request row for every event. Sequence numbers, event identifiers, or monotonic cumulative counters can make updates idempotent.
2. Preserve attempt-level consumption. A retried request should retain each attempt while exposing one logical request-level view.
3. Define whether updates are cumulative or incremental. Mixing those event types without an explicit marker can double-count usage.
4. Finalize asynchronous work only after terminal usage is available. Image, audio, or video generation may complete after the initial API response.
5. Represent partial outcomes explicitly. A request may produce valid text while media generation fails, or complete some batch items but not others.
6. Keep provider payloads associated with their attempts. This supports later investigation when normalized values or provider definitions change.

A finalized logical record can aggregate compatible quantities across attempts, but only within the same modality, unit, direction, and measurement definition. For example, input text tokens may be summed with input text tokens when their semantics match; they should not be added to audio seconds or image pixels.

Model Each Modality as a Unit-Aware Usage Component

Each usage component should identify what was measured, how it was measured, and where the value came from. A flexible component usually needs these properties:

• modality: text, image, audio, video, or a provider-defined extension;
• category: input, output, cached, or another explicit classification;
• quantity: the reported or calculated amount;
• unit: such as tokens, images, pixels, seconds, frames, or bytes;
• source: provider-reported, adapter-calculated, application-observed, or another defined origin;
• estimated: whether the quantity is an estimate;
• provider metric: the source field or metric name when useful for traceability;
• dimensions: optional details such as resolution, duration basis, or media format when they affect interpretation.

Do not require all providers to fill every component. Some may report text tokens but no media breakdown; others may provide duration or billable media units without physical dimensions. The normalized record should describe what is known without manufacturing missing detail.

Proposed JSON example

The following example is an illustrative design, not a Token Forge Cloud API contract:

``json { "schema_version": "1.0", "request_id": "req_01", "interaction_id": "run_42", "batch_id": null, "provider": "example-provider", "model": "example-multimodal-model", "created_at": "2026-09-23T10:00:00Z", "finalized_at": "2026-09-23T10:00:08Z", "status": "succeeded", "finalized": true, "attempts": [ { "attempt_id": "att_01", "provider_request_id": "provider_req_987", "status": "succeeded" } ], "components": [ { "modality": "text", "category": "input", "quantity": 1250, "unit": "tokens", "source": "provider_reported", "estimated": false }, { "modality": "image", "category": "input", "quantity": 2, "unit": "images", "source": "application_observed", "estimated": false }, { "modality": "audio", "category": "output", "quantity": 18.4, "unit": "seconds", "source": "provider_reported", "estimated": false } ], "pricing": { "currency": "USD", "calculated_cost": 0.00, "pricing_version": "example-rate-card-version", "rate_source": "internal-rate-catalog", "estimated": true }, "raw_provider_usage": { "preserved": true, "payload_reference": "usage-payload://provider_req_987" } } ``

In production, avoid using 0.00 as a placeholder for unknown cost. The example marks that amount as estimated, but an unknown value is normally better represented as null with an explicit reason.

Distinguish zero, null, absent, unsupported, and estimated

Downstream billing and analytics can produce misleading results if these states are treated as equivalent.

Representation	Recommended meaning	Example
0	The metric was measured and no usage occurred	No output audio was generated
null	The field applies, but its value is not yet known or unavailable	Final video duration is pending
Absent field	The field was not emitted under this schema or event type	An intermediate event omits pricing
unsupported	The adapter or provider does not supply the metric	No cached-image measurement is available
estimated: true	The value was calculated or inferred rather than directly reported	Audio duration estimated from observed media

A component can also include a reason code such as provider_not_reported, pending_finalization, or adapter_not_supported. This is clearer than forcing all unknown states into null.

Preserve input, output, cached, and provider-defined distinctions

Input and output should remain separate because they often have different operational and pricing implications. Cached usage should also be distinct where the provider reports it; it should not automatically be subtracted from input or treated as free consumption.

Provider-defined categories may be retained in an extension field when they do not map cleanly into the normalized model. The adapter can expose a normalized category for common analysis while preserving the source definition for auditability.

For multi-part messages, include optional part identifiers when analysts need to connect consumption with a particular text block, image, audio clip, or video asset. The request-level record can still remain singular while its components reference multiple parts.

Keep physical usage separate from cost

Consumption and price answer different questions. A physical usage component describes what happened; a pricing object explains how a monetary amount was derived.

When cost is known, record:

• the amount and currency;
• whether it is provider-reported, calculated, allocated, or estimated;
• the pricing version, rate-card identifier, or other traceable rate source;
• the calculation timestamp; and
• any relevant billing category that differs from the physical unit.

This distinction is important because provider prices can change while historical tokens, images, seconds, and frames remain the same. It also prevents a normalized usage quantity from being mistaken for the provider’s final invoice quantity.

Operational Uses of a Normalized Multimodal Record

A well-structured usage envelope can support several enterprise workflows without requiring unlike media to share one total.

Routing analysis: Platform teams can compare which models and providers handled particular modality mixes, request sizes, statuses, and retry patterns. The analysis should use comparable units and workload categories rather than a synthetic all-media token count.

Chargeback and showback: Application, tenant, project, and cost-center tags can connect request-level activity to organizational ownership. Attempt detail can separate useful workload consumption from failover or retry overhead.

Budgeting: Finance teams can retain physical consumption independently from pricing, then apply documented rate versions to model scenarios or reconcile calculated cost against provider billing.

Observability: Engineering teams can correlate modality composition with queueing, streaming, partial failures, and asynchronous completion. Usage records should complement operational traces rather than replace them.

Serving-layer optimization: Unit-aware telemetry can inform decisions involving caching, routing, batching, quantization, and GPU scheduling. The effect of those decisions remains workload- and deployment-dependent, but preserving clear usage semantics gives teams a better basis for evaluation.

Token Forge Cloud Private LLM Inference is designed around private deployment and serving-layer optimization for enterprise AI workloads, including caching, routing, batching, quantization, and GPU scheduling. Token Forge Cloud Managed Model APIs provides an API-first option for model access and usage data, with a path toward private deployment once workloads become predictable. The schema above offers architectural guidance and does not document the current API format or modality coverage of either product.

Buyer Evaluation Checklist

When evaluating a multimodal metering and normalization layer, ask how it handles the situations that create material integration and accounting differences:

• Provider adapters: Which source usage fields are mapped, preserved, estimated, or omitted? How are adapter changes versioned?
• Unit integrity: Does every quantity carry an explicit unit and modality, or are unlike measurements collapsed into a generic total?
• Lifecycle reconciliation: How are streams, retries, failover attempts, batches, partial failures, and asynchronous jobs finalized without duplicate logical records?
• Raw telemetry: Can authorized teams retain or reference the original provider usage payload alongside normalized values?
• Cost attribution: Are provider-reported, calculated, estimated, and allocated costs distinguishable? Can every calculated amount be traced to a currency and rate version?
• Schema extensibility: Can the design add new modalities, provider categories, and units without changing the meaning of historical records?
• Data semantics: Are zero, null, absent, unsupported, pending, and estimated values handled differently?
• Retention and access: Where are request metadata, cost tags, and raw payloads stored, for how long, and under which access policies?
• Deployment fit: Can the metering path work with managed model API access, self-deployed model serving, or a private inference control plane as required?
• Reconciliation: Can finance and platform teams compare normalized records with provider invoices while preserving known differences in billing definitions?

The best design is not the one that forces every provider into the same apparent number. It is the one that gives the organization one stable view of each logical request while retaining enough source detail to explain every component, update, attempt, and calculated cost.

Next Step

Contact Token Forge Cloud to discuss API access, private deployment, and LLM inference cost control.