This document provides comprehensive documentation for the Lilith Media Service Asset Management API, including asset upload, storage, retrieval, processing, and version management.
Overview#
The Asset Management API provides:
- Asset Upload: Direct upload, presigned URLs, and multipart upload for large files
- Asset Storage: S3-backed storage with lifecycle policies and CDN integration
- Asset Retrieval: Download URLs, streaming URLs, and CDN delivery
- Processing: Transcoding, thumbnails, and metadata extraction
- Version Management: Asset variants and version history
Table of Contents#
- Asset Types
- Upload Operations
- Asset Operations
- Download & Streaming
- Processing Jobs
- Version Management
- Error Handling
Asset Types#
Asset Object#
{
"id": "asset-abc123",
"filename": "meditation-audio.mp3",
"original_filename": "Morning Meditation.mp3",
"title": "Morning Meditation Guide",
"description": "A calming 10-minute morning meditation",
"type": "audio",
"mime_type": "audio/mpeg",
"file_size": 15728640,
"width": null,
"height": null,
"aspect_ratio": null,
"duration_ms": 600000,
"status": "ready",
"is_public": true,
"checksum": "sha256:a1b2c3d4e5f6...",
"public_url": "https://cdn.lilith.app/media/asset-abc123/meditation-audio.mp3",
"cdn_url": "https://d123.cloudfront.net/media/asset-abc123/meditation-audio.mp3",
"variants": {
"thumbnail": {
"url": "https://cdn.lilith.app/media/asset-abc123/thumb.jpg",
"width": 300,
"height": 300
}
},
"metadata": {
"codec": "mp3",
"bitrate": 320000,
"sampleRate": 44100,
"channels": 2
},
"tags": ["meditation", "morning", "relaxation"],
"view_count": 1250,
"download_count": 340,
"created_at": "2024-01-01T00:00:00.000Z",
"updated_at": "2024-01-01T00:00:00.000Z"
}
Asset Type Enum#
| Type | Description |
|---|---|
image |
Images (JPEG, PNG, WebP, GIF, etc.) |
video |
Video files (MP4, WebM, MOV, etc.) |
audio |
Audio files (MP3, AAC, WAV, FLAC, etc.) |
document |
Documents (PDF, text, spreadsheets) |
model_3d |
3D models (GLTF, GLB, OBJ) |
archive |
Archives (ZIP, RAR, TAR) |
other |
Other file types |
Asset Status Enum#
| Status | Description |
|---|---|
uploading |
Upload in progress |
uploaded |
Upload complete, pending processing |
processing |
Processing in progress |
ready |
Asset ready for use |
failed |
Processing or upload failed |
deleted |
Soft deleted |
Variant Types#
| Type | Description |
|---|---|
original |
Original uploaded file |
thumbnail |
Small preview image |
preview |
Preview (GIF, video clip) |
web_optimized |
Optimized for web delivery |
mobile |
Optimized for mobile devices |
hls |
HLS streaming package |
dash |
DASH streaming package |
transcode |
Transcoded version |
compressed |
Compressed version |
watermarked |
Watermarked version |
Upload Operations#
Direct Upload#
Upload an asset directly with file data.
Endpoint: POST /v1/assets
Content-Type: multipart/form-data or application/json
Multipart Form Upload#
| Field | Type | Required | Description |
|---|---|---|---|
file |
file | Yes | The file to upload |
title |
string | No | Asset title |
description |
string | No | Asset description |
tags |
string | No | Comma-separated tags |
is_public |
boolean | No | Whether asset is public |
owner_id |
string | No | Owner user ID |
content_id |
string | No | Associated content ID |
metadata |
JSON string | No | Custom metadata |
Request:
curl -X POST "https://api.lilith.app/v1/assets" \
-H "Authorization: Bearer <access_token>" \
-F "file=@meditation.mp3" \
-F "title=Morning Meditation" \
-F "tags=meditation,morning" \
-F "is_public=true"
JSON Upload (Base64)#
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
filename |
string | Yes | Original filename |
content_type |
string | No | MIME type |
file_data |
string | No | Base64-encoded file data |
title |
string | No | Asset title |
description |
string | No | Asset description |
tags |
string[] | No | Tags array |
is_public |
boolean | No | Whether asset is public |
owner_id |
string | No | Owner user ID |
content_id |
string | No | Associated content ID |
metadata |
object | No | Custom metadata |
Request:
curl -X POST "https://api.lilith.app/v1/assets" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"filename": "meditation.mp3",
"content_type": "audio/mpeg",
"file_data": "SGVsbG8gV29ybGQ=",
"title": "Morning Meditation",
"tags": ["meditation", "morning"],
"is_public": true
}'
Response (201 Created):
{
"success": true,
"asset_id": "asset-abc123",
"status": "ready",
"filename": "meditation-abc123.mp3",
"content_type": "audio/mpeg",
"file_size": 15728640,
"checksum": "sha256:a1b2c3d4e5f6...",
"width": null,
"height": null,
"duration_ms": 600000,
"storage_key": "media/asset-abc123/meditation.mp3",
"public_url": "https://cdn.lilith.app/media/asset-abc123/meditation.mp3",
"cdn_url": "https://d123.cloudfront.net/media/asset-abc123/meditation.mp3"
}
Presigned URL Upload#
Request a presigned URL for client-side upload.
Endpoint: POST /v1/assets
Request without file_data returns a presigned URL.
Request:
curl -X POST "https://api.lilith.app/v1/assets" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"filename": "large-video.mp4",
"content_type": "video/mp4",
"title": "Training Video"
}'
Response (200 OK):
{
"success": true,
"asset_id": "asset-xyz789",
"upload_url": "https://lilith-media.s3.amazonaws.com/media/asset-xyz789/large-video.mp4?X-Amz-Algorithm=...",
"expires_at": "2024-01-01T01:00:00.000Z",
"status": "pending"
}
Client Upload:
curl -X PUT "<upload_url>" \
-H "Content-Type: video/mp4" \
--data-binary @large-video.mp4
Confirm Presigned Upload#
Confirm a presigned URL upload is complete.
Endpoint: POST /v1/assets/:id/confirm
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
checksum |
string | No | File checksum for verification |
file_size |
number | No | Actual file size |
Request:
curl -X POST "https://api.lilith.app/v1/assets/asset-xyz789/confirm" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"checksum": "sha256:a1b2c3d4e5f6...",
"file_size": 524288000
}'
Response:
{
"success": true,
"asset": {
"id": "asset-xyz789",
"status": "uploaded",
"checksum": "sha256:a1b2c3d4e5f6..."
}
}
Multipart Upload#
For large files (>5MB), use multipart upload with presigned part URLs.
Initiate Multipart Upload#
Endpoint: POST /v1/assets/multipart
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
filename |
string | Yes | Original filename |
content_type |
string | Yes | MIME type |
file_size |
number | Yes | Total file size in bytes (min 5MB) |
part_size |
number | No | Size per part (default: calculated) |
title |
string | No | Asset title |
description |
string | No | Asset description |
tags |
string[] | No | Tags array |
is_public |
boolean | No | Whether asset is public |
owner_id |
string | No | Owner user ID |
content_id |
string | No | Associated content ID |
Request:
curl -X POST "https://api.lilith.app/v1/assets/multipart" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"filename": "4k-video.mp4",
"content_type": "video/mp4",
"file_size": 2147483648,
"title": "4K Training Video"
}'
Response (201 Created):
{
"asset_id": "asset-multi123",
"upload_id": "upload-abc123",
"storage_key": "media/asset-multi123/4k-video.mp4",
"part_size": 67108864,
"part_count": 32,
"parts": [
{
"partNumber": 1,
"url": "https://lilith-media.s3.amazonaws.com/...?partNumber=1&uploadId=...",
"expiresAt": "2024-01-01T02:00:00.000Z"
},
{
"partNumber": 2,
"url": "https://lilith-media.s3.amazonaws.com/...?partNumber=2&uploadId=...",
"expiresAt": "2024-01-01T02:00:00.000Z"
}
],
"expires_at": "2024-01-01T02:00:00.000Z"
}
Upload Parts#
Upload each part to its presigned URL:
curl -X PUT "<part_url>" \
-H "Content-Type: video/mp4" \
--data-binary @part1.bin
Save the ETag header from each response.
Complete Multipart Upload#
Endpoint: POST /v1/assets/:id/multipart/complete
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
upload_id |
string | Yes | Upload ID from initiation |
parts |
array | Yes | Array of uploaded parts |
parts[].part_number |
number | Yes | Part number |
parts[].etag |
string | Yes | ETag from part upload |
checksum |
string | No | Final file checksum |
Request:
curl -X POST "https://api.lilith.app/v1/assets/asset-multi123/multipart/complete" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"upload_id": "upload-abc123",
"parts": [
{ "part_number": 1, "etag": "\"abc123\"" },
{ "part_number": 2, "etag": "\"def456\"" }
],
"checksum": "sha256:final-checksum"
}'
Response:
{
"success": true,
"asset": {
"id": "asset-multi123",
"filename": "4k-video.mp4",
"status": "uploaded",
"checksum": "sha256:final-checksum",
"file_size": 2147483648,
"created_at": "2024-01-01T00:00:00.000Z"
}
}
Abort Multipart Upload#
Endpoint: DELETE /v1/assets/:id/multipart/:uploadId
Request:
curl -X DELETE "https://api.lilith.app/v1/assets/asset-multi123/multipart/upload-abc123" \
-H "Authorization: Bearer <access_token>"
Response: 204 No Content
Asset Operations#
Get Asset#
Endpoint: GET /v1/assets/:id
Request:
curl -X GET "https://api.lilith.app/v1/assets/asset-abc123" \
-H "Authorization: Bearer <access_token>"
Response:
{
"id": "asset-abc123",
"filename": "meditation-audio.mp3",
"original_filename": "Morning Meditation.mp3",
"title": "Morning Meditation Guide",
"description": "A calming 10-minute morning meditation",
"type": "audio",
"mime_type": "audio/mpeg",
"file_size": 15728640,
"width": null,
"height": null,
"aspect_ratio": null,
"duration_ms": 600000,
"status": "ready",
"is_public": true,
"checksum": "sha256:a1b2c3d4e5f6...",
"public_url": "https://cdn.lilith.app/media/asset-abc123/meditation-audio.mp3",
"cdn_url": "https://d123.cloudfront.net/media/asset-abc123/meditation-audio.mp3",
"variants": {
"thumbnail": {
"url": "https://cdn.lilith.app/media/asset-abc123/thumb.jpg",
"width": 300,
"height": 300
}
},
"metadata": {
"codec": "mp3",
"bitrate": 320000,
"sampleRate": 44100,
"channels": 2
},
"tags": ["meditation", "morning"],
"view_count": 1251,
"download_count": 340,
"created_at": "2024-01-01T00:00:00.000Z",
"updated_at": "2024-01-01T00:00:00.000Z"
}
List Assets#
Endpoint: GET /v1/assets
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
owner_id |
string | Filter by owner |
type |
string/array | Filter by asset type |
status |
string/array | Filter by status |
is_public |
boolean | Filter by visibility |
tags |
string | Comma-separated tags |
search |
string | Search title, filename, description |
page |
number | Page number (default: 1) |
limit |
number | Items per page (max: 100, default: 20) |
sort_by |
string | Sort field |
sort_order |
string | asc or desc |
Request:
curl -X GET "https://api.lilith.app/v1/assets?type=audio&tags=meditation&limit=20" \
-H "Authorization: Bearer <access_token>"
Response:
{
"data": [
{
"id": "asset-abc123",
"filename": "meditation-audio.mp3",
"title": "Morning Meditation",
"type": "audio",
"mime_type": "audio/mpeg",
"file_size": 15728640,
"status": "ready",
"is_public": true,
"thumbnail_url": "https://cdn.lilith.app/media/asset-abc123/thumb.jpg",
"created_at": "2024-01-01T00:00:00.000Z"
}
],
"total": 42,
"page": 1,
"limit": 20,
"total_pages": 3,
"has_more": true
}
Update Asset#
Endpoint: PATCH /v1/assets/:id
Request Body:
| Field | Type | Description |
|---|---|---|
title |
string | New title |
description |
string | New description |
is_public |
boolean | Visibility |
tags |
string[] | New tags |
metadata |
object | Custom metadata to merge |
Request:
curl -X PATCH "https://api.lilith.app/v1/assets/asset-abc123" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"title": "Updated Morning Meditation",
"tags": ["meditation", "morning", "featured"]
}'
Response:
{
"success": true,
"asset": {
"id": "asset-abc123",
"title": "Updated Morning Meditation",
"description": "A calming 10-minute morning meditation",
"status": "ready",
"is_public": true,
"tags": ["meditation", "morning", "featured"],
"updated_at": "2024-01-01T12:00:00.000Z"
}
}
Delete Asset#
Soft delete an asset.
Endpoint: DELETE /v1/assets/:id
Request:
curl -X DELETE "https://api.lilith.app/v1/assets/asset-abc123" \
-H "Authorization: Bearer <access_token>"
Response: 204 No Content
Download & Streaming#
Get Download URL#
Generate a time-limited download URL.
Endpoint: POST /v1/assets/:id/download-url
Request Body:
| Field | Type | Description |
|---|---|---|
version_id |
string | Specific version ID (optional) |
expires_in |
number | URL expiration in seconds (default: 3600) |
Request:
curl -X POST "https://api.lilith.app/v1/assets/asset-abc123/download-url" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"expires_in": 7200
}'
Response:
{
"url": "https://lilith-media.s3.amazonaws.com/media/asset-abc123/meditation.mp3?X-Amz-...",
"expires_in": 7200
}
Get Stream URL#
Generate a streaming URL for video/audio assets.
Endpoint: POST /v1/assets/:id/stream-url
Request Body:
| Field | Type | Description |
|---|---|---|
quality |
string | Quality level (e.g., 1080p, 720p, auto) |
Request:
curl -X POST "https://api.lilith.app/v1/assets/asset-video123/stream-url" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"quality": "720p"
}'
Response:
{
"url": "https://cdn.lilith.app/media/asset-video123/hls/720p/playlist.m3u8",
"quality": "720p"
}
Processing Jobs#
Request Processing#
Request a processing job for an asset.
Endpoint: POST /v1/assets/:id/process
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
type |
string | Yes | Processing type |
config |
object | No | Processing configuration |
Processing Types:
| Type | Description |
|---|---|
transcode |
Transcode to different format |
thumbnail |
Generate thumbnail images |
preview |
Generate preview (GIF, video clip) |
hls_packaging |
Package for HLS streaming |
dash_packaging |
Package for DASH streaming |
transcription |
Generate transcript |
metadata_extraction |
Extract detailed metadata |
ai_analysis |
AI-powered content analysis |
optimization |
Optimize for web delivery |
watermark |
Add watermark |
Request:
curl -X POST "https://api.lilith.app/v1/assets/asset-video123/process" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"type": "hls_packaging",
"config": {
"qualities": ["1080p", "720p", "480p"],
"encryption": true
}
}'
Response (202 Accepted):
{
"job_id": "job-proc123",
"asset_id": "asset-video123",
"type": "hls_packaging",
"status": "pending",
"created_at": "2024-01-01T00:00:00.000Z"
}
Get Processing Jobs#
Endpoint: GET /v1/assets/:id/jobs
Request:
curl -X GET "https://api.lilith.app/v1/assets/asset-video123/jobs" \
-H "Authorization: Bearer <access_token>"
Response:
{
"asset_id": "asset-video123",
"jobs": [
{
"id": "job-proc123",
"type": "hls_packaging",
"status": "running",
"progress": 45,
"progress_message": "Transcoding 720p variant...",
"error_message": null,
"started_at": "2024-01-01T00:01:00.000Z",
"completed_at": null,
"created_at": "2024-01-01T00:00:00.000Z"
},
{
"id": "job-thumb456",
"type": "thumbnail",
"status": "completed",
"progress": 100,
"progress_message": "Complete",
"error_message": null,
"started_at": "2024-01-01T00:00:30.000Z",
"completed_at": "2024-01-01T00:00:45.000Z",
"created_at": "2024-01-01T00:00:00.000Z"
}
]
}
Version Management#
Get Asset Versions#
Endpoint: GET /v1/assets/:id/versions
Request:
curl -X GET "https://api.lilith.app/v1/assets/asset-abc123/versions" \
-H "Authorization: Bearer <access_token>"
Response:
{
"asset_id": "asset-abc123",
"versions": [
{
"id": "version-orig",
"version_number": 1,
"variant_type": "original",
"is_current": true,
"quality": null,
"mime_type": "audio/mpeg",
"file_size": 15728640,
"width": null,
"height": null,
"status": "ready",
"created_at": "2024-01-01T00:00:00.000Z"
},
{
"id": "version-web",
"version_number": 2,
"variant_type": "web_optimized",
"is_current": false,
"quality": "128kbps",
"mime_type": "audio/mpeg",
"file_size": 4800000,
"width": null,
"height": null,
"status": "ready",
"created_at": "2024-01-01T00:05:00.000Z"
}
]
}
Error Handling#
Error Codes#
| Code | HTTP Status | Description |
|---|---|---|
ASSET_NOT_FOUND |
404 | Asset does not exist |
ASSET_FILE_REQUIRED |
400 | No file provided for upload |
ASSET_FILENAME_REQUIRED |
400 | Filename is required |
ASSET_CONTENT_TYPE_REQUIRED |
400 | Cannot determine content type |
ASSET_UPLOAD_FAILED |
500 | Upload failed |
FILE_TOO_SMALL |
400 | File too small for multipart upload |
INVALID_REQUEST |
400 | Invalid request parameters |
MULTIPART_INIT_FAILED |
500 | Failed to initiate multipart upload |
MULTIPART_COMPLETE_FAILED |
400 | Failed to complete multipart upload |
MULTIPART_ABORT_FAILED |
400 | Failed to abort multipart upload |
STREAMING_NOT_SUPPORTED |
400 | Streaming not supported for asset type |
PROCESSING_REQUEST_FAILED |
400 | Failed to request processing |
UPDATE_FAILED |
500 | Failed to update asset |
Error Response#
{
"error": "Asset not found",
"code": "ASSET_NOT_FOUND"
}
Metadata Extraction#
The API automatically extracts metadata based on asset type:
Image Metadata#
| Field | Description |
|---|---|
camera |
Camera make and model |
lens |
Lens model |
focalLength |
Focal length in mm |
aperture |
Aperture value |
shutterSpeed |
Shutter speed |
iso |
ISO sensitivity |
capturedAt |
Capture timestamp |
location |
GPS coordinates (lat, lng, altitude) |
Video/Audio Metadata#
| Field | Description |
|---|---|
codec |
Video or audio codec |
bitrate |
Bitrate in bps |
sampleRate |
Audio sample rate |
channels |
Audio channel count |
frameRate |
Video frame rate |
SDK Integration#
TypeScript/JavaScript#
import { LilithClient } from '@lilith/sdk';
const client = new LilithClient({
apiKey: process.env.LILITH_API_KEY,
});
// Direct upload
const asset = await client.media.uploadAsset({
file: fileBuffer,
filename: 'meditation.mp3',
title: 'Morning Meditation',
tags: ['meditation', 'morning'],
isPublic: true,
});
// Presigned upload
const presigned = await client.media.createPresignedUpload({
filename: 'large-video.mp4',
contentType: 'video/mp4',
});
// Upload to presigned URL
await fetch(presigned.uploadUrl, {
method: 'PUT',
body: fileBuffer,
headers: { 'Content-Type': 'video/mp4' },
});
// Confirm upload
await client.media.confirmUpload(presigned.assetId);
// Multipart upload for large files
const multipart = await client.media.createMultipartUpload({
filename: '4k-video.mp4',
contentType: 'video/mp4',
fileSize: 2147483648,
});
// Upload parts
const parts = [];
for (const part of multipart.parts) {
const response = await fetch(part.url, {
method: 'PUT',
body: chunks[part.partNumber - 1],
});
parts.push({
partNumber: part.partNumber,
etag: response.headers.get('ETag'),
});
}
// Complete multipart upload
await client.media.completeMultipartUpload(
multipart.assetId,
multipart.uploadId,
parts
);
// List assets
const assets = await client.media.listAssets({
type: 'audio',
tags: ['meditation'],
limit: 20,
});
// Get download URL
const { url } = await client.media.getDownloadUrl('asset-abc123', {
expiresIn: 3600,
});
// Request processing
const job = await client.media.requestProcessing('asset-video123', {
type: 'hls_packaging',
config: { qualities: ['1080p', '720p'] },
});
Related Documentation#
- Audio Processing - Audio transcoding and normalization
- Video Processing - Video transcoding and HLS packaging
- Transcript API - Transcript management
- CDN Setup - CloudFront CDN configuration
- Authentication - API authentication
Questions?#
- Technical Support: api-support@lilith.app
- Documentation: GitHub Issues