Segment Video

Create intelligent segments for video or audio files based on shot detection or narrative analysis.

Audio File Support:

• Audio files support narrative criteria only (shot detection is not available for audio).
• Audio files default to the ‘balanced’ strategy and may opt into ‘transcript’.

Note: YouTube URLs and audio files are supported for narrative-based segmentation only. Shot-based segmentation requires direct video file access. Use Cloudglue Files, HTTP URLs, or files from data connectors for shot-based segmentation.

Narrative Segmentation Strategies:

• comprehensive (default for non-YouTube/non-audio files): Uses a VLM to deeply analyze logical segments of video. Only available for video files (not YouTube or audio).
• balanced (default for YouTube videos and audio files): Balanced analysis approach using multiple modalities. Supports YouTube URLs and audio files.
• transcript: Cheap and fast speech-transcript-based segmentation. Requires a transcript and returns an error when none is available — use balanced for silent or visual-only content (or comprehensive for non-YouTube/non-audio video files).

YouTube URLs and Audio Files: Only the ‘balanced’ and ‘transcript’ strategies are accepted. ‘comprehensive’ will be rejected with an error.

Chapter Count Parameters:

• number_of_chapters: Target number of chapters. If only this is provided, min_chapters and max_chapters are calculated automatically.
• min_chapters: Minimum number of chapters. If provided with number_of_chapters and max, validates min is less than or equal to number_of_chapters which is less than or equal to max.
• max_chapters: Maximum number of chapters. If provided with number_of_chapters and min, validates min is less than or equal to number_of_chapters which is less than or equal to max.
• If none are provided, chapter counts are calculated automatically based on file duration.

POST /segments

Create a new segmentation job

cURL

curl --request POST \
  --url https://api.cloudglue.dev/v1/segments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "shot_config": {
    "max_duration_seconds": 300,
    "min_duration_seconds": 300,
    "fill_gaps": true
  },
  "narrative_config": {
    "prompt": "<string>",
    "number_of_chapters": 2,
    "min_chapters": 2,
    "max_chapters": 2
  }
}
'

200

{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": 123,
  "shot_config": {
    "max_duration_seconds": 300,
    "min_duration_seconds": 300,
    "fill_gaps": true
  },
  "narrative_config": {
    "prompt": "<string>",
    "number_of_chapters": 2,
    "min_chapters": 2,
    "max_chapters": 2
  },
  "total_segments": 1,
  "total_shots": 1,
  "total_chapters": 1,
  "segments": [
    {
      "start_time": 1,
      "end_time": 1,
      "description": "<string>",
      "thumbnail_url": "<string>",
      "shot_index": 123
    }
  ],
  "shots": [
    {
      "index": 123,
      "start_time": 1,
      "end_time": 1
    }
  ],
  "chapters": [
    {
      "index": 123,
      "start_time": 1,
      "end_time": 1,
      "description": "<string>"
    }
  ]
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Segmentation job parameters

url · string · required

Input video or audio file URL. Supports URIs of files uploaded to Cloudglue Files endpoint, public HTTP URLs, YouTube URLs (narrative criteria only), public TikTok video URLs, public Loom share URLs, and files which have been granted access to Cloudglue via data connectors.

⚠️ Important: YouTube URLs and audio files are ONLY supported for narrative-based segmentation. Shot-based segmentation requires direct video file access and does not support YouTube URLs or audio files. For YouTube URLs and audio files with narrative segmentation, only the 'balanced' and 'transcript' strategies are accepted; the 'comprehensive' strategy will be rejected with an error. 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.

criteria · enum<string> · required

Segmentation criteria: • shot: Detect scene changes and shot boundaries using computer vision (not supported for YouTube URLs or audio files) • narrative: Identify logical narrative segments and chapters using AI analysis (supports YouTube URLs and audio files)

Available options: shot, narrative

shot_config · object

Configuration for shot-based segmentation. Only provide when criteria is 'shot'.

Show child attributes

narrative_config · object

Configuration for narrative-based segmentation. Only provide when criteria is 'narrative'.

Show child attributes

Response

200

application/json

Successful response

job_id · string<uuid> · required

Unique identifier for the segment job

file_id · string<uuid> · required

ID of the file this segment belongs to

object · enum<string> · required

Object type, always 'segments'

Available options: segments

status · enum<string> · required

Current status of the segment job

Available options: pending, processing, completed, failed

criteria · enum<string> · required

Segment criteria used for this job

Available options: shot, narrative

created_at · integer · required

Unix timestamp in milliseconds when the job was created

shot_config · object

Configuration used for shot-based segmentation (only present when criteria is 'shot')

Show child attributes

narrative_config · object

Configuration used for narrative-based segmentation (only present when criteria is 'narrative')

Show child attributes

total_segments · integer

Total number of segments generated (only present when status is 'completed')

Required range: x >= 0

total_shots · integer

Total number of shots in the original video (only present when criteria is 'shot')

Required range: x >= 0

total_chapters · integer

Total number of chapters in the video (only present when criteria is 'narrative')

Required range: x >= 0

segments · object[]

Array of generated segments (only present when status is 'completed')

Show child attributes

shots · object[]

Array of shots in the original video (only present when criteria is 'shot')

Show child attributes

chapters · object[]

Array of narrative chapters in the video (only present when criteria is 'narrative')

Show child attributes