Eve library

Asset Management API

Guide

Revision 1

On this page

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#

  1. Asset Types
  2. Upload Operations
  3. Asset Operations
  4. Download & Streaming
  5. Processing Jobs
  6. Version Management
  7. Error Handling

Asset Types#

Asset Object#

json
{
  "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:

bash
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:

bash
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):

json
{
  "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:

bash
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):

json
{
  "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:

bash
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:

bash
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:

json
{
  "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:

bash
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):

json
{
  "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:

bash
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:

bash
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:

json
{
  "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:

bash
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:

bash
curl -X GET "https://api.lilith.app/v1/assets/asset-abc123" \
  -H "Authorization: Bearer <access_token>"

Response:

json
{
  "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:

bash
curl -X GET "https://api.lilith.app/v1/assets?type=audio&tags=meditation&limit=20" \
  -H "Authorization: Bearer <access_token>"

Response:

json
{
  "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:

bash
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:

json
{
  "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:

bash
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:

bash
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:

json
{
  "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:

bash
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:

json
{
  "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:

bash
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):

json
{
  "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:

bash
curl -X GET "https://api.lilith.app/v1/assets/asset-video123/jobs" \
  -H "Authorization: Bearer <access_token>"

Response:

json
{
  "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:

bash
curl -X GET "https://api.lilith.app/v1/assets/asset-abc123/versions" \
  -H "Authorization: Bearer <access_token>"

Response:

json
{
  "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#

json
{
  "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#

typescript
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'] },
});


Questions?#

  • Technical Support: api-support@lilith.app
  • Documentation: GitHub Issues