---
title: "[Deprecated] Add a video to a collection"
method: POST
path: "/collections/{collection_id}/videos"
tags: ["Collections"]
deprecated: true
---

# \[Deprecated\] Add a video to a collection

`POST /collections/{collection_id}/videos`

## Request

- Base URL: `https://api.cloudglue.dev/v1`
- URL: `https://api.cloudglue.dev/v1/collections/{collection_id}/videos`
- Auth: HTTP bearer

> **Deprecated.**

**DEPRECATED: Use POST /collections/\{collection_id\}/media instead.**

Add a video to a collection. This endpoint is deprecated - use the /media endpoint which supports both video and audio files.

## Path parameters

- `collection_id` string, required

## Request body

- union
  - object
    - `file_id` string, required: The ID of the file to add to the collection
    - `segmentation_id` string, uuid: Segmentation job id to use. If not provided will use default to uniform 20s segmentation. Cannot be provided together with segmentation_config.
    - `segmentation_config` SegmentationConfig: Configuration for video segmentation. **Choose a strategy and provide ONLY the corresponding config:** • **uniform**: Provide `uniform_config`, do NOT provide other configs • **shot-detector**: Provide `shot_detector_config`, do NOT provide other configs • **manual**: Provide `manual_config`, do NOT provide other configs • **narrative**: Provide `narrative_config`, do NOT provide other configs Optionally specify `start_time_seconds` and `end_time_seconds` to limit segmentation to a portion of the video.
      - `strategy` 'uniform' | 'shot-detector' | 'manual' | 'narrative', required: Segmentation strategy - determines which config you must provide
      - `uniform_config` SegmentationUniformConfig
        - `window_seconds` number, required: The duration of each segment in seconds. Must be between 1 and 120 seconds.
        - `hop_seconds` number: The offset between the start of new windows. This means there can be overlap between segments. If not provided, defaults to window_seconds. Must be between 1 and 120 seconds.
      - `shot_detector_config` SegmentationShotDetectorConfig
        - `threshold` number, nullable: Detection sensitivity threshold - lower values create more segments: • **content**: Sensitivity to visual differences (default: 27.0). Lower values detect smaller changes in color/lighting. • **adaptive**: Does not support threshold parameter - uses internal adaptive algorithm.
        - `min_seconds` number, nullable: The minimum length of a shot in seconds. Defaults to 0.6.
        - `max_seconds` number, nullable: The maximum length of a shot in seconds. Defaults to 300.
        - `detector` 'adaptive' | 'content', required: The detector strategy to use: • **adaptive**: Designed for dynamic footage with camera movement, panning, or action. Examples: sports broadcasts, drone footage, handheld documentaries, action movies, live events. • **content**: Optimized for controlled footage with clear visual transitions. Examples: studio interviews, corporate videos, educational content, product demos, scripted content.
        - `fill_gaps` boolean: When true, gaps between detected shots are filled: gaps greater than or equal to min_seconds become their own segments (split by max_seconds if needed), and shorter gaps are merged into the nearest adjacent segment. Defaults to true.
      - `manual_config` SegmentationManualConfig
        - `segments` object[], required: Array of segments
          - `start_time` number: The start time of the segment in seconds
          - `end_time` number: The end time of the segment in seconds
      - `narrative_config` NarrativeConfig
        - `prompt` string: Optional custom prompt to guide the narrative segmentation analysis. This will be incorporated into the main segmentation prompt as additional guidance.
        - `strategy` 'comprehensive' | 'balanced' | 'transcript': Narrative segmentation strategy: • **comprehensive**: Uses a VLM to deeply analyze logical segments of video. Only available for video files (not YouTube or audio). • **balanced** (default): Balanced analysis approach using multiple modalities. Supports YouTube URLs and audio files. • **transcript**: Cheap and fast speech-transcript-based segmentation. Requires a transcript; returns an error for silent or visual-only content (use `balanced` instead, or `comprehensive` for non-YouTube/non-audio video files). **Note**: YouTube URLs and audio files only support the **balanced** and **transcript** strategies; **comprehensive** will be rejected with an error.
        - `number_of_chapters` integer: Optional target number of chapters to generate. If provided, min_chapters and max_chapters will be calculated automatically if not specified. If only target is provided, the AI will attempt to generate exactly this number of chapters.
        - `min_chapters` integer: Optional minimum number of chapters to generate. If provided along with number_of_chapters and max_chapters, validates that min <= number_of_chapters <= max. If only number_of_chapters is provided, min and max are calculated automatically.
        - `max_chapters` integer: Optional maximum number of chapters to generate. If provided along with number_of_chapters and min_chapters, validates that min <= number_of_chapters <= max. If only number_of_chapters is provided, min and max are calculated automatically.
      - `keyframe_config` KeyframeConfig: Configuration for keyframe extraction. When provided, will be used to extract keyframes for the segmentation. This is not supported for YouTube videos.
        - `frames_per_segment` number, required: The number of key frames to extract per segment
        - `max_width` number: The maximum width of the key frames in pixels
      - `start_time_seconds` number: Optional: The start time of the video in seconds to start segmenting from
      - `end_time_seconds` number: Optional: The end time of the video in seconds to stop segmenting at
    - `thumbnails_config` ThumbnailsConfig
      - `enable_segment_thumbnails` boolean, required: Whether to enable segment thumbnails. If not provided will use default to false. Cannot be used together with segmentation_id.
    - `metadata` object: User metadata stored on the file (merged into the file's metadata and included in the indexed metadata doc). Only supported when adding to metadata collections; other collection types take metadata via the Files endpoints.
  - object
    - `url` string, required: The URL of the video to add to the collection. Supports URIs of files uploaded to Cloudglue Files endpoint, public YouTube video URLs, public TikTok video URLs, public Loom share URLs, public HTTP URLs, and files which have been granted access to Cloudglue via data connectors. Note that YouTube videos are currently limited to speech level understanding only. Public TikTok video URLs will be scraped and stored automatically — subject to charges. For files via our Data connectors, see our documentation on data connectors for setup information.
    - `segmentation_id` string, uuid: Segmentation job id to use. If not provided will use default to uniform 20s segmentation. Cannot be provided together with segmentation_config.
    - `segmentation_config` SegmentationConfig: Configuration for video segmentation. **Choose a strategy and provide ONLY the corresponding config:** • **uniform**: Provide `uniform_config`, do NOT provide other configs • **shot-detector**: Provide `shot_detector_config`, do NOT provide other configs • **manual**: Provide `manual_config`, do NOT provide other configs • **narrative**: Provide `narrative_config`, do NOT provide other configs Optionally specify `start_time_seconds` and `end_time_seconds` to limit segmentation to a portion of the video.
      - `strategy` 'uniform' | 'shot-detector' | 'manual' | 'narrative', required: Segmentation strategy - determines which config you must provide
      - `uniform_config` SegmentationUniformConfig
        - `window_seconds` number, required: The duration of each segment in seconds. Must be between 1 and 120 seconds.
        - `hop_seconds` number: The offset between the start of new windows. This means there can be overlap between segments. If not provided, defaults to window_seconds. Must be between 1 and 120 seconds.
      - `shot_detector_config` SegmentationShotDetectorConfig
        - `threshold` number, nullable: Detection sensitivity threshold - lower values create more segments: • **content**: Sensitivity to visual differences (default: 27.0). Lower values detect smaller changes in color/lighting. • **adaptive**: Does not support threshold parameter - uses internal adaptive algorithm.
        - `min_seconds` number, nullable: The minimum length of a shot in seconds. Defaults to 0.6.
        - `max_seconds` number, nullable: The maximum length of a shot in seconds. Defaults to 300.
        - `detector` 'adaptive' | 'content', required: The detector strategy to use: • **adaptive**: Designed for dynamic footage with camera movement, panning, or action. Examples: sports broadcasts, drone footage, handheld documentaries, action movies, live events. • **content**: Optimized for controlled footage with clear visual transitions. Examples: studio interviews, corporate videos, educational content, product demos, scripted content.
        - `fill_gaps` boolean: When true, gaps between detected shots are filled: gaps greater than or equal to min_seconds become their own segments (split by max_seconds if needed), and shorter gaps are merged into the nearest adjacent segment. Defaults to true.
      - `manual_config` SegmentationManualConfig
        - `segments` object[], required: Array of segments
          - `start_time` number: The start time of the segment in seconds
          - `end_time` number: The end time of the segment in seconds
      - `narrative_config` NarrativeConfig
        - `prompt` string: Optional custom prompt to guide the narrative segmentation analysis. This will be incorporated into the main segmentation prompt as additional guidance.
        - `strategy` 'comprehensive' | 'balanced' | 'transcript': Narrative segmentation strategy: • **comprehensive**: Uses a VLM to deeply analyze logical segments of video. Only available for video files (not YouTube or audio). • **balanced** (default): Balanced analysis approach using multiple modalities. Supports YouTube URLs and audio files. • **transcript**: Cheap and fast speech-transcript-based segmentation. Requires a transcript; returns an error for silent or visual-only content (use `balanced` instead, or `comprehensive` for non-YouTube/non-audio video files). **Note**: YouTube URLs and audio files only support the **balanced** and **transcript** strategies; **comprehensive** will be rejected with an error.
        - `number_of_chapters` integer: Optional target number of chapters to generate. If provided, min_chapters and max_chapters will be calculated automatically if not specified. If only target is provided, the AI will attempt to generate exactly this number of chapters.
        - `min_chapters` integer: Optional minimum number of chapters to generate. If provided along with number_of_chapters and max_chapters, validates that min <= number_of_chapters <= max. If only number_of_chapters is provided, min and max are calculated automatically.
        - `max_chapters` integer: Optional maximum number of chapters to generate. If provided along with number_of_chapters and min_chapters, validates that min <= number_of_chapters <= max. If only number_of_chapters is provided, min and max are calculated automatically.
      - `keyframe_config` KeyframeConfig: Configuration for keyframe extraction. When provided, will be used to extract keyframes for the segmentation. This is not supported for YouTube videos.
        - `frames_per_segment` number, required: The number of key frames to extract per segment
        - `max_width` number: The maximum width of the key frames in pixels
      - `start_time_seconds` number: Optional: The start time of the video in seconds to start segmenting from
      - `end_time_seconds` number: Optional: The end time of the video in seconds to stop segmenting at
    - `thumbnails_config` ThumbnailsConfig
      - `enable_segment_thumbnails` boolean, required: Whether to enable segment thumbnails. If not provided will use default to false. Cannot be used together with segmentation_id.
    - `metadata` object: User metadata stored on the file (merged into the file's metadata and included in the indexed metadata doc). Only supported when adding to metadata collections; other collection types take metadata via the Files endpoints.

## Response `200`

Successful file addition

- CollectionFile
  - `collection_id` string, required: ID of the collection
  - `file_id` string, required: ID of the file
  - `object` 'collection_file', required: Object type, always 'collection_file'
  - `added_at` integer, required: Unix timestamp in milliseconds when the file was added to the collection
  - `status` 'pending' | 'processing' | 'completed' | 'failed' | 'not_applicable', required: Overall processing status of the file in this collection
  - `searchable_status` 'pending' | 'processing' | 'completed' | 'failed': Indexing status of the file's search documents in this collection. Only present for media-descriptions, rich-transcripts, metadata, and entities collections. For entities collections it tracks entity indexing: file-level collections index one document per file, segment-level collections one per segment.
  - `file` File
    - `id` string, required: Unique identifier for the file
    - `status` 'pending' | 'processing' | 'completed' | 'failed' | 'not_applicable', required: Processing status of the file
    - `bytes` integer, nullable: Size of the file in bytes, null if not available
    - `created_at` integer: Unix timestamp in milliseconds when the file was created
    - `filename` string: Original filename
    - `uri` string, required: Cloudglue URI for the file, to be used in other API calls
    - `metadata` object, nullable: User-provided metadata about the file, null if none provided
    - `media_type` 'video' | 'audio' | 'image': Type of media file (video, audio, or image). Images are processed at the file level only (no segmentation).
    - `media_info` object: Unified media information for video, audio, and image files
      - `duration_seconds` number, nullable: Duration in seconds
      - `width` integer, nullable: Width in pixels (null for audio files)
      - `height` integer, nullable: Height in pixels (null for audio files)
      - `sample_rate` integer, nullable: Audio sample rate in Hz
      - `channels` integer, nullable: Number of audio channels
      - `bitrate` integer, nullable: Audio bitrate in bps
      - `format` string, nullable: File format
      - `has_audio` boolean, nullable: Whether the file has audio
    - `video_info` object: Information about the video content
      - `duration_seconds` number, nullable: Duration of the video in seconds, null if not available
      - `height` integer, nullable: Height of the video in pixels, null if not available
      - `width` integer, nullable: Width of the video in pixels, null if not available
      - `format` string, nullable: Format of the video file, null if not available
      - `has_audio` boolean, nullable: Whether the video has audio, null if not available
    - `thumbnail_url` string: URL of the thumbnail for the file
    - `source` 'video' | 'youtube' | 's3' | 'dropbox' | 'http' | 'upload' | 'google-drive' | 'zoom' | 'gong' | 'recall' | 'gcs' | 'grain' | 'loom' | 'iconik': Source of the file
    - `source_metadata` union: Per-source provenance captured from the upstream connector, discriminated by source_type. Populated for Grain, Zoom, Recall, Google Drive, Dropbox, Gong, and iconik; files synced before a connector was upgraded carry null. S3/GCS files carry null (plain object stores have no richer metadata).
      - GrainSourceMetadata: Source provenance captured from Grain at ingest time. The richer AI/contextual fields are only present when Grain returns them.
        - `source_type` 'grain', required: Discriminator identifying the upstream connector.
        - `grain_recording_id` string, required: Grain's recording id.
        - `title` string, nullable: Recording title.
        - `start_datetime` string, date-time, nullable: UTC time Grain started the recording.
        - `end_datetime` string, date-time, nullable: UTC time the recording ended.
        - `duration_ms` integer, nullable: Recording duration in milliseconds.
        - `media_type` 'audio' | 'transcript' | 'video', nullable: Grain media type of the recording.
        - `upstream_source` 'aircall' | 'local_capture' | 'meet' | 'teams' | 'upload' | 'webex' | 'zoom' | 'other', nullable: Platform Grain captured the recording from.
        - `grain_url` string, nullable: URL to the recording in Grain.
        - `thumbnail_url` string, nullable: Thumbnail URL, null if none.
        - `tags` string[], nullable: Tags applied to the recording.
        - `teams` object[], nullable: Teams the recording belongs to.
          - `id` string
          - `name` string
        - `meeting_type` object, nullable: Recording's meeting type, null if none.
          - `id` string
          - `name` string
          - `scope` string
        - `participants` object[], nullable: Meeting participants (include-gated by Grain). Null when requested but empty.
          - `id` string
          - `name` string
          - `email` string, nullable
          - `scope` 'internal' | 'external' | 'unknown'
          - `confirmed_attendee` boolean
          - `hs_contact_id` string, nullable: HubSpot contact id, if linked.
        - `highlights` object[], nullable: Clips / highlights (include-gated). Null when requested but empty.
        - `ai_summary` object, nullable: AI summary (include-gated). Null when requested but empty.
          - `text` string: Markdown AI summary.
        - `ai_action_items` object[], nullable: AI action items (include-gated). Null when requested but empty.
          - `status` 'pending' | 'completed'
          - `timestamp_ms` integer: Time in the recording the item was mentioned.
          - `text` string
          - `assignee` object, nullable
            - `id` string
            - `name` string
            - `user_id` string, nullable
        - `ai_template_sections` object[], nullable: AI template sections, shape varies by template (include-gated). Null when requested but empty.
        - `calendar_event` object, nullable: Related calendar event (include-gated).
          - `ical_uid` string
        - `hubspot` object, nullable: Related HubSpot company/deal ids (include-gated). Null when requested but empty.
          - `hubspot_company_ids` string[]
          - `hubspot_deal_ids` string[]
      - ZoomSourceMetadata: Source provenance captured from Zoom at ingest time. Signed download/play URLs, share URLs, and passcodes are never included.
        - `source_type` 'zoom', required: Discriminator identifying the upstream connector.
        - `zoom_meeting_uuid` string, required: Zoom meeting instance UUID.
        - `zoom_meeting_id` integer, nullable: Zoom numeric meeting id.
        - `topic` string, nullable: Meeting topic (empty string when Zoom omits it).
        - `start_time` string, date-time, nullable: UTC time the meeting started.
        - `host_id` string, nullable: Zoom host user id.
        - `host_email` string, nullable: Host email. Nullable whenever Zoom omits it — both list and per-meeting endpoints may return null depending on account scopes.
        - `account_id` string, nullable: Zoom account id.
        - `timezone` string, nullable: Meeting timezone.
        - `duration_minutes` number, nullable: Meeting duration in minutes (as reported by Zoom).
        - `total_size` number, nullable: Total size of all recording files in bytes.
        - `recording_count` number, nullable: Number of recording files for the meeting.
        - `meeting_type` number, nullable: Zoom's numeric meeting type.
        - `recording_files` object[], nullable: Structural facts about each recording file. Download/play URLs are excluded.
          - `id` string, nullable
          - `recording_type` string, nullable: e.g. shared_screen_with_speaker_view, audio_only.
          - `file_type` string, nullable
          - `file_extension` string, nullable
          - `file_size` number, nullable: File size in bytes.
          - `recording_start` string, nullable
          - `recording_end` string, nullable
          - `status` string, nullable
      - RecallSourceMetadata: Source provenance captured from Recall at ingest time. Artifact availability is exposed as booleans — signed artifact download URLs are never included.
        - `source_type` 'recall', required: Discriminator identifying the upstream connector.
        - `recall_recording_id` string, required: Recall recording id.
        - `created_at` string, nullable: UTC time the recording object was created.
        - `started_at` string, nullable: UTC time recording started.
        - `completed_at` string, nullable: UTC time recording completed.
        - `expires_at` string, nullable: UTC time the recording expires upstream at Recall.
        - `status_code` string, nullable: Recall status: done, processing, failed, or paused. Only done recordings can be synced.
        - `meeting_title` string, nullable: Meeting title, when Recall's meeting metadata carries one.
        - `meeting_platform` string, nullable: Meeting platform (e.g. zoom, google_meet), when available.
        - `has_transcript` boolean, nullable: Whether a transcript artifact exists.
        - `has_audio` boolean, nullable: Whether a separate audio artifact exists.
        - `has_participant_events` boolean, nullable: Whether a participant-events artifact exists.
        - `bot_id` string, nullable: Id of the bot that captured the recording.
        - `recall_metadata` object, nullable: Arbitrary caller-supplied metadata attached to the bot/recording in Recall.
      - GoogleDriveSourceMetadata: Source provenance captured from Google Drive at ingest time. Short-lived signed URLs (e.g. thumbnailLink) are never included.
        - `source_type` 'google-drive', required: Discriminator identifying the upstream connector.
        - `gdrive_file_id` string, required: Drive file id.
        - `name` string, nullable: File name.
        - `mime_type` string, nullable
        - `size_bytes` number, nullable
        - `created_time` string, nullable: UTC time the file was created in Drive.
        - `modified_time` string, nullable: UTC time the file was last modified.
        - `web_view_link` string, nullable: Link to view the file in Drive (requires Drive access).
        - `owners` object[], nullable: File owners.
          - `display_name` string, nullable
          - `email_address` string, nullable
        - `last_modifying_user` object, nullable: User who last modified the file.
          - `display_name` string, nullable
          - `email_address` string, nullable
        - `parents` string[], nullable: Parent folder ids.
        - `shared` boolean, nullable: Whether the file is shared.
        - `file_extension` string, nullable
        - `md5_checksum` string, nullable
        - `video_media_metadata` object, nullable: Drive's video metadata, when Drive has processed the file.
          - `duration_millis` number, nullable: Video duration in milliseconds.
          - `width` number, nullable
          - `height` number, nullable
      - DropboxSourceMetadata: Source provenance captured from Dropbox at ingest time.
        - `source_type` 'dropbox', required: Discriminator identifying the upstream connector.
        - `dropbox_id` string, required: Dropbox file id (id:… form).
        - `name` string, nullable: File name.
        - `path_lower` string, nullable: Lowercased path of the file.
        - `path_display` string, nullable: Display-cased path.
        - `size_bytes` number, nullable
        - `client_modified` string, nullable: Modification time reported by the client that uploaded the file.
        - `server_modified` string, nullable: Time the file was last modified on Dropbox.
        - `rev` string, nullable: Dropbox revision id.
        - `content_hash` string, nullable: Dropbox content hash.
        - `is_downloadable` boolean, nullable
        - `media_info` object, nullable: Media dimensions/duration. Only populated at sync/lookup time — Dropbox's list endpoint stopped returning media info in 2019, so items in the list endpoint carry null here.
          - `duration_ms` number, nullable: Media duration in milliseconds.
          - `width` number, nullable
          - `height` number, nullable
      - GongSourceMetadata: Source provenance captured from Gong at ingest time. Signed media URLs are never included. AI content fields (topics, trackers, brief, key_points) require Gong Call Spotlight entitlement and are only captured at sync/lookup time.
        - `source_type` 'gong', required: Discriminator identifying the upstream connector.
        - `gong_call_id` string, required: Gong call id.
        - `title` string, nullable: Call title (empty string when Gong omits it).
        - `started` string, nullable: UTC time the call started.
        - `scheduled` string, nullable: UTC time the call was scheduled for.
        - `duration` number, nullable: Call duration in seconds.
        - `gong_url` string, nullable: URL to the call in Gong.
        - `meeting_url` string, nullable: URL of the underlying meeting.
        - `is_private` boolean, nullable: Whether the call is private in Gong. Private calls cannot be listed or synced.
        - `purpose` string, nullable
        - `primary_user_id` string, nullable: Gong user id of the call owner.
        - `direction` string, nullable: Inbound, Outbound, Conference, or Unknown.
        - `system` string, nullable: Telephony/meeting system the call was held on.
        - `scope` string, nullable: Internal, External, or Unknown.
        - `language` string, nullable: ISO-639-2B language code Gong detected.
        - `workspace_id` string, nullable: Gong workspace id.
        - `call_media_type` string, nullable: Gong's media indicator: Video or Audio.
        - `parties` object[], nullable: Call participants.
          - `id` string, nullable
          - `name` string, nullable
          - `email` string, nullable
          - `affiliation` string, nullable: Internal, External, or Unknown.
          - `speaker_id` string, nullable
          - `user_id` string, nullable
        - `topics` object[], nullable: AI topics (Call Spotlight).
          - `name` string, nullable
          - `duration` number, nullable: Seconds spent on the topic.
        - `trackers` object[], nullable: Tracker keyword hit counts (Call Spotlight).
          - `name` string, nullable
          - `count` number, nullable
        - `brief` string, nullable: AI call brief (Call Spotlight).
        - `key_points` string[], nullable: AI key points (Call Spotlight).
      - IconikSourceMetadata: Source provenance captured from iconik at ingest time. Signed download URLs are never included.
        - `source_type` 'iconik', required: Discriminator identifying the upstream connector.
        - `iconik_asset_id` string, required: iconik asset id.
        - `title` string, nullable: Asset title.
        - `media_type` string, nullable: iconik media type of the asset (e.g. video, audio).
        - `date_created` string, nullable: UTC time the asset was created in iconik.
        - `date_modified` string, nullable: UTC time the asset was last modified in iconik.
        - `duration_ms` number, nullable: Asset duration in milliseconds, when iconik reports one.
        - `ingested_rendition` 'proxy' | 'original', nullable: Which rendition Cloudglue downloaded: the web proxy (preferred) or the ORIGINAL file.
        - `iconik_url` string, nullable: Deep link to the asset page in iconik.
        - `external_id` string, nullable: External reference id set on the asset in iconik.
        - `created_by_user` string, nullable: iconik user id that created the asset.
        - `iconik_metadata` object, nullable: Custom metadata-view field values from iconik (customer-defined schemas, e.g. a screening view's UGC Title / Keywords / Categories), captured verbatim keyed by field name. Indexed into metadata-collection search documents and filterable via source_metadata.iconik_metadata.<FieldName> paths.
  - `segmentation` object: Segmentation information for this file in the collection. Only present when the file has been segmented.
    - `id` string, uuid, required: Unique identifier for the segmentation
    - `status` 'pending' | 'processing' | 'completed' | 'failed' | 'not_applicable', required: Status of the segmentation job
    - `file_id` string, uuid, required: ID of the file that was segmented
    - `segmentation_config` SegmentationConfig, required: Configuration for video segmentation. **Choose a strategy and provide ONLY the corresponding config:** • **uniform**: Provide `uniform_config`, do NOT provide other configs • **shot-detector**: Provide `shot_detector_config`, do NOT provide other configs • **manual**: Provide `manual_config`, do NOT provide other configs • **narrative**: Provide `narrative_config`, do NOT provide other configs Optionally specify `start_time_seconds` and `end_time_seconds` to limit segmentation to a portion of the video.
      - `strategy` 'uniform' | 'shot-detector' | 'manual' | 'narrative', required: Segmentation strategy - determines which config you must provide
      - `uniform_config` SegmentationUniformConfig
        - `window_seconds` number, required: The duration of each segment in seconds. Must be between 1 and 120 seconds.
        - `hop_seconds` number: The offset between the start of new windows. This means there can be overlap between segments. If not provided, defaults to window_seconds. Must be between 1 and 120 seconds.
      - `shot_detector_config` SegmentationShotDetectorConfig
        - `threshold` number, nullable: Detection sensitivity threshold - lower values create more segments: • **content**: Sensitivity to visual differences (default: 27.0). Lower values detect smaller changes in color/lighting. • **adaptive**: Does not support threshold parameter - uses internal adaptive algorithm.
        - `min_seconds` number, nullable: The minimum length of a shot in seconds. Defaults to 0.6.
        - `max_seconds` number, nullable: The maximum length of a shot in seconds. Defaults to 300.
        - `detector` 'adaptive' | 'content', required: The detector strategy to use: • **adaptive**: Designed for dynamic footage with camera movement, panning, or action. Examples: sports broadcasts, drone footage, handheld documentaries, action movies, live events. • **content**: Optimized for controlled footage with clear visual transitions. Examples: studio interviews, corporate videos, educational content, product demos, scripted content.
        - `fill_gaps` boolean: When true, gaps between detected shots are filled: gaps greater than or equal to min_seconds become their own segments (split by max_seconds if needed), and shorter gaps are merged into the nearest adjacent segment. Defaults to true.
      - `manual_config` SegmentationManualConfig
        - `segments` object[], required: Array of segments
          - `start_time` number: The start time of the segment in seconds
          - `end_time` number: The end time of the segment in seconds
      - `narrative_config` NarrativeConfig
        - `prompt` string: Optional custom prompt to guide the narrative segmentation analysis. This will be incorporated into the main segmentation prompt as additional guidance.
        - `strategy` 'comprehensive' | 'balanced' | 'transcript': Narrative segmentation strategy: • **comprehensive**: Uses a VLM to deeply analyze logical segments of video. Only available for video files (not YouTube or audio). • **balanced** (default): Balanced analysis approach using multiple modalities. Supports YouTube URLs and audio files. • **transcript**: Cheap and fast speech-transcript-based segmentation. Requires a transcript; returns an error for silent or visual-only content (use `balanced` instead, or `comprehensive` for non-YouTube/non-audio video files). **Note**: YouTube URLs and audio files only support the **balanced** and **transcript** strategies; **comprehensive** will be rejected with an error.
        - `number_of_chapters` integer: Optional target number of chapters to generate. If provided, min_chapters and max_chapters will be calculated automatically if not specified. If only target is provided, the AI will attempt to generate exactly this number of chapters.
        - `min_chapters` integer: Optional minimum number of chapters to generate. If provided along with number_of_chapters and max_chapters, validates that min <= number_of_chapters <= max. If only number_of_chapters is provided, min and max are calculated automatically.
        - `max_chapters` integer: Optional maximum number of chapters to generate. If provided along with number_of_chapters and min_chapters, validates that min <= number_of_chapters <= max. If only number_of_chapters is provided, min and max are calculated automatically.
      - `keyframe_config` KeyframeConfig: Configuration for keyframe extraction. When provided, will be used to extract keyframes for the segmentation. This is not supported for YouTube videos.
        - `frames_per_segment` number, required: The number of key frames to extract per segment
        - `max_width` number: The maximum width of the key frames in pixels
      - `start_time_seconds` number: Optional: The start time of the video in seconds to start segmenting from
      - `end_time_seconds` number: Optional: The end time of the video in seconds to stop segmenting at

## Other responses

- `400`: Invalid request
- `403`: Usage limit reached (files per collection, or the file limits when adding by URL) — `code: usage_limit_reached`
- `404`: Collection or file not found
- `500`: An unexpected error occurred on the server

## Changes

- **2026-10-30** `23d3f240819f`: 4 info
  - added the non-success response with the status `403`
  - 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-08-12** `725b9736a231`: 1 info
  - added the optional property `searchable_status` to the response with the `200` status
- **2026-07-22** `c02e52ec2e28`: 1 breaking, 1 warning, 2 info
  - added `#/components/schemas/IconikSourceMetadata` to the `file/source_metadata/allOf[#/components/schemas/SourceMetadata]/` response property `oneOf` list for the response status `200`
  - added the new `iconik` enum value to the `file/source` response property for the response status `200`
  - added the new optional request property `allOf[subschema #3]/metadata`
  - added `iconik` discriminator mapping keys to the `file/source_metadata/allOf[#/components/schemas/SourceMetadata]/` response property for the response status `200`
- …earlier changes not shown

[Operation history](https://skmtc.dev/cloudglue/apis/cloudglue-api/changes/collections/:collection_id/videos/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)