Delete media files

How it works

Before deleting files, you must understand how the operation works and its potential risks to prevent irreversible data loss.

Scenario 1: Delete files using the console

The console provides an intuitive interface and is suitable for deleting a small number of files.

1. Log on to the ApsaraVideo VOD console.

2. In the navigation pane on the left, choose Media Assets, and then click Audio/Video, Image, or Short Video Material.

3. On the management page, find the file that you want to delete, and then click Delete in the Actions column.

Scenario 2: Delete files using the API or SDK

Deleting media files using the API or SDK provides greater flexibility and automation. It is the preferred solution for managing many media assets in a production environment.

Delete one or more full videos

This is the most common scenario. Call the DeleteVideo operation to delete all resources related to a video, such as the source file, transcoded streams, and snapshots. The following code provides an example.

pythonfrom aliyunsdkvod.request.v20170321 import DeleteVideoRequest
from aliyunsdkcore.client import AcsClient
import json

def delete_video_safely(video_ids: str, access_key: str, secret_key: str, region='cn-shanghai'):
    """
    Safely delete one or more videos.
    
    Args:
        video_ids: The IDs of the videos. Separate multiple IDs with commas.
        access_key: The AccessKey ID.
        secret_key: The AccessKey secret.
        region: The region.
    
    Returns:
        dict: A dictionary that indicates whether the call was successful and includes any error messages.
    """
    try:
        # 1. Initialize the client.
        client = AcsClient(access_key, secret_key, region)
        
        # 2. Create a delete request.
        request = DeleteVideoRequest.DeleteVideoRequest()
        request.set_VideoIds(video_ids)
        
        # 3. Execute the deletion.
        response = client.do_action_with_exception(request)
        result = json.loads(response)
        
        print(f"Delete request for videos {video_ids} submitted. RequestID: {result.get('RequestId')}")
        return {"success": True, "data": result}
        
    except Exception as e:
        error_msg = str(e)
        print(f"Deletion failed: {error_msg}")
        
        # Common error handling
        if "InvalidVideo.NotFound" in error_msg:
            return {"success": False, "error": "The video does not exist or has been deleted."}
        elif "Forbidden.IllegalStatus" in error_msg:
            return {"success": False, "error": "The video cannot be deleted due to its current status. It may be undergoing transcoding."}
        elif "Throttling" in error_msg:
            return {"success": False, "error": "The request is too frequent. Please try again later."}
        else:
            return {"success": False, "error": f"Unknown error: {error_msg}"}

# Example usage
# result = delete_video_safely(
#     video_ids="your-video-id-1,your-video-id-2",
#     access_key="your-access-key", 
#     secret_key="your-secret-key"
# )

Delete video streams of a specific definition

Call the DeleteStream operation. You can use this feature when you only need to remove a specific definition but want to keep others. The following code provides an example.

pythonfrom aliyunsdkvod.request.v20170321 import DeleteStreamRequest
# ... (Reuse the AcsClient initialization from the previous example)

def delete_specific_stream(video_id: str, job_ids: str, access_key: str, secret_key: str):
    """
    Delete the transcoded stream of a specific definition.
    
    Args:
        video_id: The video ID.
        job_ids: The list of transcoding job IDs. Separate multiple IDs with commas.
    """
    try:
        client = AcsClient(access_key, secret_key, 'cn-shanghai')
        request = DeleteStreamRequest.DeleteStreamRequest()
        request.set_VideoId(video_id)
        request.set_JobIds(job_ids)
        
        response = client.do_action_with_exception(request)
        print(f"The specified definition stream for video {video_id} was deleted.")
        return json.loads(response)
        
    except Exception as e:
        print(f"Failed to delete the stream: {e}")
        raise

# Example: Assume you have obtained the JobId 'job-id-for-4k' for the '4K' definition by calling GetPlayInfo.
# delete_specific_stream(
#     video_id="your-video-id",
#     job_ids="job-id-for-4k",
#     access_key="your-access-key",
#     secret_key="your-secret-key"
# )

Force delete a source file

Call the DeleteMezzanines operation. The deletion behavior varies depending on the upload mode:

• With transcoding enabled: The source file (mezzanine) and the transcoded streams are stored separately. Deleting the source file retains the generated transcoded streams, which can still be played normally.

• Without transcoding: The mezzanine is the source file itself. Deleting the source file is equivalent to deleting the mezzanine, which causes the playback streams to be removed and unrecoverable.

The following code provides an example.

pythonfrom aliyunsdkvod.request.v20170321 import DeleteMezzaninesRequest
# ... (Reuse the AcsClient initialization from the previous example)

def force_delete_source_file(video_ids: str, access_key: str, secret_key: str):
    """
    Force delete the source file.
    
    Args:
        video_ids: The list of video IDs. Separate multiple IDs with commas.
    """
    try:
        client = AcsClient(access_key, secret_key, 'cn-shanghai')
        request = DeleteMezzaninesRequest.DeleteMezzaninesRequest()
        request.set_VideoIds(video_ids)
        request.set_Force(True)  # Force delete flag
        
        response = client.do_action_with_exception(request)
        print("Source file force deleted successfully.")
        print("Purge the CDN cache immediately to prevent 404 errors during original quality playback.")
        return json.loads(response)
        
    except Exception as e:
        print(f"Force deletion failed: {e}")
        raise

# force_delete_source_file(
#     video_ids="your-video-id",
#     access_key="your-access-key",
#     secret_key="your-secret-key"
# )

The DeleteMezzanines operation deletes only the video source file (mezzanine file). After the call succeeds, the API returns a success response, but the video placeholder remains in the media library's audio/video list. A successful API response does not mean that the video has been removed from the list. To completely remove a video entry from the media library, call the DeleteVideo operation instead, which deletes the entire video, including the source file, transcoded stream files, and snapshots.

Delete image files

To delete uploaded images or video snapshots, call the DeleteImage operation.