# Annotate a video by using the command line

This page shows how to make a Video Intelligence API request with `curl` for
projects that you own.

You can follow the steps on this page or try this quickstart as a
Google Cloud Training lab.

[Try it with a lab](https://www.cloudskillsboost.google/catalog_lab/804?qlcampaign=77-18-gcpd-921&utm_source=gcp&utm_medium=documentation&utm_campaign=vintelligence)

## Before you begin

<br />

### Required roles


To get the permissions that
you need to annotate a video,

ask your administrator to grant you the
following IAM roles on the project:

- [Service Usage Consumer](https://docs.cloud.google.com/iam/docs/roles-permissions/serviceusage.md.txt#serviceusage.serviceUsageConsumer) (`roles/serviceusage.serviceUsageConsumer`)
- [Storage Admin](https://docs.cloud.google.com/iam/docs/roles-permissions/storage.md.txt#storage.admin) (`roles/storage.admin`)


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

## Create a bucket

In your development environment, use the [`gcloud storage buckets create`
command](https://docs.cloud.google.com/sdk/gcloud/reference/storage/buckets/create) to create a bucket.

Before running the command, replace the following values:

- `BUCKET_LOCATION`: The geographic location where you want to store the data in your bucket. For example, `US`.

```
gcloud storage buckets create gs://videointelligence-quickstart-bucket --location=BUCKET_LOCATION
```

If the request is successful, the command returns the following message:

```
Creating gs://videointelligence-quickstart-bucket/...
```

## Upload a video to the bucket

In your development environment, use the [`gcloud storage cp`
command](https://docs.cloud.google.com/sdk/gcloud/reference/storage/cp) to
upload a video to the bucket that you created.

Before running the command, replace the following values:

- `OBJECT_LOCATION`: The local path to your object. For example, `Desktop/dog.mp4`.

```
gcloud storage cp OBJECT_LOCATION gs://videointelligence-quickstart-bucket
```

If successful, the response looks like the following example:

```
Completed files 1/1 | 164.3kiB/164.3kiB
```

## Annotate the video

> [!CAUTION]
> **Caution:** VPC Service Controls egress restrictions are not enforced on the `outputUri` of `videos:annotate` requests. The service can write annotation results to a Cloud Storage bucket outside of your service perimeter. For details, see [Supported products and limitations](https://docs.cloud.google.com/vpc-service-controls/docs/supported-products.md.txt#videointelligence).

### gcloud

Use the gcloud CLI to call the `detect-labels` command
on the path of the video to be analyzed.

Before running the command, replace the following values:

- `YOUR_OBJECT`: The filename of the video that you uploaded. For example, `dog.mp4`.

```sh
gcloud ml video detect-labels gs://videointelligence-quickstart-bucket/YOUR_OBJECT
```

### Command-line

Use `curl` to make a POST request to the `videos:annotate` method.

Before running the command, replace the following values:

- `YOUR_OBJECT`: The filename of the video that you uploaded. For example, `dog.mp4`.

```bash
curl -X POST \
  -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
  -H "Content-Type: application/json; charset=utf-8" \
  --data '{"inputUri":"gs://videointelligence-quickstart-bucket/YOUR_OBJECT","features":["LABEL_DETECTION"]}'\
  "https://videointelligence.googleapis.com/v1/videos:annotate"
```

The Video Intelligence API creates an *operation* to process your request.
The response includes the operation name:

```json
{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/operations/OPERATION_ID"
}
```

You can request information on the operation by calling the `v1.operations`
endpoint, replacing <var translate="no">OPERATION_NAME</var> in the example below with the name returned in the previous step:

```bash
  curl -X GET \
    -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
    https://videointelligence.googleapis.com/v1/OPERATION_NAME
```

This command returns information related to your operation. If the operation has
completed, a `done` field is included and set to `true`:

```json
{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/operations/OPERATION_ID",
  "metadata": {
  "@type": "type.googleapis.com/google.cloud.videointelligence.v1.AnnotateVideoProgress",
    "annotationProgress": [
      {
        "inputUri": "/videointelligence-quickstart-bucket/YOUR_OBJECT",
        "progressPercent": 100,
        "startTime": "2020-04-01T22:13:17.978847Z",
        "updateTime": "2020-04-01T22:13:29.576004Z"
      }
    ]
  },
  "done": true,
  ...
}
```

<br />

After about a minute, the request returns the annotation results. The results
should look similar to the following:

```json
{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.videointelligence.v1.AnnotateVideoProgress",
    "annotationProgress": [
      {
        "inputUri": "videointelligence-quickstart-bucket/YOUR_OBJECT",
        "progressPercent": 100,
        "startTime": "2020-04-01T22:13:17.978847Z",
        "updateTime": "2020-04-01T22:13:29.576004Z"
      }
    ]
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.videointelligence.v1.AnnotateVideoResponse",
    "annotationResults": [
      {
        "inputUri": "/videointelligence-quickstart-bucket/YOUR_OBJECT",
        "segmentLabelAnnotations": [
          {
            "entity": {
              "entityId": "/m/07bsy",
              "description": "transport",
              "languageCode": "en-US"
            },
            "segments": [
              {
                "segment": {
                  "startTimeOffset": "0s",
                  "endTimeOffset": "38.757872s"
                },
                "confidence": 0.81231534
              }
            ]
          },
         {
          "entity": {
              "entityId": "/m/01n32",
              "description": "city",
              "languageCode": "en-US"
            },
            "categoryEntities": [
              {
                "entityId": "/m/043rvww",
                "description": "geographical feature",
                "languageCode": "en-US"
              }
            ],
            "segments": [
              {
                "segment": {
                  "startTimeOffset": "0s",
                  "endTimeOffset": "38.757872s"
                },
                "confidence": 0.3942462
              }
            ]
          },
          ...
          {
            "entity": {
              "entityId": "/m/06gfj",
              "description": "road",
              "languageCode": "en-US"
            },
            "segments": [
              {
                "segment": {
                  "startTimeOffset": "0s",
                  "endTimeOffset": "38.757872s"
                },
                "confidence": 0.86698604
              }
            ]
          }
        ]
      }
    ]
  }
}
   
```

Congratulations! You've sent your first request to the Video Intelligence API.

## Clean up

To avoid incurring charges to your Google Cloud account for the resources
used on this page, do one of the following:

- If you want to continue using the project that you created, then use the
  `gcloud storage rm` command with the `--recursive` flag to delete the bucket
  and anything inside of it:

  ```
  gcloud storage rm gs://videointelligence-quickstart-bucket --recursive
  ```
- If you don't need the project that you created for this quickstart, then
  delete the project.

  > [!CAUTION]
  > **Caution** : Deleting a project has the following effects:
  > - **Everything in the project is deleted.** If you used an existing project for the tasks in this document, when you delete it, you also delete any other work you've done in the project.
  > - **Custom project IDs are lost.** When you created this project, you might have created a custom project ID that you want to use in the future. To preserve the URLs that use the project ID, such as an `appspot.com` URL, delete selected resources inside the project instead of deleting the whole project.
  >
  >
  > If you plan to explore multiple architectures, tutorials, or quickstarts, reusing projects
  > can help you avoid exceeding project quota limits.

  1. In the Google Cloud console, go to the **Manage resources** page.

     [Go to Manage resources](https://console.cloud.google.com/iam-admin/projects)
  2. In the project list, select the project that you want to delete, and then click **Delete**.
  3. In the dialog, type the project ID, and then click **Shut down** to delete the project.

## What's next

- Work through the [How-To Guides](https://docs.cloud.google.com/video-intelligence/docs/how-to.md.txt).
- Work through the [Samples \& Tutorials](https://docs.cloud.google.com/video-intelligence/docs/tutorials.md.txt).
- Consult the [API Reference](https://docs.cloud.google.com/video-intelligence/docs/reference/rest.md.txt) for complete information on all API calls.