Media API

The Media API provides methods for managing images, files, and media uploads.

Uploading Media

`sdk.media.upload(file, options)`

Upload a file to the media library.

const result = await sdk.media.upload(file, {
  folder: 'uploads/images',
  optimize: true,
  maxWidth: 1920
});
 
console.log(result);
// {
//   id: 'media_abc123',
//   url: '/uploads/images/my-image.jpg',
//   thumbnail: '/uploads/images/my-image-thumb.jpg',
//   width: 1920,
//   height: 1080,
//   size: 245678,
//   mimeType: 'image/jpeg'
// }

Options:

Option	Type	Default	Description
`folder`	string	`'uploads'`	Destination folder
`optimize`	boolean	`true`	Compress images
`maxWidth`	number	`2048`	Maximum width for images
`maxHeight`	number	`null`	Maximum height
`quality`	number	`85`	JPEG quality (1-100)
`generateThumbnail`	boolean	`true`	Create thumbnail
`thumbnailWidth`	number	`300`	Thumbnail width

Getting Media

`sdk.media.get(id)`

Get a single media item by ID.

const media = await sdk.media.get('media_abc123');

`sdk.media.getAll(options)`

Get all media with pagination.

const result = await sdk.media.getAll({
  page: 1,
  limit: 20,
  type: 'image',
  folder: 'uploads/images'
});
 
// result.items - array of media objects
// result.total - total count
// result.pages - total pages

Options:

Option	Type	Description
`page`	number	Page number
`limit`	number	Items per page
`type`	string	Filter by type: `'image'`, `'video'`, `'document'`, `'audio'`
`folder`	string	Filter by folder
`search`	string	Search filename
`sortBy`	string	Sort field: `'createdAt'`, `'name'`, `'size'`
`sortOrder`	string	`'asc'` or `'desc'`

Deleting Media

`sdk.media.delete(id)`

Delete a media item.

await sdk.media.delete('media_abc123');

`sdk.media.deleteMultiple(ids)`

Delete multiple media items.

await sdk.media.deleteMultiple(['media_abc123', 'media_def456']);

Image Processing

`sdk.media.resize(id, options)`

Create a resized version of an image.

const resized = await sdk.media.resize('media_abc123', {
  width: 800,
  height: 600,
  fit: 'cover'
});
 
// Returns URL of resized image

Fit Options:

cover - Crop to exact dimensions
contain - Fit within dimensions
fill - Stretch to exact dimensions
inside - Resize down if larger

`sdk.media.crop(id, options)`

Crop an image.

const cropped = await sdk.media.crop('media_abc123', {
  x: 100,
  y: 100,
  width: 500,
  height: 500
});

Folders

`sdk.media.createFolder(path)`

Create a new folder.

await sdk.media.createFolder('uploads/gallery/2024');

`sdk.media.getFolders()`

List all folders.

const folders = await sdk.media.getFolders();
// ['uploads', 'uploads/images', 'uploads/documents', ...]

`sdk.media.moveToFolder(id, folder)`

Move media to a folder.

await sdk.media.moveToFolder('media_abc123', 'uploads/archive');

URL Helpers

`sdk.media.getUrl(id, options)`

Get URL for a media item with optional transformations.

// Original URL
const url = sdk.media.getUrl('media_abc123');
 
// With resize
const thumbUrl = sdk.media.getUrl('media_abc123', {
  width: 300,
  height: 200,
  fit: 'cover'
});

`sdk.media.getThumbnailUrl(id)`

Get thumbnail URL.

const thumb = sdk.media.getThumbnailUrl('media_abc123');

Example: Gallery Plugin

module.exports = async function(sdk) {
  
  sdk.shortcodes.register('gallery', async (attrs) => {
    const { folder = 'gallery', columns = 3 } = attrs;
    
    const result = await sdk.media.getAll({
      type: 'image',
      folder: folder,
      limit: 50
    });
    
    if (result.items.length === 0) {
      return '<p>No images found</p>';
    }
    
    let html = `<div class="gallery" style="
      display: grid;
      grid-template-columns: repeat(${columns}, 1fr);
      gap: 15px;
    ">`;
    
    result.items.forEach(image => {
      const thumbUrl = sdk.media.getUrl(image.id, {
        width: 400,
        height: 300,
        fit: 'cover'
      });
      
      html += `
        <a href="${image.url}" class="gallery-item" data-lightbox>
          <img src="${thumbUrl}" alt="${image.filename}" loading="lazy">
        </a>
      `;
    });
    
    html += '</div>';
    return html;
  });
  
  return {};
};

Example: Image Upload Form

module.exports = async function(sdk) {
  
  // Add custom admin page
  sdk.admin.registerPage('image-uploader', {
    title: 'Bulk Image Uploader',
    icon: '📷',
    
    render: async () => {
      return `
        <div class="upload-form">
          <input type="file" id="images" multiple accept="image/*">
          <button onclick="uploadImages()">Upload All</button>
          <div id="progress"></div>
        </div>
        <script>
          async function uploadImages() {
            const files = document.getElementById('images').files;
            const progress = document.getElementById('progress');
            
            for (let i = 0; i < files.length; i++) {
              progress.textContent = 'Uploading ' + (i + 1) + ' of ' + files.length;
              
              const formData = new FormData();
              formData.append('file', files[i]);
              
              await fetch('/api/media/upload', {
                method: 'POST',
                body: formData
              });
            }
            
            progress.textContent = 'Done!';
          }
        </script>
      `;
    }
  });
  
  return {};
};

Content API Hooks API