Introduction
What the API does
YAHO is Pyler's public video-understanding API. You hand it a video; it splits the video into scenes and runs each scene through scene detection, captioning, embedding and moderation. The result is structured data you can query instead of a video file you have to watch.
Every scene carries:
- A caption, the transcript for that span, and on-screen text
- Detected brands, product categories, people, locations, actions and weather
- Mood (
valence/arousal), music mood and audio events - GARM brand-safety categories
- Presigned keyframe and clip URLs
Every video carries a summary, genre, IAB content and audience categories, and a per-category GARM assessment (high / medium / low) with the time ranges behind it.
On top of that index you can:
| Capability | Endpoints |
|---|---|
| Index videos by URL, file upload, batch or sheet | POST /api/v1/videos, POST /api/v1/videos/upload, POST /api/v1/videos/batch/* |
| Read scenes and analysis | GET /api/v1/videos/{video_id}, GET /api/v1/videos/{video_id}/scenes |
| Search by natural language, image or audio | POST /api/v1/search, POST /api/v1/search/multimodal, POST /api/v1/search/deep |
| Screen an ad creative for brand safety | POST /api/v1/ad-blocking, POST /api/v1.1/ad-blocking |
| Match an ad to videos | POST /api/v1/ads/match |
| Monitor HLS live streams | /api/v1/live/* |
| Check your organization's quota | GET /api/v1/usage |
Base URL and versions
All requests go to:
https://video.pyler.ai
There are two version roots. Both accept the same API key.
| Root | Contents |
|---|---|
/api/v1 | Every core route: indexing, jobs, scenes, search, ads, brand safety, live, usage. |
/api/v1.1 | Routes that take an already-registered ad_id as input. Today that is POST /api/v1.1/ad-blocking and GET /api/v1.1/ad-blocking. The v1 routes are unchanged. |
Indexing is asynchronous. POST /api/v1/videos returns 202 Accepted with a job_id; poll GET /api/v1/jobs/{job_id} until status is done or failed.
Streaming endpoints
A few endpoints return NDJSON (one JSON object per line) instead of a single document, so you can use partial results while the multi-stage pipeline is still running. Parse the body line by line.
POST /api/v1/ads/matchGET /api/v1/videos/{video_id}/scenes/streamPOST /api/v1/searchwhenjudge: "text"is setGET /api/v1/live/streams/{stream_id}/events
Next steps
Submit a video, poll the job, read its scenes and run your first search.
Get an API key from the dashboard and send it as a bearer token.
The error envelope, validation errors and when to retry.
What is stored, signed URL expiry, how to delete data, and how to treat AI output.
Every endpoint with request and response schemas and a live playground.
After you sign in to the dashboard, an interactive Swagger UI generated from the same OpenAPI document is available at video.pyler.ai/api-docs.