Videos API

The video API lives under

/api/v1/videos

Endpoints

```
POST /api/v1/videos/process
```
– enqueue async processing
```
POST /api/v1/videos/process-sync
```
– inline processing (admin only)
```
GET /api/v1/videos/status/{job_id}
```
– polling status
```
GET /api/v1/videos/result/{job_id}
```
– retrieve completed results
```
GET /api/v1/videos/
```
– list jobs
```
GET /api/v1/videos/thumbnails
```
– fetch thumbnails for a YouTube URL

POST

/api/v1/videos/process

Request body

```
video_url
```
(required)
```
summary_mode
```
```
webhook_url
```
(Pro)
```
custom_instructions
```
(Pro)
```
options.generate_infographic=true
```
(Pro)
```
priority
```
(
```
low|normal|high
```
;
```
high
```
requires Pro)

Plans enforce feature availability. In particular, the free plan supports

tldr

only.

When plan or usage limits are exceeded, the API returns

FEATURE_NOT_AVAILABLE

QUOTA_EXCEEDED

with a non-200 status.

Example

{
  "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "summary_mode": "tldr",
  "custom_instructions": "Keep it concise"
}

Response

{
  "success": true,
  "data": {
    "job_id": "7f9f6f",
    "status": "queued",
    "created_at": "2026-02-13T10:00:00Z"
  }
}

POST

/api/v1/videos/process-sync

Processes synchronously in the same request context and is restricted to admin users.

GET

/api/v1/videos/status/{job_id}

Response shape

{
  "success": true,
  "data": {
    "job_id": "7f9f6f",
    "status": "completed",
    "video_id": "dQw4w9WgXcQ",
    "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "summary_mode": "tldr",
    "created_at": "2026-02-13T10:00:00Z",
    "started_at": "2026-02-13T10:00:02Z",
    "completed_at": "2026-02-13T10:00:10Z",
    "processing_time": 8.2
  }
}

GET

/api/v1/videos/result/{job_id}

Returns final output once completed.

{
  "success": true,
  "data": {
    "job_id": "7f9f6f",
    "status": "completed",
    "video_info": {
      "title": "Example title",
      "duration": 312
    },
    "summaries": ["Concise output"],
    "infographic_url": "https://.../infographic.png",
    "processing_time": 8.2
  }
}

If the result is requested before completion, expect

JOB_NOT_COMPLETED

GET

/api/v1/videos/

(list)

Returns a paginated list with stats.

{
  "success": true,
  "data": {
    "jobs": [],
    "total": 0,
    "limit": 20,
    "offset": 0,
    "has_more": false,
    "stats": {
      "completed": 4,
      "processing": 1,
      "failed": 0
    }
  }
}

GET

/api/v1/videos/thumbnails

Returns thumbnail candidates for a given YouTube URL. This endpoint is not authentication-gated.

GET /api/v1/videos/thumbnails?video_url=https://www.youtube.com/watch?v=dQw4w9WgXcQ