All Products
Search

This Product

    ApsaraVideo VOD:RefreshMediaPlayUrls

    Document Center

    ApsaraVideo VOD:RefreshMediaPlayUrls

    Last Updated:Mar 27, 2026

    Submits media refresh or prefetch tasks based on the media IDs.

    Operation description

    • ApsaraVideo VOD allows you to purge and prefetch resources. The purge feature forces the point of presence (POP) to clear cached resources and retrieve the latest resources from origin servers. The prefetch feature allows the POP to retrieve frequently accessed resources from origin servers during off-peak hours. This increases the cache hit ratio.

    • Submit purge or prefetch tasks based on the media ID. You can also specify the format and resolution of the media streams to purge or prefetch based on your business requirements.

    • You can submit a maximum of 20 purge or prefetch tasks at a time.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    vod:RefreshMediaPlayUrls

    update

    *All Resource

    *

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    MediaIds

    string

    Yes

    The IDs of the media files that you want to refresh or prefetch. You can specify a maximum of 20 IDs. Separate multiple IDs with commas (,). You can use one of the following methods to obtain the ID:

    • Log on to the ApsaraVideo VOD console. In the left-side navigation pane, choose Media Files > Audio/Video. On the Video and Audio page, view the ID of the audio or video file. This method is applicable to files that are uploaded by using the ApsaraVideo VOD console.

    • Obtain the value of VideoId from the response to the CreateUploadVideo operation that you call to upload media files.

    • Obtain the value of VideoId from the response to the SearchMedia operation that you call to query the media ID after the media file is uploaded.

    ca3a8f6e4957b658067095869****, a6e49sfgd23p5g9ja7095863****
    TaskType

    string

    Yes

    The type of the task that you want to create. Valid values:

    • Refresh

    • Preload

    Preload
    Formats

    string

    No

    The formats of the media streams you want to refresh or prefetch. You can specify multiple formats. Separate multiple formats with commas (,). If you leave this parameter empty, media streams in all formats are refreshed or prefetched by default. Valid values:

    • mp4

    • m3u8

    • mp3

    • flv

    • webm

    • ts

    mp4,m3u8
    Definitions

    string

    No

    Specifies the resolutions of the media streams you want to refresh or prefetch. You can specify multiple resolutions. Separate multiple resolutions with commas (,). If you leave this parameter empty, media streams in all resolutions are refreshed or prefetched by default.

    Note

    The value must be supported in the Definition section in Parameters for media assets.

    HD, SD
    StreamType

    string

    No

    Specifies the types of media streams you want to refresh or prefetch. You can specify multiple types. Separate multiple types with commas (,). If you leave this parameter empty, media streams in all types are refreshed or prefetched by default. Valid values:

    • video

    • audio

    video
    ResultType

    string

    No

    Specifies the type of the refresh or prefetch operation. Default value: Single. Valid values:

    • Single: Only one latest transcoded stream is refreshed or prefetched for each resolution and format.

    • Multiple: All transcoded streams are refreshed or prefetched for each resolution and format.

    Single
    SliceFlag

    boolean

    No

    Specifies whether to refresh or prefetch the playback URLs of the TS files of the M3U8 media stream. Default value: false. Valid values:

    • false

    • true

    false
    SliceCount

    integer

    No

    Specifies the number of the playback URLs of the TS files for the M3U8 media stream you want to refresh or prefetch. After you set this parameter, only the playback URLs of the first N TS files will be refreshed or prefetched. Valid values: 1 to 20. Default value: 5.

    5
    UserData

    string

    No

    The custom configurations such as callback configurations and upload acceleration configurations. The value must be a JSON string. For more information, see the "UserData: specifies the custom configurations for media upload" section in the Request parameter topic.

    Note

    • The callback configurations take effect only after you specify the HTTP callback URL and select specific callback events in the ApsaraVideo VOD console. For more information about how to configure HTTP callback settings in the ApsaraVideo VOD console, see Configure callback settings.

    • To enable the upload acceleration feature, submit a ticket. For more information, see Overview. For more information about how to submit a ticket, see Contact us.

    {"MessageCallback":{"CallbackURL":"http://example.aliyundoc.com"}, "Extend":{"localId":"xxx","test":"www"}}

    Response elements

    Element

    Type

    Description

    Example

    object

    The returned data.

    MediaRefreshJobId

    string

    The ID of the refresh or prefetch task.

    41d465e31957****
    NonExistMediaIds

    string

    The IDs of the media files that do not exist.

    ca3a8f6e4957b658067095869****
    ForbiddenMediaIds

    string

    The IDs of the media files that cannot be operated on. In most cases, media files cannot be operated on because you are not authorized to perform the operations. For more information, see Overview.

    a6e49sfgd23p5g9ja7095863****
    RequestId

    string

    The ID of the request.

    25818875-5F78-4AF6-04D5-D7393642****

    Examples

    Success response

    JSON format

    {
  "MediaRefreshJobId": "41d465e31957****",
  "NonExistMediaIds": "ca3a8f6e4957b658067095869****",
  "ForbiddenMediaIds": "a6e49sfgd23p5g9ja7095863****",
  "RequestId": "25818875-5F78-4AF6-04D5-D7393642****"
}

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.