TypeScript SDK

The frametail npm package is the supported TypeScript client. It wraps the HTTP API with typed helpers and optional automatic tracing when you use fal.ai.

Installation

pnpm add frametail @fal-ai/client

@fal-ai/client is optional but recommended when you want traced fal calls.

Configuration

Set defaults once in your service bootstrap:

import { setDefaultConfig } from 'frametail'

setDefaultConfig({
  apiKey: process.env.FRAMETAIL_API_KEY!,
  projectKey: process.env.FRAMETAIL_PROJECT_KEY!,
  // baseUrl: 'https://api.frametail.com', // optional override
})

You can override apiKey or projectKey per call when needed.

Resources

Each resource exposes static methods (create, list, get, …) and instance methods on returned objects.

Refer to inline TypeScript types in the package for the exact argument shapes.

fal.ai tracing

Wrap your fal client for automatic span export:

import { FrametailClient } from 'frametail'
import * as fal from '@fal-ai/client'

const frametail = new FrametailClient({
  apiKey: process.env.FRAMETAIL_API_KEY!,
  projectKey: process.env.FRAMETAIL_PROJECT_KEY!,
  enableTracing: true,
})

await frametail.initializeFalClient(fal)
const tracedFal = frametail.getFalClient()
await tracedFal.run('model-id', { prompt: 'Hello' })

AI SDK tracing

Wrap generateImage and experimental_generateVideo from the Vercel AI SDK for automatic span export:

import { FrametailClient, wrapGenerateVideo, wrapGenerateImage } from 'frametail'
import { generateImage, experimental_generateVideo as generateVideo } from 'ai'
import { fal } from '@ai-sdk/fal'

const frametail = new FrametailClient({
  apiKey: process.env.FRAMETAIL_API_KEY!,
  projectKey: process.env.FRAMETAIL_PROJECT_KEY!,
  enableTracing: true,
})

const tracedGenerateImage = frametail.wrapGenerateImage(generateImage)
const tracedGenerateVideo = frametail.wrapGenerateVideo(generateVideo)

const { image } = await tracedGenerateImage({
  model: fal.image('fal-ai/flux/dev'),
  prompt: 'A cat wearing sunglasses',
  aspectRatio: '1:1',
})

const { video } = await tracedGenerateVideo({
  model: fal.video('luma-dream-machine/ray-2'),
  prompt: 'A cat walking on a treadmill',
  aspectRatio: '16:9',
  providerOptions: { fal: { pollTimeoutMs: 600_000 } },
})

Image spans use type compose with image.url and output.kind: image. Video spans use video.generate with video.url. Both set gen_ai.request.model, gen_ai.system, and video.prompt. Binary data (base64, uint8Array) is stripped from exported outputs.

OpenTelemetry conventions

Across fal, AI SDK, and OpenRouter wrappers, Frametail uses a consistent attribute model:

• W3C Trace Context — 32-byte trace ids, 8-byte span ids, optional traceparent on ingest HTTP requests
• Span status — UNSET, OK, ERROR
• Gen AI semantic conventions — gen_ai.request.model, gen_ai.system, plus provider-specific blobs (falSpanData, openRouterSpanData, …)
• Video fields — video.prompt, video.url, video.model, video.job_id (and frametail.job_id where applicable)

Manual helpers (startTrace, runTraced, buildTraceparent, propagationHeaders) follow the same id format. See Tracing for operational guidance.

Manual tracing helpers

For code paths that do not use fal directly, you can use span helpers such as startTrace, startSpan, endSpan, endTrace, or the traced() wrapper. These forward to the configured exporter (by default, the Frametail API for your project).

Custom exporters

Advanced deployments can supply a traceExporter to send spans and traces to your own pipeline instead of, or in addition to, Frametail ingestion.

Related

• HTTP API overview for raw REST usage.
• fal.ai integration for product-level guidance.
• AI SDK integration for Vercel AI SDK image and video providers.