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.