CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-langfuse--langfuse-java

Java client for the Langfuse API providing access to observability and analytics features for LLM applications

Overview
Eval results
Files

media.mddocs/

Media

The Media API provides management of media records and presigned upload URLs for media files. This enables secure file uploads associated with traces and observations.

Capabilities

MediaClient

Client for managing media records and uploads.

/**
 * Get a media record
 *
 * @param mediaId Media ID
 * @param requestOptions Optional request configuration
 */
GetMediaResponse get(String mediaId);
GetMediaResponse get(String mediaId, RequestOptions requestOptions);

/**
 * Patch a media record
 * Update trace/observation associations or field
 *
 * @param mediaId Media ID
 * @param request Update data
 * @param requestOptions Optional request configuration
 */
void patch(String mediaId, PatchMediaBody request);
void patch(String mediaId, PatchMediaBody request, RequestOptions requestOptions);

/**
 * Get a presigned upload URL for a media record
 * Used for uploading media files to cloud storage
 *
 * @param request Media file specifications
 * @param requestOptions Optional request configuration
 */
GetMediaUploadUrlResponse getUploadUrl(GetMediaUploadUrlRequest request);
GetMediaUploadUrlResponse getUploadUrl(GetMediaUploadUrlRequest request, RequestOptions requestOptions);

Usage Examples:

import com.langfuse.client.LangfuseClient;
import com.langfuse.client.resources.media.types.*;

LangfuseClient client = LangfuseClient.builder()
    .url("https://cloud.langfuse.com")
    .credentials("pk-lf-...", "sk-lf-...")
    .build();

// Get a presigned upload URL
// Note: Staged builder requires traceId() -> contentType() -> contentLength() -> sha256Hash() -> field()
GetMediaUploadUrlRequest uploadRequest = GetMediaUploadUrlRequest.builder()
    .traceId("trace-123")  // Required first: trace ID
    .contentType(MediaContentType.IMAGE_PNG)  // Required second: content type
    .contentLength(1024000)  // Required third: content length in bytes
    .sha256Hash("abc123def456...")  // Required fourth: SHA-256 hash of file
    .field("input")  // Required fifth: field name (input, output, metadata)
    .observationId("obs-123")  // Optional: observation ID
    .build();

GetMediaUploadUrlResponse uploadUrl = client.media().getUploadUrl(uploadRequest);

System.out.println("Media ID: " + uploadUrl.getMediaId());
if (uploadUrl.getUploadUrl().isPresent()) {
    System.out.println("Upload URL: " + uploadUrl.getUploadUrl().get());
} else {
    System.out.println("File already uploaded");
}

// Upload file to the presigned URL (using your HTTP client)
// PUT request to uploadUrl.getUploadUrl() with file data

// Get media record
GetMediaResponse media = client.media().get(uploadUrl.getMediaId());
System.out.println("Content type: " + media.getContentType());
System.out.println("Content length: " + media.getContentLength());

// Update media associations
PatchMediaBody patchRequest = PatchMediaBody.builder()
    .observationId("obs-456")
    .field("output")
    .build();

client.media().patch(uploadUrl.getMediaId(), patchRequest);

Request Types

GetMediaUploadUrlRequest

/**
 * Request for presigned upload URL
 *
 * Staged Builder Pattern (required order):
 * 1. traceId(String) - Trace ID
 * 2. contentType(MediaContentType) - Media content type
 * 3. contentLength(int) - File size in bytes
 * 4. sha256Hash(String) - SHA-256 hash of the file
 * 5. field(String) - Field name: "input", "output", or "metadata"
 * 6. observationId(String) - Optional observation ID
 * 7. build() - Build the request
 */
public final class GetMediaUploadUrlRequest {
    String getTraceId();                   // Trace ID (required)
    MediaContentType getContentType();     // Media content type (required)
    int getContentLength();                // File size in bytes (required)
    String getSha256Hash();                // SHA-256 hash of file (required)
    String getField();                     // Field name (required): "input", "output", "metadata"
    Optional<String> getObservationId();   // Optional observation ID

    static TraceIdStage builder();         // Returns staged builder starting with traceId()
}

PatchMediaBody

/**
 * Request for patching media record
 */
public final class PatchMediaBody {
    Optional<String> getTraceId();         // Update trace association
    Optional<String> getObservationId();   // Update observation association
    Optional<String> getField();           // Update field association

    static Builder builder();
}

Response Types

GetMediaResponse

/**
 * Media record details
 */
public final class GetMediaResponse {
    String getId();
    MediaContentType getContentType();
    long getContentLength();
    String getUrl();            // Access URL for the media
    Optional<String> getUploadedAt();  // ISO 8601 timestamp

    static Builder builder();
}

GetMediaUploadUrlResponse

/**
 * Presigned upload URL response
 */
public final class GetMediaUploadUrlResponse {
    Optional<String> getUploadUrl();  // Presigned URL for upload (null if already uploaded)
    String getMediaId();              // Media record ID

    static Builder builder();
}

Enums

MediaContentType

/**
 * Supported media content types
 */
public enum MediaContentType {
    // Images
    IMAGE_PNG,           // image/png
    IMAGE_JPEG,          // image/jpeg
    IMAGE_JPG,           // image/jpg
    IMAGE_WEBP,          // image/webp
    IMAGE_GIF,           // image/gif
    IMAGE_SVG_XML,       // image/svg+xml
    IMAGE_TIFF,          // image/tiff
    IMAGE_BMP,           // image/bmp

    // Audio
    AUDIO_MPEG,          // audio/mpeg
    AUDIO_MP_3,          // audio/mp3
    AUDIO_WAV,           // audio/wav
    AUDIO_OGG,           // audio/ogg
    AUDIO_OGA,           // audio/oga
    AUDIO_AAC,           // audio/aac
    AUDIO_MP_4,          // audio/mp4
    AUDIO_FLAC,          // audio/flac

    // Video
    VIDEO_MP_4,          // video/mp4
    VIDEO_WEBM,          // video/webm

    // Text
    TEXT_PLAIN,          // text/plain
    TEXT_HTML,           // text/html
    TEXT_CSS,            // text/css
    TEXT_CSV,            // text/csv

    // Application
    APPLICATION_PDF,             // application/pdf
    APPLICATION_MSWORD,          // application/msword
    APPLICATION_MS_EXCEL,        // application/vnd.ms-excel
    APPLICATION_ZIP,             // application/zip
    APPLICATION_JSON,            // application/json
    APPLICATION_XML,             // application/xml
    APPLICATION_OCTET_STREAM     // application/octet-stream
}

Complete Media Upload Example

import com.langfuse.client.LangfuseClient;
import com.langfuse.client.resources.media.types.*;
import okhttp3.*;
import java.io.File;
import java.io.IOException;

public class MediaUploadExample {
    public static void main(String[] args) throws IOException {
        LangfuseClient client = LangfuseClient.builder()
            .url("https://cloud.langfuse.com")
            .credentials("pk-lf-...", "sk-lf-...")
            .build();

        // 1. Prepare file for upload
        File imageFile = new File("/path/to/image.png");
        long fileSize = imageFile.length();

        // Calculate SHA-256 hash of the file
        String sha256Hash = calculateSHA256(imageFile);  // Your hash calculation method

        // 2. Get presigned upload URL
        // Staged builder: traceId() -> contentType() -> contentLength() -> sha256Hash() -> field()
        GetMediaUploadUrlRequest uploadRequest = GetMediaUploadUrlRequest.builder()
            .traceId("trace-123")  // Required first
            .contentType(MediaContentType.IMAGE_PNG)  // Required second
            .contentLength((int) fileSize)  // Required third
            .sha256Hash(sha256Hash)  // Required fourth
            .field("user_upload")  // Required fifth
            .build();

        GetMediaUploadUrlResponse uploadResponse = client.media()
            .getUploadUrl(uploadRequest);

        String mediaId = uploadResponse.getMediaId();
        System.out.println("Media ID: " + mediaId);

        // 3. Upload file to presigned URL (if not already uploaded)
        if (uploadResponse.getUploadUrl().isPresent()) {
            String uploadUrl = uploadResponse.getUploadUrl().get();

            OkHttpClient httpClient = new OkHttpClient();

            RequestBody fileBody = RequestBody.create(
                imageFile,
                okhttp3.MediaType.parse("image/png")
            );

            Request uploadReq = new Request.Builder()
                .url(uploadUrl)
                .put(fileBody)
                .build();

            try (Response response = httpClient.newCall(uploadReq).execute()) {
                if (response.isSuccessful()) {
                    System.out.println("File uploaded successfully");
                } else {
                    System.err.println("Upload failed: " + response.code());
                }
            }
        } else {
            System.out.println("File already uploaded (duplicate detected)");
        }

        // 4. Retrieve media record
        GetMediaResponse media = client.media().get(mediaId);
        System.out.println("Media URL: " + media.getUrl());
        System.out.println("Content type: " + media.getContentType());
        System.out.println("Size: " + media.getContentLength() + " bytes");

        // 5. Update associations
        PatchMediaBody patchRequest = PatchMediaBody.builder()
            .observationId("obs-456")
            .field("visualization")
            .build();

        client.media().patch(mediaId, patchRequest);
        System.out.println("Updated media associations");

        // 6. Upload multiple files
        File[] files = {
            new File("/path/to/audio.mp3"),
            new File("/path/to/document.pdf"),
            new File("/path/to/video.mp4")
        };

        MediaContentType[] contentTypes = {
            MediaContentType.AUDIO_MPEG,
            MediaContentType.APPLICATION_PDF,
            MediaContentType.VIDEO_MP4
        };

        for (int i = 0; i < files.length; i++) {
            File file = files[i];
            MediaContentType contentType = contentTypes[i];
            String hash = calculateSHA256(file);

            GetMediaUploadUrlRequest req = GetMediaUploadUrlRequest.builder()
                .traceId("trace-123")  // Required first
                .contentType(contentType)  // Required second
                .contentLength((int) file.length())  // Required third
                .sha256Hash(hash)  // Required fourth
                .field("attachment_" + i)  // Required fifth
                .build();

            GetMediaUploadUrlResponse resp = client.media().getUploadUrl(req);

            // Upload file (implementation omitted for brevity)
            System.out.println("Created media record: " + resp.getMediaId());
        }
    }
}

Upload Workflow

  1. Request Upload URL: Call getUploadUrl() with content type and size
  2. Upload File: Use HTTP PUT to upload file to presigned URL
  3. Verify Upload: Optionally call get() to verify upload success
  4. Update Associations: Use patch() to update trace/observation links

Best Practices

  1. Content Type: Always specify correct MediaContentType
  2. File Size: Include accurate contentLength for validation
  3. Presigned URLs: Use URLs immediately - they expire after a short time
  4. HTTP Client: Use a robust HTTP client for file uploads
  5. Error Handling: Handle upload failures and retry logic
  6. Association: Link media to traces/observations via traceId/observationId
  7. Field Names: Use descriptive field names ("input", "output", "screenshot")
  8. Large Files: Consider chunked uploads for very large files

Use Cases

Image Upload

// Upload screenshot for observation
GetMediaUploadUrlRequest request = GetMediaUploadUrlRequest.builder()
    .traceId("trace-123")  // Required first
    .contentType(MediaContentType.IMAGE_PNG)  // Required second
    .contentLength((int) imageFile.length())  // Required third
    .sha256Hash(calculateSHA256(imageFile))  // Required fourth
    .field("screenshot")  // Required fifth
    .observationId("obs-123")  // Optional
    .build();

GetMediaUploadUrlResponse response = client.media().getUploadUrl(request);

Audio Upload

// Upload audio recording
GetMediaUploadUrlRequest request = GetMediaUploadUrlRequest.builder()
    .traceId("trace-123")  // Required first
    .contentType(MediaContentType.AUDIO_WAV)  // Required second
    .contentLength((int) audioFile.length())  // Required third
    .sha256Hash(calculateSHA256(audioFile))  // Required fourth
    .field("audio_input")  // Required fifth
    .build();

Document Upload

// Upload PDF document
GetMediaUploadUrlRequest request = GetMediaUploadUrlRequest.builder()
    .traceId("trace-123")  // Required first
    .contentType(MediaContentType.APPLICATION_PDF)  // Required second
    .contentLength((int) pdfFile.length())  // Required third
    .sha256Hash(calculateSHA256(pdfFile))  // Required fourth
    .field("document")  // Required fifth
    .build();

Related Documentation

  • Traces and Observations - Associating media with traces
  • Ingestion API - Creating traces and observations

Install with Tessl CLI

npx tessl i tessl/maven-com-langfuse--langfuse-java

docs

client-configuration.md

comments-annotations.md

common-types.md

datasets.md

exceptions.md

health.md

index.md

ingestion.md

media.md

metrics.md

models.md

pagination.md

projects-organizations.md

prompts.md

scim.md

scores.md

sessions.md

traces-observations.md

tile.json