---
title: "Create a new transcription job"
method: POST
path: "/transcribe"
tags: ["Transcribe"]
---

# Create a new transcription job

`POST /transcribe`

## Request

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

Creates a new transcription job for video content.

Note: For most use cases, you should use the `/describe` endpoint instead. This API will be deprecated in the future and only supports speech level understanding.

## Request body

- NewTranscribe
  - `url` string, required: Input video 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, 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.
  - `enable_summary` boolean: Whether to generate video-level and segment-level (moment-level) summaries and titles
  - `enable_speech` boolean: Whether to generate speech transcript
  - `enable_visual_scene_description` boolean: Whether to generate visual scene description
  - `enable_scene_text` boolean: Whether to generate scene text extraction
  - `enable_audio_description` boolean: Whether to generate audio description
  - `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.
  - `include_metadata` boolean: Include the file's user-defined metadata and source metadata on the returned `file` object.
  - `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

## Response `200`

Successful response

- Transcribe
  - `job_id` string, required
  - `status` 'pending' | 'processing' | 'completed' | 'failed' | 'not_applicable', required
  - `url` string: The URL of the processed video
  - `created_at` integer: Unix timestamp in milliseconds when the job was created
  - `transcribe_config` object: Configuration for rich transcription from videos
    - `enable_summary` boolean: Whether the user requested to generate video-level and segment-level (moment-level) summaries and titles
    - `enable_speech` boolean: Whether the user requested to generate speech transcript
    - `enable_visual_scene_description` boolean: Whether the user requested to generate visual scene description
    - `enable_scene_text` boolean: Whether the user requested to generate scene text
  - `data` object
    - `content` string: Content string returned based on formatting, e.g. set to markdown text when response_format=markdown is requested
    - `title` string: Generated title of the video; for YouTube videos, this is the title of the video as it appears on YouTube
    - `summary` string: Generated video level summary; for YouTube videos, this is the summary of the video as it appears on YouTube
    - `segment_summary` object[]: Array of summary information for each segment of the video. Only available when enable_summary is set to true in the transcribe configuration.
      - `title` string: Generated segment-level title
      - `summary` string: Generated segment-level summary
      - `start_time` number: Start time of segment in seconds
      - `end_time` number: End time of segment in seconds
    - `visual_scene_description` DescribeOutputPart[]: Array of visual descriptions
      - `text` string: Text content
      - `start_time` number: Start time in seconds
      - `end_time` number: End time in seconds
    - `scene_text` DescribeOutputPart[]: Array of scene text extractions
      - `text` string: Text content
      - `start_time` number: Start time in seconds
      - `end_time` number: End time in seconds
    - `speech` SpeechOutputPart[]: Array of speech transcriptions
      - `speaker` string: Identified speaker
      - `text` string: Transcribed speech text
      - `start_time` number: Start time of speech in seconds
      - `end_time` number: End time of speech in seconds
      - `words` WordTimestamp[]: Word-level timestamps. Only present when include_word_timestamps=true. Not available for YouTube sources.
        - `word` string, required: The word text
        - `start_time` number, required: Start time of the word in seconds
        - `end_time` number, required: End time of the word in seconds
    - `audio_description` DescribeOutputPart[]: Array of audio descriptions
      - `text` string: Text content
      - `start_time` number: Start time in seconds
      - `end_time` number: End time in seconds
  - `error` string: Error message if status is 'failed'
  - `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.

## Other responses

- `400`: Invalid request or missing required url/file_id
- `403`: Usage limit reached (monthly describe jobs, or the file limits when given a new URL) — `code: usage_limit_reached`
- `404`: File not found
- `509`: Monthly transcription jobs limit reached

## 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-07-22** `c02e52ec2e28`: 2 info
  - added the new optional request property `allOf[subschema #1]/include_metadata`
  - added the optional property `file` to the response with the `200` status
- **2026-06-12** `f90a8032c6ae`: 1 info
  - the `allOf[#/components/schemas/FileSegmentationConfig]/segmentation_config/shot_detector_config/min_seconds` request property's min was decreased from `1.00` to `0.60`
- **2026-04-27** `43191ed5a246`: 1 info
  - added the new `transcript` enum value to the request property `allOf[#/components/schemas/FileSegmentationConfig]/segmentation_config/narrative_config/strategy`
- **2026-03-11** `1d5d6115c0d0`: 11 info
  - the `enable_audio_description` request property default value `false` was removed
  - the `enable_scene_text` request property default value `false` was removed
  - the `enable_speech` request property default value `true` was removed
  - the `enable_summary` request property default value `true` was removed
  - …7 more

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