feat(fal): surface billed cost as result.usage.unitsBilled (#723)

* feat(fal): surface billed cost as result.usage.unitsBilled

The fal adapters discarded fal's response headers, so the actual billed
cost of a generation was unrecoverable through the SDK. fal returns the
real billed quantity in the `x-fal-billable-units` header on the result
fetch; this surfaces it as `result.usage.unitsBilled` so consumers can
compute exact media-generation cost without wrapping `fetch` themselves.

- `TokenUsage` gains an optional `unitsBilled` (a bare count of priced
  units, sibling to `durationSeconds`; the unit name itself is provider
  -defined and looked up via the pricing API, not carried here).
- A `config.fetch` wrapper reads `x-fal-billable-units` off every fal
  response, keyed by `x-fal-request-id` (the same value the client
  surfaces as `Result.requestId`), so the adapter's lookup always
  matches the fetch the units came from. `config.fetch` is used rather
  than `responseHandler` because the queue ops clobber a global handler.
- All five fal media adapters (image, audio, video, speech,
  transcription) populate `result.usage.unitsBilled` when fal reports it.
- `VideoUrlResult` gains a `usage` slot; `getVideoJobStatus` now emits
  the `video:usage` event and returns `usage` on completion.

Closes #722

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* ci: apply automated fixes

* feat(examples): show fal unitsBilled in ts-react-media

Surface the new `result.usage.unitsBilled` in the media example so the
billed quantity is visible after a generation — a caption under each
generated image/video ("Billed N fal units"). Verified against the live
fal API: a fal-ai/flux/schnell generation reports unitsBilled: 1.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(examples): use a runtime-valid size for grok-imagine-image

fal's generated `size`/`resolution` type for `xai/grok-imagine-image`
offers `16:9_1K` / `16:9_4K`, but the live API rejects those resolutions
("Input should be '1k' or '2k'") — the vendor enum is out of sync with
the API. `'16:9_4K'` therefore type-checked but 422'd at runtime. Pass
`aspect_ratio: '16:9'` via modelOptions instead and let the endpoint
default the resolution; verified against the live fal API.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(fal): inject fetch instead of overriding the global

Address CodeRabbit + review feedback: dependency-inject the underlying
fetch rather than mutating globals.

- `createBillingFetch(baseFetch = globalThis.fetch)` now takes the fetch to
  delegate to, and `FalClientConfig` gains an optional `fetch` override that
  `configureFalClient` wraps for usage capture.
- The E2E route passes a per-request redirecting `fetch` via
  `falImage(model, { fetch })` instead of swapping `globalThis.fetch` —
  removing the concurrency race CodeRabbit flagged (no global mutation, no
  try/finally restore).
- `billing.test.ts` injects a fake fetch directly instead of
  `vi.stubGlobal('fetch')`.
- Changeset: reword "billed cost" → "billed units" to match the surfaced
  `usage.unitsBilled` field.

Verified: full `pnpm test:pr` green, fal E2E spec green, and a live
fal-ai/flux/schnell call still reports unitsBilled via the default
(no-override) path.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* ci: apply automated fixes

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: 3 people

.changeset/fal-billable-units-usage.md

@@ -0,0 +1,11 @@
+---
+'@tanstack/ai-event-client': minor
+'@tanstack/ai-fal': minor
+'@tanstack/ai': minor
+---
+
+Surface fal's billed units as `result.usage`. The fal adapters now read fal's `x-fal-billable-units` response header off the result fetch and expose the billed quantity (`usage.unitsBilled`) on the generation result, so consumers can compute exact media-generation cost without wrapping `fetch` themselves.
+
+- `TokenUsage` gains an optional `unitsBilled` field for usage-based (non-token) billing, denominated in the provider's priced unit.
+- `falImage`, `falAudio`, `falVideo`, `falSpeech`, and `falTranscription` populate `result.usage.unitsBilled` when fal reports it.
+- `VideoUrlResult` gains an optional `usage` slot; `getVideoJobStatus` now emits the `video:usage` event and returns `usage` when the completed result reports billed units.

docs/config.json

@@ -242,17 +242,20 @@
         {
           "label": "Audio Generation",
           "to": "media/audio-generation",
-          "addedAt": "2026-04-23"
+          "addedAt": "2026-04-23",
+          "updatedAt": "2026-06-08"
         },
         {
           "label": "Image Generation",
           "to": "media/image-generation",
-          "addedAt": "2026-04-15"
+          "addedAt": "2026-04-15",
+          "updatedAt": "2026-06-08"
         },
         {
           "label": "Video Generation",
           "to": "media/video-generation",
-          "addedAt": "2026-04-15"
+          "addedAt": "2026-04-15",
+          "updatedAt": "2026-06-08"
         },
         {
           "label": "Generation Hooks",

docs/media/audio-generation.md

@@ -118,7 +118,10 @@ interface AudioGenerationResult {
     duration?: number
   }
   // Canonical TokenUsage (same shape as chat), present when the provider
-  // reports it (e.g. Gemini Lyria via generateContent).
+  // reports it (e.g. Gemini Lyria via generateContent). Usage-billed providers
+  // (fal) instead surface `usage.unitsBilled` — the real billed quantity read
+  // from fal's `x-fal-billable-units` result header. Multiply by the endpoint's
+  // unit price (fal pricing API) for the exact cost.
   usage?: TokenUsage
 }
 ```

docs/media/image-generation.md

@@ -203,7 +203,8 @@ interface ImageGenerationResult {
   images: GeneratedImage[] // Array of generated images
   // Canonical TokenUsage (same shape as chat). Token-billed models also surface
   // a per-modality breakdown on `promptTokensDetails` (e.g. text vs image input
-  // tokens for gpt-image-1).
+  // tokens for gpt-image-1). Usage-billed providers (fal) instead surface
+  // `usage.unitsBilled` — see the note below.
   usage?: TokenUsage
 }
 
@@ -214,6 +215,25 @@ interface GeneratedImage {
 }
 ```
 
+> **Cost tracking (fal):** fal bills by usage-based units rather than tokens. The
+> fal image adapter surfaces the real billed quantity as `usage.unitsBilled`
+> (read from fal's `x-fal-billable-units` result header). Multiply it by the
+> endpoint's unit price from
+> `GET https://api.fal.ai/v1/models/pricing?endpoint_id=…` for the exact cost —
+> no `fetch` interceptor needed.
+
+```typescript
+const result = await generateImage({
+  adapter: falImage('fal-ai/flux/dev'),
+  prompt: 'a serene mountain lake',
+})
+
+if (result.usage?.unitsBilled != null) {
+  const cost = result.usage.unitsBilled * unitPrice // unitPrice from fal pricing API
+  console.log(`Billed ${result.usage.unitsBilled} units (~$${cost})`)
+}
+```
+
 ## Model Availability
 
 ### OpenAI Models

docs/media/video-generation.md

@@ -408,7 +408,7 @@ const { jobId } = await generateVideo({
 
 ## Response Types
 
-> **Note:** The interfaces below are the underlying adapter-level types. The `getVideoJobStatus()` helper returns a single merged object, `{ status, progress?, url?, error? }` — it does not return `jobId` or `expiresAt`.
+> **Note:** The interfaces below are the underlying adapter-level types. The `getVideoJobStatus()` helper returns a single merged object, `{ status, progress?, url?, error?, usage? }` — it does not return `jobId` or `expiresAt`.
 
 ### VideoJobResult (from create)
 
@@ -437,9 +437,20 @@ interface VideoUrlResult {
   jobId: string
   url: string        // URL to download/stream the video
   expiresAt?: Date   // When the URL expires
+  // Usage for the completed generation, when the adapter reports it. fal
+  // populates `usage.unitsBilled` from its `x-fal-billable-units` header.
+  usage?: TokenUsage
 }
 ```
 
+> **Cost tracking (fal):** fal bills media generation by usage-based units
+> rather than tokens. The fal adapters surface the real billed quantity as
+> `usage.unitsBilled` (denominated in the endpoint's priced unit). Combine it
+> with the endpoint's unit price from
+> `GET https://api.fal.ai/v1/models/pricing?endpoint_id=…` to compute the exact
+> cost (`unitsBilled * unitPrice`). The same `usage.unitsBilled` is surfaced
+> on image, audio, speech, and transcription results.
+
 ## Model Variants
 
 | Model | Description | Use Case |

examples/ts-react-media/src/components/ImageGenerator.tsx

@@ -209,13 +209,24 @@ export default function ImageGenerator({
                 {modelResult.status === 'success' &&
                   modelResult.result &&
                   modelResult.result.images.length > 0 && (
-                    <div className="rounded-lg overflow-hidden border border-gray-700">
-                      <img
-                        src={getImageSrc(modelResult.result.images[0]!)}
-                        alt={`Generated by ${model?.name ?? modelId}`}
-                        className="w-full h-auto"
-                      />
-                    </div>
+                    <>
+                      <div className="rounded-lg overflow-hidden border border-gray-700">
+                        <img
+                          src={getImageSrc(modelResult.result.images[0]!)}
+                          alt={`Generated by ${model?.name ?? modelId}`}
+                          className="w-full h-auto"
+                        />
+                      </div>
+                      {modelResult.result.usage?.unitsBilled != null && (
+                        <p className="text-xs text-gray-500">
+                          Billed {modelResult.result.usage.unitsBilled} fal unit
+                          {modelResult.result.usage.unitsBilled === 1
+                            ? ''
+                            : 's'}{' '}
+                          — multiply by the endpoint unit price for USD cost
+                        </p>
+                      )}
+                    </>
                   )}
               </div>
             )

examples/ts-react-media/src/components/VideoGenerator.tsx

@@ -20,7 +20,7 @@ type JobState =
       model: string
       progress?: number | undefined
     }
-  | { status: 'completed'; url: string }
+  | { status: 'completed'; url: string; unitsBilled?: number }
   | { status: 'error'; message: string }
 
 interface VideoGeneratorProps {
@@ -95,7 +95,11 @@ export default function VideoGenerator({
 
         setJobStates((prev) => ({
           ...prev,
-          [model]: { status: 'completed', url: url },
+          [model]: {
+            status: 'completed',
+            url: url,
+            unitsBilled: urlResult.usage?.unitsBilled,
+          },
         }))
       } else if (status.status === 'processing') {
         setJobStates((prev) => ({
@@ -387,15 +391,24 @@ export default function VideoGenerator({
                   </div>
                 )}
                 {state.status === 'completed' && (
-                  <div className="rounded-lg overflow-hidden border border-gray-700">
-                    <video
-                      src={state.url}
-                      controls
-                      autoPlay
-                      loop
-                      className="w-full h-auto"
-                    />
-                  </div>
+                  <>
+                    <div className="rounded-lg overflow-hidden border border-gray-700">
+                      <video
+                        src={state.url}
+                        controls
+                        autoPlay
+                        loop
+                        className="w-full h-auto"
+                      />
+                    </div>
+                    {state.unitsBilled != null && (
+                      <p className="text-xs text-gray-500">
+                        Billed {state.unitsBilled} fal unit
+                        {state.unitsBilled === 1 ? '' : 's'} — multiply by the
+                        endpoint unit price for USD cost
+                      </p>
+                    )}
+                  </>
                 )}
               </div>
             )

examples/ts-react-media/src/lib/server-functions.ts

@@ -29,11 +29,17 @@ export const generateImageFn = createServerFn({ method: 'POST' })
         })
       }
       case 'xai/grok-imagine-image': {
+        // NOTE: fal's generated `size` type for this model only offers
+        // `16:9_1K` / `16:9_4K`, but the live API rejects those resolutions
+        // ("Input should be '1k' or '2k'") — fal's published enum is out of
+        // sync with its API, so `'16:9_4K'` type-checks yet 422s at runtime.
+        // Pass aspect_ratio via modelOptions and let the endpoint pick its
+        // default resolution, which both type-checks and works at runtime.
         return generateImage({
           adapter: falImage('xai/grok-imagine-image'),
           prompt: data.prompt,
           numberOfImages: 1,
-          size: '16:9_4K',
+          modelOptions: { aspect_ratio: '16:9' },
         })
       }
       case 'fal-ai/flux-2/klein/9b': {

packages/ai-event-client/src/index.ts

@@ -223,6 +223,18 @@ export interface TokenUsage<TProviderDetails = ProviderUsageDetails> {
   completionTokensDetails?: CompletionTokensDetails
   /** Duration in seconds for duration-based billing (e.g., Whisper transcription) */
   durationSeconds?: number
+  /**
+   * Number of priced units actually billed, for usage-based (non-token) billing.
+   * This is a bare count, not a cost and not a unit name — the unit itself
+   * (megapixels, seconds, images, …) is provider-defined and not carried here;
+   * providers typically expose it via a separate pricing API. Surfaced for media
+   * generation, where there are no tokens: fal returns this count in its
+   * `x-fal-billable-units` response header. Multiply by the unit price to get the
+   * exact cost (`unitsBilled * unitPrice`). The unit-priced analogue of
+   * `durationSeconds` (the time-priced case); both are quantities, distinct from
+   * the monetary `cost` / `costDetails`.
+   */
+  unitsBilled?: number
   /** Provider-specific usage details not covered by standard fields */
   providerUsageDetails?: TProviderDetails
   /** Provider-reported cost for the request, when available. */

packages/ai-fal/src/adapters/audio.ts

@@ -1,8 +1,10 @@
 import { fal } from '@fal-ai/client'
 import { BaseAudioAdapter } from '@tanstack/ai/adapters'
 import {
+  buildFalUsage,
   configureFalClient,
   deriveAudioContentType,
+  takeBillableUnits,
   generateId as utilGenerateId,
 } from '../utils'
 import type { OutputType, Result } from '@fal-ai/client'
@@ -133,13 +135,16 @@ export class FalAudioAdapter<TModel extends FalModel> extends BaseAudioAdapter<
       throw new Error('Audio URL not found in fal audio generation response')
     }
 
+    const usage = buildFalUsage(takeBillableUnits(response.requestId))
+
     return {
       id: response.requestId || this.generateId(),
       model: this.model,
       audio: {
         url: audioUrl,
         contentType: deriveAudioContentType(contentType, audioUrl),
       },
+      ...(usage ? { usage } : {}),
     }
   }
 }