Videos API

All video endpoints live under

/api/v1/videos

Endpoints

```
POST /api/v1/videos/process
```
```
POST /api/v1/videos/process-sync
```
admin-only
```
GET /api/v1/videos/status/{job_id}
```
```
GET /api/v1/videos/result/{job_id}
```
```
GET /api/v1/videos/export/{job_id}/pdf
```
```
GET /api/v1/videos/
```
```
GET /api/v1/videos/thumbnails
```

POST /api/v1/videos/process

Request body:

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "options": {
    "max_transcript_length": 10000000,
    "include_comments": false,
    "language": "en",
    "summary_modes": ["tldr", "detailed"],
    "generate_infographic": false
  },
  "webhook_url": "https://example.com/webhook",
  "priority": "normal",
  "custom_instructions": "Pro only",
  "use_proxy": null,
  "force_refresh": false,
  "service_name": "optional",
  "agent_name": "optional",
  "client_reference": "optional"
}

Rules:

free plan supports
```
tldr
```
only
```
priority=high
```
requires Pro/Admin
```
webhook_url
```
requires Pro/Admin
```
custom_instructions
```
requires Pro/Admin
```
options.generate_infographic=true
```
requires Pro/Admin and may still be runtime-disabled

Summary Modes

```
tldr
```
```
detailed
```
```
study_notes
```
```
timestamped
```
```
key_insights
```

POST /api/v1/videos/process-sync

This endpoint exists, but it is admin-only and requires an API key with the

admin

permission.

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

Returns:

```
job_id
```
```
status
```
```
progress_percentage
```
```
current_step
```
```
estimated_time_remaining
```
```
video_id
```
```
video_url
```
timestamps
optional attribution fields like
```
service_name
```
,
```
agent_name
```
,
```
client_reference
```

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

Returns:

```
video_info
```
```
transcript
```
```
summaries
```
keyed by mode
```
infographic_url
```
```
processing_time
```
```
completed_at
```
optional attribution fields

If the job is not finished yet, the API returns

success: false

with

JOB_NOT_COMPLETED

GET /api/v1/videos/export/{job_id}/pdf

Downloads a PDF export for a completed job.

requires ownership of the job
requires Pro/Admin plan

GET /api/v1/videos/

Lists the authenticated user's jobs.

Query parameters:

```
limit
```
```
offset
```
```
status
```

GET /api/v1/videos/thumbnails

Query string:

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

This endpoint uses the same auth dependency as the rest of the public video router. In local development with

REQUIRE_API_AUTH=false

it can be called anonymously, but in production it should be treated as authenticated.