---
title: "Create a new frame extraction for a file"
method: POST
path: "/files/{file_id}/frames"
tags: ["Files"]
---

# Create a new frame extraction for a file

`POST /files/{file_id}/frames`

## Request

- Base URL: `https://api.cloudglue.dev/v1`
- URL: `https://api.cloudglue.dev/v1/files/{file_id}/frames`
- Auth: HTTP bearer

Create a new frame extraction for a file using the specified frame extraction configuration. This is an async operation that returns immediately with a 'pending' status. Results are cached, so identical requests will return the same frame extraction.

## Path parameters

- `file_id` string, uuid, required

## Request body

- FrameExtractionConfig: Configuration for frame extraction. Currently only supports uniform strategy.
  - `strategy` 'uniform', required: Frame extraction strategy - currently only 'uniform' is supported
  - `uniform_config` FrameExtractionUniformConfig: Configuration for uniform frame extraction
    - `frames_per_second` number: Number of frames to extract per second of video
    - `max_width` number: Maximum width of extracted frames in pixels. Aspect ratio is preserved.
  - `thumbnails_config` FrameExtractionThumbnailsConfig: Configuration for frame thumbnails
    - `enable_frame_thumbnails` boolean: Whether to generate CDN-hosted thumbnails for extracted frames
  - `start_time_seconds` number: Optional: The start time of the video in seconds to start extracting frames from
  - `end_time_seconds` number: Optional: The end time of the video in seconds to stop extracting frames at

## Response `200`

Frame extraction created successfully

- FrameExtraction
  - `frame_extraction_id` string, uuid, required: Unique identifier for the frame extraction job
  - `status` 'pending' | 'processing' | 'completed' | 'failed', required: Status of the frame extraction job
  - `created_at` number, required: Unix timestamp in milliseconds when the frame extraction was created
  - `file_id` string, uuid, required: ID of the file this frame extraction belongs to
  - `frame_extraction_config` FrameExtractionConfig, required: Configuration for frame extraction. Currently only supports uniform strategy.
    - `strategy` 'uniform', required: Frame extraction strategy - currently only 'uniform' is supported
    - `uniform_config` FrameExtractionUniformConfig: Configuration for uniform frame extraction
      - `frames_per_second` number: Number of frames to extract per second of video
      - `max_width` number: Maximum width of extracted frames in pixels. Aspect ratio is preserved.
    - `thumbnails_config` FrameExtractionThumbnailsConfig: Configuration for frame thumbnails
      - `enable_frame_thumbnails` boolean: Whether to generate CDN-hosted thumbnails for extracted frames
    - `start_time_seconds` number: Optional: The start time of the video in seconds to start extracting frames from
    - `end_time_seconds` number: Optional: The end time of the video in seconds to stop extracting frames at
  - `frame_count` number: Total number of frames extracted (only present when status is completed)
  - `data` object: Frame data with pagination (only present when status is completed and frames exist)
    - `object` 'list', required: Object type, always 'list'
    - `frames` object[]: Array of extracted frames
      - `id` string, uuid, required: Unique identifier for the frame
      - `timestamp` number, required: Timestamp of the frame in seconds
      - `thumbnail_url` string: URL of the CDN-hosted thumbnail for the frame if thumbnails are enabled
    - `total` integer, required: Total number of frames in this extraction
    - `limit` integer, required: Number of frames returned in this response
    - `offset` integer, required: Offset from the start of the frames list

## Other responses

- `400`: Invalid request or file duration is less than specified time range
- `404`: File not found
- `500`: An unexpected error occurred on the server

## Changes

- **2026-10-30** `23d3f240819f`: 3 info
  - added the optional property `code` to the response with the `400` status
  - added the optional property `code` to the response with the `404` status
  - added the optional property `code` to the response with the `500` status
- **2026-03-11** `1d5d6115c0d0`: 7 info
  - the `enable_frame_thumbnails` request property default value `true` was removed
  - the `enable_frame_thumbnails` request property default value `true` was removed
  - the `frames_per_second` request property default value `1` was removed
  - the `max_width` request property default value `1024` was removed
  - …3 more
- **2025-10-10** `98ab592d7867`: 1 breaking, 2 info
  - the response property `frame_extraction_config/thumbnails_config/enable_frame_thumbnails` became optional for the status `200`
  - the request property `allOf[#/components/schemas/FrameExtractionConfig]/thumbnails_config/enable_frame_thumbnails` became optional
  - the request property `thumbnails_config/enable_frame_thumbnails` became optional
- **2025-10-10** `3f3c2cfec49d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cloudglue/apis/cloudglue-api/changes/files/:file_id/frames/post.md)

---

[API](https://skmtc.dev/cloudglue/apis/cloudglue-api.md) - [All operations](https://skmtc.dev/cloudglue/apis/cloudglue-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cloudglue/apis/cloudglue-api/revisions/23d3f240819f?raw)