---
title: "Create a new segmentation job"
method: POST
path: "/segments"
tags: ["Segments"]
---

# Create a new segmentation job

`POST /segments`

## Request

- Base URL: `https://api.cloudglue.dev/v1`
- URL: `https://api.cloudglue.dev/v1/segments`
- Auth: HTTP bearer

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.

## Request body

- NewSegments
  - `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` 'shot' | 'narrative', 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)
  - `shot_config` ShotConfig
    - `detector` 'content' | 'adaptive': Detection algorithm: • **adaptive**: Designed for dynamic footage with camera movement and action (default) • **content**: Optimized for controlled footage with clear visual transitions
    - `max_duration_seconds` number: Maximum duration for each segment in seconds (1 second to 10 minutes, default: 5 minutes)
    - `min_duration_seconds` number: Minimum duration for each segment in seconds (0.6 seconds to 10 minutes, default: 0.6 seconds)
    - `fill_gaps` boolean: When true, gaps between detected shots are filled: gaps greater than or equal to min_duration_seconds become their own segments (split by max_duration_seconds if needed), and shorter gaps are merged into the nearest adjacent segment. Defaults to true.
  - `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.

## Response `200`

Successful response

- Segments
  - `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` 'segments', required: Object type, always 'segments'
  - `status` 'pending' | 'processing' | 'completed' | 'failed', required: Current status of the segment job
  - `criteria` 'shot' | 'narrative', required: Segment criteria used for this job
  - `created_at` integer, required: Unix timestamp in milliseconds when the job was created
  - `shot_config` ShotConfig
    - `detector` 'content' | 'adaptive': Detection algorithm: • **adaptive**: Designed for dynamic footage with camera movement and action (default) • **content**: Optimized for controlled footage with clear visual transitions
    - `max_duration_seconds` number: Maximum duration for each segment in seconds (1 second to 10 minutes, default: 5 minutes)
    - `min_duration_seconds` number: Minimum duration for each segment in seconds (0.6 seconds to 10 minutes, default: 0.6 seconds)
    - `fill_gaps` boolean: When true, gaps between detected shots are filled: gaps greater than or equal to min_duration_seconds become their own segments (split by max_duration_seconds if needed), and shorter gaps are merged into the nearest adjacent segment. Defaults to true.
  - `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.
  - `total_segments` integer: Total number of segments generated (only present when status is 'completed')
  - `total_shots` integer: Total number of shots in the original video (only present when criteria is 'shot')
  - `total_chapters` integer: Total number of chapters in the video (only present when criteria is 'narrative')
  - `segments` Segment[]: Array of generated segments (only present when status is 'completed')
    - `start_time` number, required: Start time of the segment in seconds
    - `end_time` number, required: End time of the segment in seconds
    - `description` string: Optional description of the segment content (available for narrative segmentation)
    - `thumbnail_url` string, uri: Optional URL of the thumbnail for this segment
    - `shot_index` integer: Index of the shot in the original video segmentation. Only present when criteria is set to 'shot'
  - `shots` Shot[]: Array of shots in the original video (only present when criteria is 'shot')
    - `index` integer, required: Index of the shot in the original video
    - `start_time` number, required: Start time of the shot in seconds
    - `end_time` number, required: End time of the shot in seconds
  - `chapters` Chapter[]: Array of narrative chapters in the video (only present when criteria is 'narrative')
    - `index` integer, required: Index of the chapter in the video
    - `start_time` number, required: Start time of the chapter in seconds
    - `end_time` number, required: End time of the chapter in seconds
    - `description` string, required: AI-generated description of the chapter content

## Other responses

- `400`: Invalid request, missing required parameters, unsupported URL type (e.g., YouTube URLs with shot-based segmentation), or unsupported strategy for YouTube URLs and audio files (only 'balanced' and 'transcript' are accepted)
- `403`: Usage limit reached (monthly segments jobs, or the file limits when given a new URL) — `code: usage_limit_reached`
- `404`: File not found
- `500`: An unexpected error occurred on the server

## Changes

- **2026-10-30** `23d3f240819f`: 5 info
  - added the non-success response with the status `403`
  - removed the non-success response with the status `429`
  - added the optional property `code` to the response with the `400` status
  - added the optional property `code` to the response with the `404` status
  - …1 more
- **2026-06-12** `f90a8032c6ae`: 3 breaking, 3 info
  - the `shot_config/min_duration_seconds` response property's min was decreased from `1.00` to `0.60` for the response status `200`
  - the `shot_config/max_duration_seconds` response's property type changed from `integer` to `number` for status `200`
  - the `shot_config/min_duration_seconds` response's property type changed from `integer` to `number` for status `200`
  - the `shot_config/min_duration_seconds` request property's min was decreased from `1.00` to `0.60`
  - …2 more
- **2026-04-27** `43191ed5a246`: 1 warning, 1 info
  - added the new `transcript` enum value to the `narrative_config/strategy` response property for the response status `200`
  - added the new `transcript` enum value to the request property `narrative_config/strategy`
- **2026-03-11** `1d5d6115c0d0`: 10 info
  - the `detector` request property default value `adaptive` was removed
  - the `fill_gaps` request property default value `true` was removed
  - the `max_duration_seconds` request property default value `300` was removed
  - the `min_duration_seconds` request property default value `1` was removed
  - …6 more
- …earlier changes not shown

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