Skip to main content

Media API

The Media namespace provides operations for uploading images and media files using presigned S3 uploads.

How Media Upload Works​

DFOS uses a presigned upload flow:

  1. Request a media object (get presigned URL)
  2. Upload file directly to S3 using the presigned URL
  3. Reference the media ID in posts, profiles, etc.

This keeps file uploads off the API servers and uses S3 directly.

Key Endpoints​

Create media object - POST /media

Get media object - GET /media/{id}

Common Workflows​

Upload an Image​

1. Request media object:

POST /media
{
  "filename": "photo.jpg",
  "contentType": "image/jpeg"
}

Returns:

{
  "uploadUrl": "https://s3.amazonaws.com/...",
  "contentDispositionHeader": "inline; filename=\"photo.jpg\"",
  "media": {
    "id": "media_abc123",
    "filename": "photo.jpg",
    "contentType": "image/jpeg"
  }
}

2. Upload file to S3:

PUT <uploadUrl>
Content-Type: image/jpeg
Content-Disposition: <contentDispositionHeader from response>
Body: <file bytes>

3. Use media ID:

# In a post
POST /posts
{
  "spaceDID": "space_xyz",
  "body": "Check this out",
  "attachmentIds": ["media_abc123"]
}

# Or in a profile
PUT /identity/current
{
  "id": "current",
  "avatarId": "media_abc123"
}

Supported Formats​

  • Images: PNG, JPEG, GIF, WebP
  • Max size: 10 MB per file

Media Visibility​

All media is currently created as public with CDN URLs via Imgix. Media objects include:

  • publicDownloadUrl - Full HTTPS URL to the media (available after upload completes)
  • blurHash - For progressive image loading (generated async after upload)
  • canonicalUri - Content-addressed URI (generated async after upload)

Access control is currently managed at the uploader level - only the user who uploaded the media can retrieve it via GET /media/{id}.

Get Media Info​

GET /media/{id}

Returns media metadata including:

  • Filename
  • Content type
  • Size
  • Public URL (if usage is public)
  • Blur hash (for progressive loading)

Image Transformations​

Public media uses Imgix for transformations. Append query params to the CDN URL:

https://metalabel.imgix.net/media_abc123?w=400&h=400&fit=crop

Common params:

  • w - width
  • h - height
  • fit - crop, scale, etc.
  • auto=format,compress - optimize

See Imgix documentation for all options.

Authorization​

  • Creating media: Authenticated users
  • Retrieving media metadata (GET /media/{id}): Only the user who uploaded it
  • Accessing public URLs: Anyone with the publicDownloadUrl can view the media

Best Practices​

  1. Check file size before requesting upload (10 MB limit)
  2. Validate content type on client side
  3. Handle upload failures gracefully
  4. Use blur hash for progressive image loading
  5. Use Imgix transformations instead of uploading multiple sizes

See Also​