DocsICP FilingConsole
官方文档
首页

Snapshot capture FAQ

更新时间：
复制 MD 格式
产品详情
我的收藏

Common issues and solutions for MPS snapshot jobs, including timeout errors, parameter configuration, and unexpected output.

Common errors for snapshot jobs

Snapshot jobs may return the following error codes: SnapshotTimeOut, InvalidParameter.ResourceNotFound, or InvalidParameter.ResourceContentBad. If a snapshot job fails, call QuerySnapshotJobList to query the failure cause.

SnapshotTimeOut

Returned when a synchronous snapshot job times out. The timeout period is 5 seconds. Large input files may exceed this limit. If timeouts occur frequently, submit the job in asynchronous mode instead.

InvalidParameter.ResourceNotFound

Returned when the input file cannot be found. Check the following causes:

Cause

Solution

The input file was not uploaded or was deleted before the job was submitted.

Upload the input file before submitting the snapshot job.

The OSS path of the input file is invalid.

Verify the path spelling.

The OSS path of the input file is not URL-encoded.

Apply URL encoding to the path. URL encoding.

The OSS bucket is not in the same region as MPS.

Change the region.

The input file uses Cold Archive or Deep Cold Archive storage.

Restore the data before accessing it.

The input file uses Archive storage and real-time access is disabled or the file is not restored.

Enable real-time access for Archive data, or restore the file before accessing it.

Referer-based hotlink protection is enabled for the OSS bucket.

For workflow-triggered jobs, configure a referer for the OSS bucket. For manually submitted jobs, add the Referer parameter to the Input parameter.

InvalidParameter.ResourceContentBad

Returned when parameter conflicts exist or the input file is damaged. Troubleshoot as follows:

  1. Verify that the input file is not corrupted.

  2. Check the snapshot job parameters, especially Time, FrameType, and OutputFile.

  3. If the error persists, contact Alibaba Cloud technical support with your region ID and request ID.

Synchronous snapshot fails for M3U8 files

For synchronous snapshot jobs on M3U8 files, the TS files referenced in the M3U8 index must be in the same directory as the M3U8 file. Asynchronous mode does not have this restriction.

Snapshot fails: specified time exceeds video duration

Error code: InvalidParameter.ResourceContentBad

Error message: The resource operated InputFile is bad

Cause

Solution

The `time` parameter exceeds the video duration for a single regular-frame snapshot job.

Set Time to a value smaller than the video duration. Alternatively, use keyframe mode — if Time exceeds the video length, the closest keyframe is captured instead of failing.

Job fails: invalid OutputFile Object parameter

Error code: InvalidParameter.ResourceContentBad

Error message: The format of parameter "SnapshotConfig:OutputFile:Object" is invalid

Cause

Solution

The Object parameter in OutputFile does not contain the {count} placeholder for a multi-snapshot job.

Add {Count} to the Object parameter in OutputFile to prevent snapshots from overwriting each other.

Format is set to vtt for WebVTT snapshots, but the Object parameter in OutputFile does not use the .vtt extension.

Change the file extension in the Object parameter to .vtt.

Job fails: invalid TileOutputFile Object parameter

Error code: InvalidParameter.ResourceContentBad

Error message: The format of parameter "SnapshotConfig:TileOutputFile:Object" is invalid

Cause

Solution

The Object parameter in TileOutputFile does not contain the {TileCount} placeholder for a sprite generation job.

Add {TileCount} to the Object parameter in TileOutputFile to prevent sprites from overwriting each other.

Snapshot settings FAQ

How do I distinguish between synchronous and asynchronous snapshot modes?

If the Interval or Num parameter is specified in SnapshotConfig, the job runs in asynchronous mode regardless of whether PipelineId is specified.

What happens if the snapshot time exceeds the video duration?

  • Single snapshot where Time exceeds duration:

    • Regular frame: The job fails with error code "InvalidParameter.ResourceContentBad" and message "The resource operated InputFile is bad".

    • Keyframe: The job succeeds. The closest keyframe to the specified time is captured.

  • Multiple snapshots: If Time + Interval × Num exceeds the video duration, the job still succeeds. Snapshots are captured only at points within the video duration. The total number of captured snapshots is returned.

Unexpected snapshot results

Snapshot count does not match settings

Check the following causes:

Cause

Solution

The sprite output path and individual image output path are identical, causing files to overwrite each other.

Use different buckets or paths for OutputFile and TileOutputFile.

Both Interval and Num are specified (sampling mode). If the video is too short, fewer snapshots may be captured than specified by Num.

This is expected behavior.

Black frame detection is enabled for a single-snapshot job. No snapshot is captured if the frame is filtered out as black.

Adjust the BlackLevel and PixelBlackThreshold parameters to reduce black frame filtering.

Keyframe capture is enabled (`FrameType=intra`). Possible reasons:

  • The video contains fewer I-frames than the Num value.

  • The GOP size is not fixed, so I-frames are unevenly distributed. The snapshot interval is calculated as video duration / number of snapshots. With uneven I-frame distribution, some intervals may contain multiple I-frames while others contain none.

  • No I-frame exists near the target time, so no snapshot is captured for that interval.

To capture snapshots at precise times, set FrameType to normal.

Snapshot timing does not match settings

Cause

Solution

FrameType is set to intra (keyframe mode). Keyframes appear at intervals in the video, so capture times are not precise — the closest keyframe to the specified time is captured instead.

To capture snapshots at precise times, set FrameType to normal.

Blurry snapshots

Cause

Solution

FrameType is set to normal. Regular frames are less sharp than keyframes.

Set FrameType to intra for sharper snapshots.

Snapshot distortion or aspect ratio mismatch

Check the following causes:

Cause

Solution

Both width and height are specified, but the aspect ratio differs from the input video.

Specify only width or height. The other dimension scales automatically to preserve the original aspect ratio.

`Cellwidth` and `Cellheight` values do not match the source aspect ratio, distorting individual images in the sprite.

Set only one dimension (width or height). The other adjusts automatically to maintain the aspect ratio.

The input video has incompatible DAR/SAR attributes.

Contact Alibaba Cloud technical support with your region ID and snapshot job ID.

Portrait video produces landscape snapshots

MP4 videos in portrait mode contain a rotation identifier (common in mobile-captured videos), so snapshots appear in landscape orientation.

To check for a rotation identifier:

Call SubmitMediaInfoJob and check the Rotate parameter. A value of -90 or 90 indicates the video is rotated, causing the display orientation to differ from the input.

Synchronous snapshot does not generate sprites or VTT files

Synchronous mode captures only one snapshot and does not support sprite generation or WebVTT output. To generate sprites or WebVTT snapshots, submit the job in asynchronous mode.

Previous：FAQNext：Workflow FAQ