> ## 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. # Extract from Video > Extract structured data from a video ## OpenAPI ````yaml POST /extract 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: /extract: post: tags: - Extract summary: Create a new extract job description: Extract structured data from a video operationId: createExtract requestBody: description: Extract job parameters content: application/json: schema: $ref: '#/components/schemas/NewExtract' required: true responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Extract' '400': description: Invalid request or missing required prompt/schema content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Extract job not found content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Monthly extract 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: NewExtract: allOf: - required: - url type: object properties: url: description: >- Input media URL. Supports URIs of files uploaded to Cloudglue Files endpoint, public YouTube video URLs, public TikTok video URLs, public Loom share URLs, public HTTP URLs (including direct image URLs such as JPEG/PNG/WebP), 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. type: string prompt: description: >- A natural language prompt describing the data you want to extract. Required if no schema is provided. type: string schema: type: object description: >- A more rigid structure if you already know the JSON layout you want. Required if no prompt is provided. enable_video_level_entities: type: boolean description: >- Whether to extract entities at the video level. Mutually exclusive with enable_segment_level_entities - only one can be true. enable_segment_level_entities: type: boolean description: >- Whether to extract entities at the segment level. Mutually exclusive with enable_video_level_entities - only one can be true. enable_transcript_mode: type: boolean description: >- When enabled, extract entities from transcript only (similar to YouTube path). Useful for speech-heavy content. enable_metadata_mode: type: boolean description: >- When enabled, extract entities from the file's metadata document (filename, file details, user metadata, and connector source metadata) instead of the media content. File-level entities only; flat 1 credit per file; works on metadata-only files without ingesting their media. Mutually exclusive with enable_transcript_mode. thumbnails_config: $ref: '#/components/schemas/ThumbnailsConfig' include_chapters: type: boolean description: >- Include narrative chapters in the response when segmentation strategy is 'narrative'. Only affects cached completed results; newly created pending jobs do not include chapters. default: false include_shots: type: boolean description: >- Include shot boundaries in the response when segmentation strategy is 'shot-detector'. Only affects cached completed results; newly created pending jobs do not include shots. default: false - $ref: '#/components/schemas/FileSegmentationConfig' Extract: required: - job_id - status type: object properties: job_id: type: string status: type: string enum: - pending - processing - completed - failed - not_applicable url: type: string description: The URL of the processed video created_at: type: integer description: Unix timestamp in milliseconds when the job was created extract_config: type: object description: Configuration for automatic entity extraction from videos properties: prompt: type: string description: >- A natural language prompt describing the data to extract. Required if no schema is provided. schema: type: object description: >- A more rigid structure if you already know the JSON layout you want. Required if no prompt is provided. enable_video_level_entities: type: boolean description: >- Whether to extract entities at the video level. Mutually exclusive with enable_segment_level_entities - only one can be true. enable_segment_level_entities: type: boolean description: >- Whether to extract entities at the segment level. Mutually exclusive with enable_video_level_entities - only one can be true. enable_transcript_mode: type: boolean description: >- When enabled, extract entities from transcript only (similar to YouTube path). Useful for speech-heavy content. enable_metadata_mode: type: boolean description: >- When enabled, extract entities from the file's metadata document (filename, file details, user metadata, and connector source metadata) instead of the media content. File-level entities only; flat 1 credit per file; works on metadata-only files without ingesting their media. Mutually exclusive with enable_transcript_mode. segmentation_id: type: string description: The ID of the segmentation job used for this extraction data: description: >- The structured data extracted from the video based on prompt or schema. Only present when status is 'completed'. type: object properties: entities: type: object description: Entities extracted from the video level segment_entities: type: array description: Array of video entities extracted from individual time segments items: type: object properties: start_time: type: number description: Start time of the segment in seconds end_time: type: number description: End time of the segment in seconds entities: type: object description: Entities extracted from the segment thumbnail_url: type: string format: uri description: URL of the segment thumbnail, when available. thumbnail_url: type: string format: uri description: >- URL of the file-level thumbnail for the video. Only present when include_thumbnails=true. total: type: integer description: >- Total number of segment entities available. Only present when status is 'completed'. limit: type: integer description: >- Maximum number of segment entities returned per request. Only present when status is 'completed'. offset: type: integer description: >- Number of segment entities skipped. Only present when status is 'completed'. error: type: string description: Error message if status is 'failed' chapters: type: array description: >- Array of narrative chapters (only present when include_chapters=true and segmentation strategy is 'narrative') items: type: object properties: index: type: integer minimum: 0 start_time: type: number minimum: 0 end_time: type: number minimum: 0 description: type: string required: - index - start_time - end_time - description shots: type: array description: >- Array of shot boundaries (only present when include_shots=true and segmentation strategy is 'shot-detector') items: type: object properties: index: type: integer minimum: 0 start_time: type: number minimum: 0 end_time: type: number minimum: 0 required: - index - start_time - end_time total_chapters: type: integer minimum: 0 description: >- Total number of chapters (only present when include_chapters=true and segmentation strategy is 'narrative') total_shots: type: integer minimum: 0 description: >- Total number of shots (only present when include_shots=true and segmentation strategy is 'shot-detector') Error: required: - error type: object properties: error: type: string ThumbnailsConfig: type: object required: - enable_segment_thumbnails properties: enable_segment_thumbnails: type: boolean description: >- Whether to enable segment thumbnails. If not provided will use default to false. Cannot be used together with segmentation_id. FileSegmentationConfig: type: object properties: segmentation_id: type: string format: uuid description: >- Segmentation job id to use. If not provided will use default to uniform 20s segmentation. Cannot be provided together with segmentation_config. segmentation_config: $ref: '#/components/schemas/SegmentationConfig' description: >- Configuration for video segmentation. Cannot be provided together with segmentation_id. SegmentationConfig: type: object description: >- 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. required: - strategy properties: strategy: type: string enum: - uniform - shot-detector - manual - narrative description: Segmentation strategy - determines which config you must provide uniform_config: $ref: '#/components/schemas/SegmentationUniformConfig' description: >- 🎯 **REQUIRED when strategy = 'uniform'** - Configuration for uniform segmentation. shot_detector_config: $ref: '#/components/schemas/SegmentationShotDetectorConfig' description: >- 🎯 **REQUIRED when strategy = 'shot-detector'** - Configuration for shot detection segmentation. manual_config: $ref: '#/components/schemas/SegmentationManualConfig' description: >- 🎯 **REQUIRED when strategy = 'manual'** - Configuration for manual segmentation. narrative_config: $ref: '#/components/schemas/NarrativeConfig' description: >- 🎯 **REQUIRED when strategy = 'narrative'** - Configuration for narrative-based chapter segmentation using AI analysis. keyframe_config: $ref: '#/components/schemas/KeyframeConfig' description: >- When provided, will be used to extract keyframes for the segmentation. start_time_seconds: type: number minimum: 0 description: >- Optional: The start time of the video in seconds to start segmenting from end_time_seconds: type: number minimum: 0 description: 'Optional: The end time of the video in seconds to stop segmenting at' SegmentationUniformConfig: type: object required: - window_seconds properties: window_seconds: type: number minimum: 1 maximum: 120 description: >- The duration of each segment in seconds. Must be between 1 and 120 seconds. hop_seconds: type: number minimum: 1 maximum: 120 description: >- 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. SegmentationShotDetectorConfig: type: object required: - detector properties: threshold: type: number nullable: true description: >- 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: type: number minimum: 0.6 maximum: 600 nullable: true description: The minimum length of a shot in seconds. Defaults to 0.6. max_seconds: type: number minimum: 1 maximum: 600 nullable: true description: The maximum length of a shot in seconds. Defaults to 300. detector: type: string enum: - adaptive - content description: >- 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: type: boolean description: >- 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. SegmentationManualConfig: type: object required: - segments properties: segments: type: array items: type: object properties: start_time: type: number description: The start time of the segment in seconds end_time: type: number description: The end time of the segment in seconds description: Array of segments 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. KeyframeConfig: type: object required: - frames_per_segment description: >- Configuration for keyframe extraction. When provided, will be used to extract keyframes for the segmentation. This is not supported for YouTube videos. properties: frames_per_segment: type: number minimum: 0 maximum: 8 description: The number of key frames to extract per segment max_width: type: number minimum: 144 maximum: 4320 description: The maximum width of the key frames in pixels securitySchemes: bearerAuth: type: http scheme: bearer ````