canonical: https://jentic.com/apis/googleapis.com/videointelligence

# Google Cloud Video Intelligence API

The Cloud Video Intelligence API analyzes video stored in Cloud Storage or supplied inline to detect objects, label content, identify shot changes, recognize on-screen text, transcribe speech, and flag explicit content. Annotation is performed asynchronously via long-running operations, with results returned per shot, per frame, or per segment depending on the requested feature. It powers content moderation, video search, and automated metadata pipelines.

## For AI agents

Annotate videos for labels, shots, text, speech, and explicit content so an agent can build searchable metadata or moderate content without running its own ML.

## Scope

Does not handle video editing, transcoding, or live streaming - use for asynchronous video annotation (labels, shots, text, speech, explicit content) only.

## Capabilities

- Annotate a video for object tracking, label detection, and shot change detection
- Run optical character recognition on text that appears on screen across a video
- Transcribe spoken audio in supported languages with timestamps
- Flag explicit content frame-by-frame for moderation pipelines
- Track long-running annotation operations from submission through completion
- Cancel or delete an annotation operation that is no longer needed

## Use cases

### User-Generated Content Moderation

Platforms hosting user uploads run every video through the Video Intelligence API to flag explicit content, violence-adjacent labels, and profanity in transcribed speech before the asset goes live. The annotate endpoint accepts a Cloud Storage URI and returns a per-frame confidence score for each enabled feature, which the moderation pipeline thresholds before approving or routing to human review. This is dramatically faster than running an in-house vision model.

Example prompt: Annotate a Cloud Storage video for EXPLICIT_CONTENT_DETECTION and reject uploads with any frame above 0.8 confidence

### Video Search and Metadata Indexing

Media libraries enrich every uploaded video with label, shot, and OCR annotations so editors can search across footage by subject, scene, or on-screen text. The API returns timestamped annotations that the indexer maps into a search engine document, turning raw video into queryable metadata. Annotation is asynchronous and free of model maintenance overhead.

Example prompt: Submit a videos:annotate request with LABEL_DETECTION, SHOT_CHANGE_DETECTION, and TEXT_DETECTION on a Cloud Storage URI

### Automated Captioning and Transcripts

Publishers generate first-pass captions and searchable transcripts by enabling SPEECH_TRANSCRIPTION on the annotate request. The API returns word-level timing that the captioning pipeline converts into WebVTT or SRT files for upload to a video player. This dramatically reduces editor time on large back-catalogs.

Example prompt: Annotate a video with SPEECH_TRANSCRIPTION and convert the response into a WebVTT caption file

### AI Agent Video Understanding

An AI agent integrated through Jentic answers prompts like 'summarize this clip' by submitting a Video Intelligence annotation, polling the long-running operation, and assembling the labels, shots, and transcripts into a structured summary. Because the API uses OAuth 2.0 with the cloud-platform scope, Jentic isolates the token in your Jentic One instance and exposes only a scoped reference to the agent.

Example prompt: Search Jentic for annotate a video, submit annotation, and poll until the operation completes

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /v1/videos:annotate | Submit an annotation request for one or more features |
| GET | /v1/{+name}/operations | List annotation operations |
| POST | /v1/operations/{+name}:cancel | Cancel a running annotation operation |
| DELETE | /v1/operations/{+name} | Delete a completed operation |

## Key resources

- **Videos** — Submit annotate requests for label, object, shot, text, speech, and explicit content detection
- **Operations** — Track, list, cancel, and delete long-running annotation operations

## Why Jentic

- **Setup:** Wiring the Cloud Video Intelligence API by hand means setting up a Google service account, granting the cloud-platform scope, submitting the annotate request, and polling the long-running operation to completion yourself. Through Jentic you install once, import the Cloud Video Intelligence API from the API Directory, store the service-account credential once, and your agent calls it.
- **Permission scoping:** The video input and requested features travel in the request body, so scope by operation: limit the agent to the operations it needs, such as videos:annotate and reading operation status. You choose the operations it may call, so cancelling or deleting an operation is not included unless you add it.
- **Credential handling:** Your Video Intelligence service-account credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'transcribe a video' or 'detect explicit content', and Jentic returns the videos:annotate operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Cloud Vision API** — Image-level annotation; Video Intelligence is the per-frame, per-shot equivalent for video
- **Cloud Speech-to-Text API** — Audio-only transcription without the rest of the video annotation feature set
- **Cloud Translation API** — Translate transcripts produced by Video Intelligence into other languages
- **Cloud Storage API** — Stage video files in a bucket so Video Intelligence can read them by URI

## FAQ

### What authentication does the Cloud Video Intelligence API use?

The Cloud Video Intelligence API uses OAuth 2.0 with the https://www.googleapis.com/auth/cloud-platform scope. Through Jentic, the OAuth token is stored encrypted in your Jentic One instance and only a scoped reference is exposed to the agent at execution time.

### Can I detect explicit content in videos with the Video Intelligence API?

Yes. Submit a POST /v1/videos:annotate with features set to EXPLICIT_CONTENT_DETECTION. The response (delivered via the long-running operation) contains per-frame likelihood values from VERY_UNLIKELY to VERY_LIKELY that a moderation pipeline can threshold.

### What are the rate limits for the Cloud Video Intelligence API?

Default project quotas allow 5 concurrent annotation operations and 1,000 annotation requests per day, with file-size and length caps documented per feature. Higher quotas can be requested in the Google Cloud Console for production workloads.

### How do I annotate a video through Jentic with the Video Intelligence API?

Install Jentic with pip install jentic, search for annotate a video, load the schema for POST /v1/videos:annotate, then call it with the Cloud Storage URI and the features array. Poll the returned operation name until done is true to retrieve the annotations.

### Does the Video Intelligence API support inline video bytes or only Cloud Storage URIs?

Both. The annotate request accepts inputUri for a Cloud Storage object or inputContent for base64-encoded video bytes up to a per-feature size limit. Cloud Storage is recommended for files over a few megabytes to avoid request timeouts.

### Why is my annotation operation taking so long to complete?

Annotation runtime scales with video length and the number of enabled features. SPEECH_TRANSCRIPTION and OBJECT_TRACKING are the slowest; expect minutes for a 10-minute clip with multiple features enabled. Use GET /v1/{+name}/operations to monitor progress and cancel runs that exceed your budget.

### Can I limit what my agent is allowed to do with the Cloud Video Intelligence API?

Yes. Because you self-host Jentic One, your own rules decide which Video Intelligence operations and credentials the agent may use. Since the video input and requested features travel in the request body, you scope by operation: you can limit the agent to just the calls it needs, such as submitting videos:annotate and reading operation status, and leave out cancelling or deleting operations unless you explicitly add them. The service-account credential stays in your instance and is injected only when a permitted operation runs.