Get Keyframes Async
Asynchronous scene-change keyframe extraction for video files.
Detects scene changes in the source video and returns one representative
keyframe per detected scene, each tagged with its timestamp (seconds from
the start of the video) and scene-change score. Set include_images = true
to also receive each frame as a base64-encoded JPEG; when the field is
omitted the response carries keyframe metadata only.
Supported video formats: .3gp, .3gpp, .3gpp2, .asf, .avi, .dv, .flv, .m2t,
.m2ts, .m4v, .mkv, .mov, .mp4, .mpeg, .mpg, .mts, .mxf, .oggtheora, .ogv,
.rm, .ts, .vob, .webm, .wmv. Unsupported formats return an
unsupported_format_error.
Limits: the source file must be at most 10 GB. To keep responses within
service limits the number of keyframes and the total image payload are
bounded; requests that would exceed these limits return a
limit_exceeded_error — raise scene_change_threshold or set
include_images = false to stay within bounds.
Required scope: files.content.read
Endpoint format: RPC
This endpoint does not support apps with the app folder permission.
Authentication
App-level OAuth 2.0 token (no user context). Use Authorization: Bearer <token>.
Obtain by calling the token endpoint with grant_type=client_credentials.
Only available on endpoints that declare app auth support.
OAuth 2.0 token issued to a specific user. Use Authorization: Bearer <token>.
Public clients should use the authorization code flow with PKCE (S256).
For background or offline access, send token_access_type=offline during authorization and use the returned refresh token to obtain new access tokens.
You can generate a short-lived access token from the App Console; see Testing with a generated token.
Headers
Acts on behalf of a team member for supported user-auth operations. Pass a team member ID such as dbmid:.... When used with a team token, that token must also include the team_data.member scope.
Scopes path-based operations to a namespace (root). The value is a JSON serialization of the common.PathRoot union: {".tag": "home"}, {".tag": "root", "root": "<namespace_id>"}, or {".tag": "namespace_id", "namespace_id": "<namespace_id>"}. On failure the request returns 422 with a common.PathRootError.
Request
Identifier of the video file to extract keyframes from. Callers must set
exactly one of the FileIdOrUrl variants. Keyframe extraction is supported
for video files only; see the route description for the supported formats.
Requests against unsupported formats return unsupported_format_error.
A Dropbox-issued file ID for a file the authenticated user has access to, e.g. “id:a4ayc_80_OEAAAAAAAAAYa”.
When true, each returned keyframe includes the JPEG image bytes,
base64-encoded, in ApiKeyframe.image_base64. When false, the response
contains only per-keyframe metadata (timestamp and scene score) and
image_base64 is left empty — useful when you only need the scene
boundaries and want a small response. NOTE: because the field defaults to
false in proto3, callers who want images must set this explicitly to true.
Sensitivity of scene-change detection. A keyframe is emitted whenever the frame-to-frame scene score crosses this threshold, so a LOWER value yields MORE keyframes. Valid range is (0.0, 1.0]. When omitted (0.0) the service uses a default of 0.3, which is a good starting point for most videos.