Get Keyframes Async | Dropbox API Documentation

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

Authentication: App, User

This endpoint does not support apps with the app folder permission.

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](https://docs.dropboxapi.com/dropbox-api/docs/technical-reference/request-response-formats#rpc-endpoints) **Authentication:** [App](https://docs.dropboxapi.com/dropbox-api/docs/auth-types#app-authentication), [User](https://docs.dropboxapi.com/dropbox-api/docs/auth-types#user-authentication) This endpoint does not support apps with the app folder permission.

Authentication

AuthorizationBearer

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.

AuthorizationBearer

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.

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](https://docs.dropboxapi.com/dropbox-api/docs/oauth#testing-with-a-generated-token).

Headers

Dropbox-API-Path-RootstringOptional

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.

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

This endpoint expects a nullable object.

file_id_or_urlobject or nullOptional

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.

include_imagesbooleanOptional

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.

scene_change_thresholddoubleOptional

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.

Response headers

X-Dropbox-Request-IdstringOptional

A unique identifier for the request, useful for debugging and support.

Response

Successful response

Variant:

async_common.LaunchResultBase.async_job_idobject

This response indicates that the processing is asynchronous. The string is an id that can be used to obtain the status of the asynchronous job.

Errors

401

Unauthorized Error

403

Forbidden Error

429

Too Many Requests Error

500

Internal Server Error