Skip to main content
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",
    "max_duration_seconds": 300,
    "min_duration_seconds": 1
  },
  "narrative_config": {
    "prompt": "<string>",
    "strategy": "balanced",
    "number_of_chapters": 2,
    "min_chapters": 2,
    "max_chapters": 2
  }
}
'
{
  "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",
    "max_duration_seconds": 300,
    "min_duration_seconds": 1
  },
  "narrative_config": {
    "prompt": "<string>",
    "strategy": "balanced",
    "number_of_chapters": 2,
    "min_chapters": 2,
    "max_chapters": 2
  },
  "total_segments": 1,
  "total_shots": 1,
  "segments": [
    {
      "start_time": 1,
      "end_time": 1,
      "description": "<string>",
      "thumbnail_url": "<string>",
      "shot_index": 123
    }
  ],
  "shots": [
    {
      "index": 123,
      "start_time": 1,
      "end_time": 1
    }
  ]
}

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, YouTube URLs (narrative criteria only), and files which have been granted access to Cloudglue via data connectors.

⚠️ Important: YouTube URLs are ONLY supported for narrative-based segmentation. Shot-based segmentation requires direct video file access and does not support YouTube URLs. For YouTube URLs with narrative segmentation, the 'balanced' strategy is automatically used regardless of the strategy field value. Other strategies will be rejected with an error. For files via our Data connectors, 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 (not supported for YouTube URLs) • narrative: Identify logical narrative segments and chapters using AI analysis (supports YouTube URLs)

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
​
total_shots
integer

Total number of shots in the original video (only present when criteria is 'shot')

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

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

​
shots
object[]

Array of shots in the original video (only present when criteria is 'shot')