> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloudglue.dev/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml POST /segments openapi: 3.0.0 info: title: Cloudglue API description: API for Cloudglue license: name: Apache License 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 version: 0.7.13 servers: - url: https://api.cloudglue.dev/v1 security: - bearerAuth: [] paths: /segments: post: tags: - Segments summary: Create a new segmentation job description: >- 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. operationId: createSegments requestBody: description: Segmentation job parameters content: application/json: schema: $ref: '#/components/schemas/NewSegments' required: true responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Segments' '400': description: >- 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) content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: File not found content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Monthly segments jobs limit reached content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: An unexpected error occurred on the server content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: NewSegments: type: object required: - url - criteria properties: url: type: string description: >- 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: type: string enum: - shot - narrative description: >- 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: $ref: '#/components/schemas/ShotConfig' description: >- Configuration for shot-based segmentation. Only provide when criteria is 'shot'. narrative_config: $ref: '#/components/schemas/NarrativeConfig' description: >- Configuration for narrative-based segmentation. Only provide when criteria is 'narrative'. Segments: type: object required: - file_id - job_id - object - status - criteria - created_at properties: job_id: type: string format: uuid description: Unique identifier for the segment job file_id: type: string format: uuid description: ID of the file this segment belongs to object: type: string enum: - segments description: Object type, always 'segments' status: type: string enum: - pending - processing - completed - failed description: Current status of the segment job criteria: type: string enum: - shot - narrative description: Segment criteria used for this job created_at: type: integer description: Unix timestamp in milliseconds when the job was created shot_config: $ref: '#/components/schemas/ShotConfig' description: >- Configuration used for shot-based segmentation (only present when criteria is 'shot') narrative_config: $ref: '#/components/schemas/NarrativeConfig' description: >- Configuration used for narrative-based segmentation (only present when criteria is 'narrative') total_segments: type: integer minimum: 0 description: >- Total number of segments generated (only present when status is 'completed') total_shots: type: integer minimum: 0 description: >- Total number of shots in the original video (only present when criteria is 'shot') total_chapters: type: integer minimum: 0 description: >- Total number of chapters in the video (only present when criteria is 'narrative') segments: type: array description: >- Array of generated segments (only present when status is 'completed') items: $ref: '#/components/schemas/Segment' shots: type: array description: >- Array of shots in the original video (only present when criteria is 'shot') items: $ref: '#/components/schemas/Shot' chapters: type: array description: >- Array of narrative chapters in the video (only present when criteria is 'narrative') items: $ref: '#/components/schemas/Chapter' Error: required: - error type: object properties: error: type: string ShotConfig: type: object properties: detector: type: string enum: - content - adaptive description: >- 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: type: number minimum: 1 maximum: 600 description: >- Maximum duration for each segment in seconds (1 second to 10 minutes, default: 5 minutes) min_duration_seconds: type: number minimum: 0.6 maximum: 600 description: >- Minimum duration for each segment in seconds (0.6 seconds to 10 minutes, default: 0.6 seconds) fill_gaps: type: boolean description: >- 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. NarrativeConfig: type: object properties: prompt: type: string description: >- Optional custom prompt to guide the narrative segmentation analysis. This will be incorporated into the main segmentation prompt as additional guidance. strategy: type: string enum: - comprehensive - balanced - transcript description: >- 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: type: integer minimum: 1 description: >- 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: type: integer minimum: 1 description: >- 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: type: integer minimum: 1 description: >- 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. Segment: type: object required: - start_time - end_time properties: start_time: type: number minimum: 0 description: Start time of the segment in seconds end_time: type: number minimum: 0 description: End time of the segment in seconds description: type: string description: >- Optional description of the segment content (available for narrative segmentation) thumbnail_url: type: string format: uri description: Optional URL of the thumbnail for this segment shot_index: type: integer description: >- Index of the shot in the original video segmentation. Only present when criteria is set to 'shot' Shot: type: object required: - index - start_time - end_time properties: index: type: integer description: Index of the shot in the original video start_time: type: number minimum: 0 description: Start time of the shot in seconds end_time: type: number minimum: 0 description: End time of the shot in seconds Chapter: type: object required: - index - start_time - end_time - description properties: index: type: integer description: Index of the chapter in the video start_time: type: number minimum: 0 description: Start time of the chapter in seconds end_time: type: number minimum: 0 description: End time of the chapter in seconds description: type: string description: AI-generated description of the chapter content securitySchemes: bearerAuth: type: http scheme: bearer ````