Create a warehouse asset annotation

Media objects (asset resources) in a warehouse (corpus) contain metadata and annotation resources. These annotation resources represent a key-value mapping of content in an asset.

Create a warehouse asset annotation

You must complete the following steps before you can create an annotation for an asset:

Create an asset resource in a warehouse
Create a dataSchema with the same key to indicate the data type of the annotation value

An annotation can optionally have a temporal partition associated with it. For example, if an annotation applies to the whole asset, you can omit any temporal partition associated with it. Similarly, if an annotation applies to only a specific part of a video asset, you can supply the time range of the asset when creating the annotation.

Create an annotation with no temporal partition

If an annotation applies to the entirety of a video asset you don't have to provide a temporal partition for it. Use the following sample to create a user provided annotation for a whole asset (no video time period specified).

REST

Before using any of the request data, make the following replacements:

REGIONALIZED_ENDPOINT: Endpoint might include a prefix matching the LOCATION_ID such as europe-west4-. See more about regionalized endpoints.
PROJECT_NUMBER: Your Google Cloud project number.
LOCATION_ID: The region where you are using Vertex AI Vision. For example: us-central1, europe-west4. See available regions.
CORPUS_ID: The ID of your target corpus.
ASSET_ID: The ID of your target asset.
ANNOTATION_ID: (Optional) A user-provided value for the annotation ID. In this request, the value is added to the request URL in the form:
- https://ENDPOINT/v1/[...]/corpora/CORPUS_ID/assets/ASSET_ID/annotations?annotation_id=ANNOTATION_ID

HTTP method and URL:

POST https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations

Request JSON body:

{
  "user_specified_annotation":{
    "key": "camera-location",
    "value": {
      "str_value": "Sunnyvale"
    }
  }
}

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations"

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations/ANNOTATION_ID",
  "userSpecifiedAnnotation": {
    "key": "camera-location",
    "value": {
      "strValue": "Sunnyvale"
    }
  }
}

Create an annotation with a temporal partition

If an annotation applies to only part of a video asset you can provide a time range for the target video portion. Use the following sample to create a user provided annotation for a specific time period of a video asset using a temporal partition.

REST

Before using any of the request data, make the following replacements:

REGIONALIZED_ENDPOINT: Endpoint might include a prefix matching the LOCATION_ID such as europe-west4-. See more about regionalized endpoints.
PROJECT_NUMBER: Your Google Cloud project number.
LOCATION_ID: The region where you are using Vertex AI Vision. For example: us-central1, europe-west4. See available regions.
CORPUS_ID: The ID of your target corpus.
ASSET_ID: The ID of your target asset.
ANNOTATION_ID: (Optional) A user-provided value for the annotation ID. In this request, the value is added to the request URL in the form:
- https://ENDPOINT/v1/[...]/corpora/CORPUS_ID/assets/ASSET_ID/annotations?annotation_id=ANNOTATION_ID

HTTP method and URL:

POST https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations

Request JSON body:

{
  "user_specified_annotation": {
    "key": "object-detected",
    "value": {
      "str_value": "cat"
    },
    "partition": {
      "temporal_partition": {
        "start_time": {
          "seconds": "1630464728"
        },
        "end_time": {
          "seconds": "1630464729"
        }
      }
    }
  }
}

To send your request, choose one of these options:

curl

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations"

PowerShell

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations/ANNOTATION_ID",
  "userSpecifiedAnnotation": {
    "key": "object-detected",
    "value": {
      "strValue": "cat"
    },
    "partition": {
      "temporalPartition": {
        "startTime": "2022-09-14T20:33:09Z",
        "endTime": "2022-09-14T20:33:39Z"
      }
    }
  }
}

Update an annotation (no temporal partition)

REST

Before using any of the request data, make the following replacements:

REGIONALIZED_ENDPOINT: Endpoint might include a prefix matching the LOCATION_ID such as europe-west4-. See more about regionalized endpoints.
PROJECT_NUMBER: Your Google Cloud project number.
LOCATION_ID: The region where you are using Vertex AI Vision. For example: us-central1, europe-west4. See available regions.
CORPUS_ID: The ID of your target corpus.
ASSET_ID: The ID of your target asset.
ANNOTATION_ID: The ID of your target annotation.

HTTP method and URL:

PATCH https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations/ANNOTATION_ID

Request JSON body:

{
 "user_specified_annotation":{
    "key": "camera-location",
    "value": {
      "str_value": "UPDATED_FIELD_VALUE"
    }
  }
}

To send your request, choose one of these options:

curl

Save the request body in a file named request.json, and execute the following command:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations/ANNOTATION_ID"

PowerShell

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations/ANNOTATION_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations/ANNOTATION_ID",
  "userSpecifiedAnnotation": {
    "key": "camera-location",
    "value": {
      "strValue": "UPDATED_FIELD_VALUE"
    }
  }
}