microCMS
Documentation
  • Pricing
  • Blog
  • FAQ
  • Contact
  • Sign In
  • Get started for free
Navigation
Tutorial
Next.js
  • Integration with Next.js
  • Getting Started with App Router
  • Tutorial (App Router)
  • Getting Started with Pages Router
  • Tutorial (Pages Router)
Astro
  • Getting Started
  • Integration with Astro
  • Tutorial
Nuxt
  • Integration with Nuxt
  • Getting Started
  • Tutorial
Gatsby
  • Integration with Gatsby
  • Getting Started
  • Tutorial
JavaScript
  • Integration with JavaScript
  • Getting Started (Browser)
  • Getting Started (Server)
PHP
  • Integration with PHP
  • Getting Started
Ruby
  • Integration with Ruby
  • Getting Started
Go
  • Integration with Go
  • Getting Started with microCMS
Manual
  • Introduction
Account & Login
  • Account Registration
  • Login
  • Email Address Authentication
Services
  • Creating a Service
  • Service Configuration
  • Template
  • Service Deletion
Payment
  • Change of Pricing Plan
  • Registering and Changing Payment Methods
API
  • Creating and Managing APIs
  • API Settings
  • Export/Import of API Schema
Fields
  • Text Field
  • Text Area
  • Image
  • Multiple Images
  • Date
  • Boolean
  • Selectable Field
  • Content Reference
  • Multiple Content References
  • Number
  • File
  • Extended Field
  • Repetition
  • Custom
Contents
  • CSV Export of Content
  • Content Creation
  • Content Editing
  • Content Management
  • View
  • Content Status
  • Custom Status
  • Setting the Content ID
  • Automatically Assigned Values for Content
  • CSV Import of Content
  • API Preview
  • Examples of Using Query Parameters with API Preview
  • Integration Methods by Rendering Type
  • Screen Preview
  • Setting Up Webhooks for Content
Rich Editor
  • How to Use the Rich Editor
  • Rich Editor WRITE API
  • How to Use the Old Rich Editor
Reviews
  • Review
  • AI Review
Media
  • Media Management
  • Changing Media Filters and Display Order
  • Media Tag Configuration
  • Setting Up Media Webhooks
  • Custom Domain Settings for Media
Permission Management
  • Member Management
  • Roles (Permission Management in the Admin Panel)
Environments
  • Multiple Environments (Development Environment)
  • Merging API Settings Between Environments
Connection
  • Amazon S3 Integration
Logs
  • Audit Log
  • Data Transfer Volume
Security
  • Content Update History
  • IP Restrictions for Management Dashboard
  • IP Restrictions for APIs
Authentication
  • Setting Up Two-Factor Authentication
  • Mandatory Two-Factor Authentication
  • Single Sign-On
Specifications & Limitations
  • Recommended Environment
  • Limitations / Precautions
Content API
  • What is the Content API?
Basic Operations
  • GET /api/v1/{endpoint}
  • GET /api/v1/{endpoint}/{content_id}
  • POST /api/v1/{endpoint}
  • PUT /api/v1/{endpoint}/{content_id}
  • PATCH /api/v1/{endpoint}/{content_id}
  • DELETE /api/v1/{endpoint}/{content_id}
API Keys
  • API Key (API Authentication and Authorization Management)
  • Migration from the Old API (X-API-KEY, etc.)
Responses & Error Handling
  • Response format for each field in the GET API
  • Specifying Query Parameters in the GET API
  • Error Responses of the Content API
Management API (Beta)
  • POST /api/v1/roles
  • DELETE /api/v1/roles/{role_id}
  • GET /api/v1/roles/{role_id}
  • PATCH /api/v1/roles/{role_id}
  • GET /api/v1/roles
  • What is the Management API?
Content Operations
  • PUT /api/v1/contents/{endpoint}/{content_id}/reservation
  • GET /api/v1/contents/{endpoint}
  • GET /api/v1/contents/{endpoint}/{content_id}
  • PATCH /api/v1/contents/{endpoint}/{content_id}/status
  • PATCH /api/v1/contents/{endpoint}/{content_id}/createdBy
Media Operations
  • GET /api/v2/media
  • GET /api/v1/media
  • POST /api/v1/media
  • DELETE /api/v2/media
Member Operations
  • PATCH /api/v1/members/{member_id}
  • GET /api/v1/members
  • GET /api/v1/members/{member_id}
API Operations
  • POST /api/v1/apis
  • GET /api/v1/apis
  • GET /api/v1/apis/{endpoint}
Service Operations
  • GET /api/v1/service
Responses & Error Handling
  • Management API Error Responses
Image API
  • What is the Image API?
Parameters
  • Image Size
  • Quality
  • Resolution and Screen Size
  • Format
  • Text
  • Border
  • Padding
  • Shape
  • Download
  • Watermark
MCP Server
  • microCMS MCP
  • microCMS Document MCP Server
  • Top
  • Manual

Media Management

Last updated: 2026/04/24

In microCMS, you can upload and manage media (files) separately from your content.

How to Upload Media

There are two ways to upload media in the management screen.
In either method, it is possible to upload multiple files as well as a single file.
For information on the types of media that can be uploaded, please refer to the help article "What types of media can be uploaded?".

How to Upload from the "Upload" Button

Click the "Upload" button in the upper right corner of the media management screen, and a file selection dialog will open, allowing you to upload files from there.

How to Upload via Drag and Drop

You can upload media by dragging and dropping it into the central area of the media management screen.

Information

You can also upload media via the API (some conditions apply).
For more details, please check POST /api/v1/media.

Caution

When uploading multiple files, there is no specific limit on the quantity. However, when uploading a large number of files, there is a possibility that errors may occur. In that case, please try uploading in smaller batches.

Delivery Method

It is delivered via CDN.

Media Format

The media is determined to be either Image or File (non-image media) based on the MIME type at the time of upload.

Delivery URL

The domain from which the media is delivered varies depending on the media format, as shown in the examples below.

  • Image: https://images.microcms-assets.io/assets/xxxx/yyyy/{fileName}.png
  • File: https://files.microcms-assets.io/assets/xxxx/yyyy/{fileName}.pdf

Additionally, the values contained in the media URL follow the rules below.

  • The "xxxx" part: A unique random value for each service
  • The "yyyy" part: A random value for each media (since it is generated each time, different values will be assigned even if the same file is uploaded multiple times)

Available Fields

The available fields vary depending on the media type.

  • Image: Image field, multiple image field, rich editor, old rich editor, file field
  • File: File field
Information

The media registered in the file field will have the delivery domain of "files.microcms-assets.io", regardless of the media format.

Tips

In addition to the fields mentioned above, it is also possible to directly copy the media URL and use it in other fields.

Media Visibility

Media becomes "public" at the moment of upload.
In other words, if you know the media URL, it can be accessed even by those who are not members of the microCMS service.

Information

When referencing media from published websites or web applications, there is a possibility that the media information included on the page may also be indexed by search engines.

Media Information

By selecting the uploaded media, you can view the media information on the right side of the screen.

  • File Name: The file name of the media. This relates to the displayed URL. Clicking the link will allow you to view the original data in a new tab.
  • Creation Date: The date the media was uploaded.
  • Format: The type and extension of the media.
  • Size: The file size of the media.
  • Image Size (images only): The dimensions of the image in height × width.
  • Uploader: The name of the member who uploaded the media (can be changed to any member later).
  • Content Reference: Information about the content that references the media.
  • Alternative Text: You can set alternative text to be included in the alt attribute of the img tag.
  • Tags: Tag information associated with the media can be set.

Checking Content References

If there is content that references the media, it will be indicated as "◯ references" as shown below.



Clicking the "◯ references" link will display a list of content that references the media. Note that the displayed content is limited to media for which you have read permissions.

Clicking the link for each content will take you to the edit page for that content.

Caution

As a known issue, there may be cases where reference information for content is displayed even though there is no content referencing the media. If this occurs, please contact the support team via the chat section located at the bottom right of the management screen.

Renaming Files

After uploading, you can change the media file name to any desired name.
First, click the pencil icon located to the right of the media file name.



A file name editing modal will appear, so please enter the new file name. Click "Change" to complete the modification.

Caution
  • Changing the file name will also change the URL of the delivered media, making the previous URL inaccessible. If you are using the media URL directly, it may result in broken links.
  • In the case of an SSG configuration, the previous URL may become invalid and lead to broken links until a rebuild is performed.

Change of Creator

The creator of the media can be changed to another member within the service.
First, click on the display area of the media creator.



A modal will appear, so please select the member to change to. Click "Change" to complete the change.

Bulk Change of Creator

You can select multiple media items and change the creator in bulk.
Check the media items for which you want to change the creator and click on "◯ items selected".


Click on "Change Creator".



A modal will appear, so please select the member to change to. Click "Change" to complete the change.


Tips

The change of media creator can be utilized when the media read permission is set to "Only media created by members of this role."

Since the creator is a factor in the read range settings, it is used to change the range.

Setting Alternative Text

After uploading media, you can set any alternative text.
The string you set will be output as the alt attribute of the img tag in the API response and Webhook payload (this can only be set for images).

First, click the pencil icon next to the alternative text.



After setting your desired string, press [Complete Settings] to finish the changes.

Deleting Media

Individual Deletion

Select the media you want to delete and click the "Delete" button at the bottom of the right-side menu to delete it.


Bulk Deletion

Check the media you want to delete and click on "◯ items selected".



Click "Delete Media" to delete the selected media.


Delete All

From "Media Settings" → "Delete All Media", you can delete all media by clicking the "Delete all media for ◯◯ service" button.

Information
  • Even after deleting media, there may be cases where the distribution URL can still be accessed for a while. For more information on this case, please refer to the help article "Even after deleting media, the URL can still be accessed. What should I do?".

Deletion Conditions

To prevent accidental deletion, you must ensure that there are no references from any content before deleting media.
When deleting media, please remove all references from the content, and perform the deletion only when the reference count is zero.

Information

For handling cases where reference information exists and cannot be deleted despite not being referenced in the content, please refer to the help article "There are "X references" linked to unreferenced media, and I cannot delete it. What should I do?".

Media Re-upload

After uploading, you can re-upload any media to overwrite it.
This feature can be used in cases such as when you want to replace media referenced in the content.

Re-upload Procedure

First, select the media you want to re-upload and click the "Re-upload" button at the bottom of the right-side menu.



Then, a file selection dialog will open, allowing you to choose any media.
A confirmation dialog will appear stating, "You are about to overwrite the media with the same URL. Do you want to continue uploading?" Click "OK" to start the media upload, which will overwrite the existing media.

Caution

If there is a cache remaining in the browser, the original media may be displayed immediately after re-uploading.

Information
  • When re-uploading, the set alternative text will be reset. Please reconfigure it according to the content of the re-uploaded file.
  • In a default re-upload, the media URL, including the file name, will not change. Even if you re-upload media with a different file name, the original file name will be maintained.

Replacing with a New URL

By default, the media URL will remain unchanged when re-uploaded.
If you want to use the traditional re-upload method to replace the media with a changed URL, click on "Replace with a New URL".

Caution
  • When you use "Replace with new URL" to re-upload media, the URL of the delivered media will also change, and access via the URL before re-uploading will no longer be possible. If you are directly using the media URL, there is a possibility of broken links.
  • In the case of an SSG configuration, the URL before re-uploading may become invalid and lead to broken links until a rebuild is performed.

Image API Preview

For media of the image type, you can check the preview when applying the Image API.

First, click the "Image API Preview" button located at the top right of the selected media.



Then, a preview will be displayed showing the results of applying various image APIs (such as ?w=300, ?fit=crop&w=200&h=200, etc.).

Information

The parameters that can be checked in the preview are only a part of the available options. For details on parameters that can be used with the image API, please refer to the document titled "What is the Image API".

Amazon S3 Integration

Amazon S3 Integration is a feature that allows you to switch the storage destination of media such as images and videos uploaded from the microCMS management screen from the default microCMS storage to an Amazon S3 bucket that you have prepared.

There are changes in specifications that may affect your usage, such as changes to the media distribution URL or the inability to use the image API, so please check the documentation for details.

Other Features

In the media management screen, there are additional features as listed below. For details on each feature, please refer to the respective documentation pages.

Changing Media Filters and Display Order
https://document.microcms.io/en/manual/media-filter
Media Tag Configuration
https://document.microcms.io/en/manual/media-tag-settings
Setting Up Media Webhooks
https://document.microcms.io/en/manual/medium-webhook-setting
Custom Domain Settings for Media
https://document.microcms.io/en/manual/custom-domain

Contents

  • How to Upload Media
  • How to Upload from the "Upload" Button
  • How to Upload via Drag and Drop
  • Delivery Method
  • Media Format
  • Delivery URL
  • Available Fields
  • Media Visibility
  • Media Information
  • Checking Content References
  • Renaming Files
  • Change of Creator
  • Bulk Change of Creator
  • Setting Alternative Text
  • Deleting Media
  • Individual Deletion
  • Bulk Deletion
  • Delete All
  • Deletion Conditions
  • Media Re-upload
  • Re-upload Procedure
  • Image API Preview
  • Amazon S3 Integration
  • Other Features
  • Company
  • Legal Notice
  • Terms of Service
  • Privacy Policy

Copyright © microcms.io All rights reserved.