# Method: videos.annotate

- [HTTP request](https://docs.cloud.google.com/video-intelligence/docs/reference/rest/v1beta1/videos/annotate#body.HTTP_TEMPLATE)
- [Request body](https://docs.cloud.google.com/video-intelligence/docs/reference/rest/v1beta1/videos/annotate#body.request_body)
  - [JSON representation](https://docs.cloud.google.com/video-intelligence/docs/reference/rest/v1beta1/videos/annotate#body.request_body.SCHEMA_REPRESENTATION)
- [Response body](https://docs.cloud.google.com/video-intelligence/docs/reference/rest/v1beta1/videos/annotate#body.response_body)
- [Authorization Scopes](https://docs.cloud.google.com/video-intelligence/docs/reference/rest/v1beta1/videos/annotate#body.aspect)

Performs asynchronous video annotation. Progress and results can be retrieved through the `google.longrunning.Operations` interface. `Operation.metadata` contains `AnnotateVideoProgress` (progress). `Operation.response` contains `AnnotateVideoResponse` (results).

### HTTP request

`POST https://videointelligence.googleapis.com/v1beta1/videos:annotate`

The URL uses [Google API HTTP annotation](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto) syntax.

### Request body

The request body contains data with the following structure:

| JSON representation ||
|---|---|
| ``` { "inputUri": string, "inputContent": string, "features": [ enum(`https://docs.cloud.google.com/video-intelligence/docs/reference/rest/v1beta1/videos#Feature`) ], "videoContext": { object(`https://docs.cloud.google.com/video-intelligence/docs/reference/rest/v1beta1/videos#VideoContext`) }, "outputUri": string, "locationId": string } ``` |

| Fields ||
|---|---|
| `inputUri` | `string` Input video location. Currently, only [Google Cloud Storage](https://cloud.google.com/storage/) URIs are supported, which must be specified in the following format: `gs://bucket-id/object-id` (other URI formats return `https://docs.cloud.google.com/video-intelligence/docs/reference/rest/Shared.Types/Code#ENUM_VALUES.INVALID_ARGUMENT`). For more information, see [Request URIs](https://docs.cloud.google.com/storage/docs/reference-uris). A video URI may include wildcards in `object-id`, and thus identify multiple videos. Supported wildcards: '\*' to match 0 or more characters; '?' to match 1 character. If unset, the input video should be embedded in the request as `inputContent`. If set, `inputContent` should be unset. |
| `inputContent` | `string` The video data bytes. Encoding: base64. If unset, the input video(s) should be specified via `inputUri`. If set, `inputUri` should be unset. |
| `features[]` | ``enum(`https://docs.cloud.google.com/video-intelligence/docs/reference/rest/v1beta1/videos#Feature`)`` Requested video annotation features. |
| `videoContext` | ``object(`https://docs.cloud.google.com/video-intelligence/docs/reference/rest/v1beta1/videos#VideoContext`)`` Additional video context and/or feature-specific parameters. |
| `outputUri` | `string` Optional location where the output (in JSON format) should be stored. Currently, only [Google Cloud Storage](https://cloud.google.com/storage/) URIs are supported, which must be specified in the following format: `gs://bucket-id/object-id` (other URI formats return `https://docs.cloud.google.com/video-intelligence/docs/reference/rest/Shared.Types/Code#ENUM_VALUES.INVALID_ARGUMENT`). For more information, see [Request URIs](https://docs.cloud.google.com/storage/docs/reference-uris). |
| `locationId` | `string` Optional cloud region where annotation should take place. Supported cloud regions: `us-east1`, `us-west1`, `europe-west1`, `asia-east1`. If no region is specified, a region will be determined based on video file location. |

### Response body

If successful, the response body contains an instance of `https://docs.cloud.google.com/video-intelligence/docs/reference/rest/Shared.Types/Operation`.

### Authorization Scopes

Requires the following OAuth scope:

- `https://www.googleapis.com/auth/cloud-platform`

For more information, see the [Auth Guide](https://cloud.google.com/docs/authentication/).