Langfuse JS/TS SDKs
    Preparing search index...

    Class LangfuseMediaReference

    A resolved reference to a media record stored in Langfuse.

    Returned in place of media reference strings when fetching dataset items via langfuse.dataset.get. It holds the media metadata and a signed download URL, and exposes helpers to fetch the content in the formats commonly expected by LLM providers.

    The signed url is short-lived. Fetch the content promptly, or re-fetch the dataset item if LangfuseMediaReference.isUrlExpired returns true.

    const dataset = await langfuse.dataset.get("visual-qa");

    for (const item of dataset.items) {
      const image = item.input.image as LangfuseMediaReference;

      // OpenAI: { type: "input_image", image_url: await image.fetchDataUri() }
      // Anthropic: { source: { type: "base64", media_type: image.contentType, data: await image.fetchBase64() } }
      // Vercel AI SDK: { type: "image", image: await image.fetchBytes(), mediaType: image.contentType }
    }

    Implements

    Index

    Constructors

    constructor

    Properties

    contentLength? contentType mediaId referenceString url urlExpiry?

    Methods

    fetchBase64 fetchBytes fetchDataUri isUrlExpired toJSON

    Constructors

    Properties

    contentLength?: number

    The size of the media record in bytes

    contentType: string

    The MIME type of the media record

    mediaId: string

    The unique Langfuse identifier of the media record

    referenceString: string

    The original @@@langfuseMedia:…@@@ reference string. Used to losslessly round-trip a resolved reference back through the API / tracing when a fetched dataset item is re-used.

    url: string

    The signed download URL of the media record

    urlExpiry?: string

    The expiry date and time (ISO 8601) of the signed download URL

    Methods

    • Fetches the media over the network and returns raw base64 (no data URI prefix).

      Useful for Anthropic ({ source: { type: "base64", media_type: media.contentType, data: await media.fetchBase64() } }) or LangChain ({ type: "image", base64: await media.fetchBase64(), mime_type: media.contentType }).

      Returns Promise<string>

      The media content as a base64 string

      If the download fails

    • Fetches the media content from the signed URL over the network.

      Useful for local evaluators / image libraries, manual base64 conversion, or the Vercel AI SDK ({ type: "image", image: await media.fetchBytes() }).

      Returns Promise<Uint8Array<ArrayBufferLike>>

      The media content as raw bytes

      If the download fails

    • Fetches the media over the network and returns a data:<contentType>;base64,... URI.

      Useful for OpenAI ({ type: "input_image", image_url: await media.fetchDataUri() }).

      Returns Promise<string>

      The media content as a base64 data URI

      If the download fails

    • Returns whether the signed download URL is expired or near expiry.

      Parameters

      • OptionalthresholdSeconds: number

        Treat the URL as expired this many seconds before its actual expiry to account for clock skew and download time (default: 60).

      Returns boolean

      true if the URL is expired or within the threshold of expiry. If the expiry is unknown or unparseable, returns false.

    • Serializes to the original @@@langfuseMedia:…@@@ reference string.

      This makes resolved references round-trip losslessly through anything that serializes with JSON.stringify — the dataset item API, experiment/trace span attributes — so a re-used item links back to its media instead of persisting a JSON object with a soon-to-expire signed URL.

      Returns string

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods