POST
/
segments
Create a new video segmentation job
curl --request POST \
  --url https://api.cloudglue.dev/v1/segments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "<string>",
  "criteria": "shot",
  "shot_config": {
    "detector": "adaptive",
    "threshold": 123,
    "max_duration_seconds": 300,
    "min_duration_seconds": 1
  },
  "narrative_config": {
    "prompt": "<string>"
  }
}'
{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "object": "segments",
  "status": "pending",
  "criteria": "shot",
  "created_at": 123,
  "shot_config": {
    "detector": "adaptive",
    "threshold": 123,
    "max_duration_seconds": 300,
    "min_duration_seconds": 1
  },
  "narrative_config": {
    "prompt": "<string>"
  },
  "total_segments": 1,
  "segments": [
    {
      "start_time": 1,
      "end_time": 1,
      "description": "<string>",
      "thumbnail_url": "<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 URL. Supports URIs of files uploaded to Cloudglue Files endpoint, public HTTP URLs, and S3 or Dropbox URIs which have been granted access to Cloudglue via data connectors.

⚠️ Important: YouTube URLs are NOT supported for the segments API. This includes both shot-based and narrative-based segmentation. For S3 and Dropbox URI support 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 • narrative: Identify logical narrative segments and chapters using AI analysis

Available options:
shot,
narrative
​
shot_config
object

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

​
narrative_config
object

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

Response

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 of when the job was created

​
shot_config
object

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

​
narrative_config
object

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

​
total_segments
integer

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

Required range: x >= 0
​
segments
object[]

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