0
# Media
1

2
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.
3

4
## Capabilities
5

6
### MediaClient
7

8
Client for managing media records and uploads.
9

10
```java { .api }
11
/**
12
 * Get a media record
13
 *
14
 * @param mediaId Media ID
15
 * @param requestOptions Optional request configuration
16
 */
17
GetMediaResponse get(String mediaId);
18
GetMediaResponse get(String mediaId, RequestOptions requestOptions);
19

20
/**
21
 * Patch a media record
22
 * Update trace/observation associations or field
23
 *
24
 * @param mediaId Media ID
25
 * @param request Update data
26
 * @param requestOptions Optional request configuration
27
 */
28
void patch(String mediaId, PatchMediaBody request);
29
void patch(String mediaId, PatchMediaBody request, RequestOptions requestOptions);
30

31
/**
32
 * Get a presigned upload URL for a media record
33
 * Used for uploading media files to cloud storage
34
 *
35
 * @param request Media file specifications
36
 * @param requestOptions Optional request configuration
37
 */
38
GetMediaUploadUrlResponse getUploadUrl(GetMediaUploadUrlRequest request);
39
GetMediaUploadUrlResponse getUploadUrl(GetMediaUploadUrlRequest request, RequestOptions requestOptions);
40
```
41

42
**Usage Examples:**
43

44
```java
45
import com.langfuse.client.LangfuseClient;
46
import com.langfuse.client.resources.media.types.*;
47

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

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

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

66
System.out.println("Media ID: " + uploadUrl.getMediaId());
67
if (uploadUrl.getUploadUrl().isPresent()) {
68
    System.out.println("Upload URL: " + uploadUrl.getUploadUrl().get());
69
} else {
70
    System.out.println("File already uploaded");
71
}
72

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

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

81
// Update media associations
82
PatchMediaBody patchRequest = PatchMediaBody.builder()
83
    .observationId("obs-456")
84
    .field("output")
85
    .build();
86

87
client.media().patch(uploadUrl.getMediaId(), patchRequest);
88
```
89

90
## Request Types
91

92
### GetMediaUploadUrlRequest
93

94
```java { .api }
95
/**
96
 * Request for presigned upload URL
97
 *
98
 * Staged Builder Pattern (required order):
99
 * 1. traceId(String) - Trace ID
100
 * 2. contentType(MediaContentType) - Media content type
101
 * 3. contentLength(int) - File size in bytes
102
 * 4. sha256Hash(String) - SHA-256 hash of the file
103
 * 5. field(String) - Field name: "input", "output", or "metadata"
104
 * 6. observationId(String) - Optional observation ID
105
 * 7. build() - Build the request
106
 */
107
public final class GetMediaUploadUrlRequest {
108
    String getTraceId();                   // Trace ID (required)
109
    MediaContentType getContentType();     // Media content type (required)
110
    int getContentLength();                // File size in bytes (required)
111
    String getSha256Hash();                // SHA-256 hash of file (required)
112
    String getField();                     // Field name (required): "input", "output", "metadata"
113
    Optional<String> getObservationId();   // Optional observation ID
114

115
    static TraceIdStage builder();         // Returns staged builder starting with traceId()
116
}
117
```
118

119
### PatchMediaBody
120

121
```java { .api }
122
/**
123
 * Request for patching media record
124
 */
125
public final class PatchMediaBody {
126
    Optional<String> getTraceId();         // Update trace association
127
    Optional<String> getObservationId();   // Update observation association
128
    Optional<String> getField();           // Update field association
129

130
    static Builder builder();
131
}
132
```
133

134
## Response Types
135

136
### GetMediaResponse
137

138
```java { .api }
139
/**
140
 * Media record details
141
 */
142
public final class GetMediaResponse {
143
    String getId();
144
    MediaContentType getContentType();
145
    long getContentLength();
146
    String getUrl();            // Access URL for the media
147
    Optional<String> getUploadedAt();  // ISO 8601 timestamp
148

149
    static Builder builder();
150
}
151
```
152

153
### GetMediaUploadUrlResponse
154

155
```java { .api }
156
/**
157
 * Presigned upload URL response
158
 */
159
public final class GetMediaUploadUrlResponse {
160
    Optional<String> getUploadUrl();  // Presigned URL for upload (null if already uploaded)
161
    String getMediaId();              // Media record ID
162

163
    static Builder builder();
164
}
165
```
166

167
## Enums
168

169
### MediaContentType
170

171
```java { .api }
172
/**
173
 * Supported media content types
174
 */
175
public enum MediaContentType {
176
    // Images
177
    IMAGE_PNG,           // image/png
178
    IMAGE_JPEG,          // image/jpeg
179
    IMAGE_JPG,           // image/jpg
180
    IMAGE_WEBP,          // image/webp
181
    IMAGE_GIF,           // image/gif
182
    IMAGE_SVG_XML,       // image/svg+xml
183
    IMAGE_TIFF,          // image/tiff
184
    IMAGE_BMP,           // image/bmp
185

186
    // Audio
187
    AUDIO_MPEG,          // audio/mpeg
188
    AUDIO_MP_3,          // audio/mp3
189
    AUDIO_WAV,           // audio/wav
190
    AUDIO_OGG,           // audio/ogg
191
    AUDIO_OGA,           // audio/oga
192
    AUDIO_AAC,           // audio/aac
193
    AUDIO_MP_4,          // audio/mp4
194
    AUDIO_FLAC,          // audio/flac
195

196
    // Video
197
    VIDEO_MP_4,          // video/mp4
198
    VIDEO_WEBM,          // video/webm
199

200
    // Text
201
    TEXT_PLAIN,          // text/plain
202
    TEXT_HTML,           // text/html
203
    TEXT_CSS,            // text/css
204
    TEXT_CSV,            // text/csv
205

206
    // Application
207
    APPLICATION_PDF,             // application/pdf
208
    APPLICATION_MSWORD,          // application/msword
209
    APPLICATION_MS_EXCEL,        // application/vnd.ms-excel
210
    APPLICATION_ZIP,             // application/zip
211
    APPLICATION_JSON,            // application/json
212
    APPLICATION_XML,             // application/xml
213
    APPLICATION_OCTET_STREAM     // application/octet-stream
214
}
215
```
216

217
## Complete Media Upload Example
218

219
```java
220
import com.langfuse.client.LangfuseClient;
221
import com.langfuse.client.resources.media.types.*;
222
import okhttp3.*;
223
import java.io.File;
224
import java.io.IOException;
225

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

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

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

240
        // 2. Get presigned upload URL
241
        // Staged builder: traceId() -> contentType() -> contentLength() -> sha256Hash() -> field()
242
        GetMediaUploadUrlRequest uploadRequest = GetMediaUploadUrlRequest.builder()
243
            .traceId("trace-123")  // Required first
244
            .contentType(MediaContentType.IMAGE_PNG)  // Required second
245
            .contentLength((int) fileSize)  // Required third
246
            .sha256Hash(sha256Hash)  // Required fourth
247
            .field("user_upload")  // Required fifth
248
            .build();
249

250
        GetMediaUploadUrlResponse uploadResponse = client.media()
251
            .getUploadUrl(uploadRequest);
252

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

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

260
            OkHttpClient httpClient = new OkHttpClient();
261

262
            RequestBody fileBody = RequestBody.create(
263
                imageFile,
264
                okhttp3.MediaType.parse("image/png")
265
            );
266

267
            Request uploadReq = new Request.Builder()
268
                .url(uploadUrl)
269
                .put(fileBody)
270
                .build();
271

272
            try (Response response = httpClient.newCall(uploadReq).execute()) {
273
                if (response.isSuccessful()) {
274
                    System.out.println("File uploaded successfully");
275
                } else {
276
                    System.err.println("Upload failed: " + response.code());
277
                }
278
            }
279
        } else {
280
            System.out.println("File already uploaded (duplicate detected)");
281
        }
282

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

289
        // 5. Update associations
290
        PatchMediaBody patchRequest = PatchMediaBody.builder()
291
            .observationId("obs-456")
292
            .field("visualization")
293
            .build();
294

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

298
        // 6. Upload multiple files
299
        File[] files = {
300
            new File("/path/to/audio.mp3"),
301
            new File("/path/to/document.pdf"),
302
            new File("/path/to/video.mp4")
303
        };
304

305
        MediaContentType[] contentTypes = {
306
            MediaContentType.AUDIO_MPEG,
307
            MediaContentType.APPLICATION_PDF,
308
            MediaContentType.VIDEO_MP4
309
        };
310

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

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

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

326
            // Upload file (implementation omitted for brevity)
327
            System.out.println("Created media record: " + resp.getMediaId());
328
        }
329
    }
330
}
331
```
332

333
## Upload Workflow
334

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

340
## Best Practices
341

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

351
## Use Cases
352

353
### Image Upload
354

355
```java
356
// Upload screenshot for observation
357
GetMediaUploadUrlRequest request = GetMediaUploadUrlRequest.builder()
358
    .traceId("trace-123")  // Required first
359
    .contentType(MediaContentType.IMAGE_PNG)  // Required second
360
    .contentLength((int) imageFile.length())  // Required third
361
    .sha256Hash(calculateSHA256(imageFile))  // Required fourth
362
    .field("screenshot")  // Required fifth
363
    .observationId("obs-123")  // Optional
364
    .build();
365

366
GetMediaUploadUrlResponse response = client.media().getUploadUrl(request);
367
```
368

369
### Audio Upload
370

371
```java
372
// Upload audio recording
373
GetMediaUploadUrlRequest request = GetMediaUploadUrlRequest.builder()
374
    .traceId("trace-123")  // Required first
375
    .contentType(MediaContentType.AUDIO_WAV)  // Required second
376
    .contentLength((int) audioFile.length())  // Required third
377
    .sha256Hash(calculateSHA256(audioFile))  // Required fourth
378
    .field("audio_input")  // Required fifth
379
    .build();
380
```
381

382
### Document Upload
383

384
```java
385
// Upload PDF document
386
GetMediaUploadUrlRequest request = GetMediaUploadUrlRequest.builder()
387
    .traceId("trace-123")  // Required first
388
    .contentType(MediaContentType.APPLICATION_PDF)  // Required second
389
    .contentLength((int) pdfFile.length())  // Required third
390
    .sha256Hash(calculateSHA256(pdfFile))  // Required fourth
391
    .field("document")  // Required fifth
392
    .build();
393
```
394

395
## Related Documentation
396

397
- [Traces and Observations](./traces-observations.md) - Associating media with traces
398
- [Ingestion API](./ingestion.md) - Creating traces and observations
399