自 2026 年 9 月 14 日起,Video Intelligence API 将正式弃用,并且不再受支持。您可以在 2027 年 9 月 14 日之前继续使用 Video Intelligence API,之后该 API 将被关闭。我们建议您迁移到
Gemini 系列模型。
Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。
检测人员
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
以下代码示例演示了如何使用 Video Intelligence API 检测视频文件中的人物。
Video Intelligence 可以检测视频文件中是否存在人员并跟踪视频或视频片段中的个人。
通过 Cloud Storage 中的文件进行人员检测
以下演示了如何使用人员动态检测功能向 Video Intelligence 发送注解请求。
REST
发送视频注解请求
下面演示了如何向
videos:annotate
方法发送 POST 请求。该示例使用 Google Cloud CLI 创建访问令牌。如需了解如何安装 gcloud CLI,请参阅
Video Intelligence API 快速入门。
另请参阅 PersonDetectionConfig。
在使用任何请求数据之前,请先进行以下替换:
- INPUT_URI:包含要添加注释的文件的 Cloud Storage 存储桶(包括文件名)。必须以
gs:// 开头。
例如:
"inputUri": "gs://cloud-samples-data/video/googlework_short.mp4"
- PROJECT_NUMBER:您的 Google Cloud 项目的数字标识符
HTTP 方法和网址:
POST https://videointelligence.googleapis.com/v1/videos:annotate
请求 JSON 正文:
{
"inputUri": "INPUT_URI",
"features": ["PERSON_DETECTION"],
"videoContext": {
"personDetectionConfig": {
"includeBoundingBoxes": true,
"includePoseLandmarks": true,
"includeAttributes": true
}
}
}
如需发送您的请求,请展开以下选项之一:
curl(Linux、macOS 或 Cloud Shell)
将请求正文保存在名为 request.json 的文件中,然后执行以下命令:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_NUMBER" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://videointelligence.googleapis.com/v1/videos:annotate"
PowerShell (Windows)
将请求正文保存在名为 request.json 的文件中,然后执行以下命令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_NUMBER" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://videointelligence.googleapis.com/v1/videos:annotate" | Select-Object -Expand Content
您应该收到类似以下内容的 JSON 响应:
响应
{
"name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/operations/OPERATION_ID"
}
如果响应成功,Video Intelligence API 将返回您的操作的 name。上面显示了此类响应的示例,其中:
- PROJECT_NUMBER:您项目的编号
- LOCATION_ID:在其中添加注释的 Cloud 区域。支持的云区域为:
us-east1、us-west1、europe-west1、asia-east1。如果未指定区域,系统将根据视频文件位置确定区域。
- OPERATION_ID:是为请求创建的长时间运行的操作的 ID,并在启动操作时在响应中提供,例如
12345...
获取注解结果
要检索操作的结果,请使用从 videos:annotate 调用返回的操作名称发出 GET 请求,如以下示例所示。
在使用任何请求数据之前,
请先进行以下替换:
- OPERATION_NAME:Video Intelligence API 返回的操作名称。操作名称采用
projects/PROJECT_NUMBER/locations/LOCATION_ID/operations/OPERATION_ID 格式
- PROJECT_NUMBER:您的 Google Cloud 项目的数字标识符
HTTP 方法和网址:
GET https://videointelligence.googleapis.com/v1/OPERATION_NAME
如需发送您的请求,请展开以下选项之一:
curl(Linux、macOS 或 Cloud Shell)
执行以下命令:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_NUMBER" \
"https://videointelligence.googleapis.com/v1/OPERATION_NAME"
PowerShell (Windows)
执行以下命令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_NUMBER" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://videointelligence.googleapis.com/v1/OPERATION_NAME" | Select-Object -Expand Content
您应该收到类似以下内容的 JSON 响应:
响应
{
"name": "us-west1.10001026834554604237",
"metadata": {
"@type": "type.googleapis.com/google.cloud.videointelligence.v1.AnnotateVideoProgress",
"annotationProgress": [
{
"inputUri": "/cloud-ml-sandbox/video/chicago.mp4",
"progressPercent": 100,
"startTime": "2020-02-08T21:26:56.577807Z",
"updateTime": "2020-02-08T21:28:09.620665Z"
}
]
},
"done": true,
"response": {
"@type": "type.googleapis.com/google.cloud.videointelligence.v1.AnnotateVideoResponse",
"annotationResults": [
{
"inputUri": "/cloud-ml-sandbox/video/chicago.mp4",
"personDetectionAnnotations": [
{
"tracks": [
{
"segment": {
"startTimeOffset": "0s",
"endTimeOffset": "1.507436s"
}
},
...
]
}
]
}
]
}
}
镜头检测注释以 shotAnnotations 列表的形式返回。
注意:done 字段仅在其值为 True 时返回。
操作未完成的响应中不包含该字段。
下载注释结果
将来源中的注释复制到目标存储分区(请参阅复制文件和对象):
gcloud storage cp gcs_uri gs://my-bucket
注意:如果输出 gcs uri 由用户提供,则注解存储在该 gcs uri 中。
Java
如需向 Video Intelligence 进行身份验证,请设置应用默认凭据。
如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
如需向 Video Intelligence 进行身份验证,请设置应用默认凭据。
如需了解详情,请参阅为本地开发环境设置身份验证。
Python
如需向 Video Intelligence 进行身份验证,请设置应用默认凭据。
如需了解详情,请参阅为本地开发环境设置身份验证。
来自本地文件的人员动态检测
以下示例使用人员动态检测功能从本地机器上传的视频文件中查找视频中的实体。
REST
发送处理请求
要对本地视频文件执行人员动态检测,请对视频文件的内容进行 base64 编码。如需了解如何对视频文件的内容进行 base64 编码,请参阅 Base64 编码。然后,向 videos:annotate 方法发出 POST 请求。在请求的 inputContent 字段中添加 base64 编码的内容,并指定 PERSON_DETECTION 功能。
以下示例展示了使用 curl 的 POST 请求。该示例使用 Google Cloud CLI 创建访问令牌。如需了解如何安装
gcloud CLI,请参阅
Video Intelligence API 快速入门
在使用任何请求数据之前,
请先进行以下替换:
- inputContent: inputContent:二进制文件格式的本地视频文件
例如:'AAAAGGZ0eXBtcDQyAAAAAGlzb21tcDQyAAGVYW1vb3YAAABsbXZoZAAAAADWvhlR1r4ZUQABX5ABCOxo
AAEAAAEAAAAAAA4...'
- PROJECT_NUMBER:您的 Google Cloud 项目的数字标识符
HTTP 方法和网址:
POST https://videointelligence.googleapis.com/v1/videos:annotate
请求 JSON 正文:
{
"inputUri": "Local video file in binary format",
"features": ["PERSON_DETECTION"],
"videoContext": {
"personDetectionConfig": {
"includeBoundingBoxes": true,
"includePoseLandmarks": true,
"includeAttributes": true
}
}
}
如需发送您的请求,请展开以下选项之一:
curl(Linux、macOS 或 Cloud Shell)
将请求正文保存在名为 request.json 的文件中,然后执行以下命令:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_NUMBER" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://videointelligence.googleapis.com/v1/videos:annotate"
PowerShell (Windows)
将请求正文保存在名为 request.json 的文件中,然后执行以下命令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_NUMBER" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://videointelligence.googleapis.com/v1/videos:annotate" | Select-Object -Expand Content
您应该收到类似以下内容的 JSON 响应:
响应
{
"name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/var>/operations/OPERATION_ID"
}
如果请求成功,则 Video Intelligence 会为您的操作分配 name。上面的示例展示了此类响应的示例,其中 project-number 是您的项目编号,operation-id 是为请求创建的长时间运行的操作的 ID。
{
"name": "us-west1.17122464255125931980"
}
获取结果
要检索操作结果,请向 operations 端点发送 GET 请求并指定操作名称。
在使用任何请求数据之前,请先进行以下替换:
- OPERATION_NAME:Video Intelligence API 返回的操作名称。操作名称采用
projects/PROJECT_NUMBER/locations/LOCATION_ID/operations/OPERATION_ID 格式
- PROJECT_NUMBER:您的 Google Cloud 项目的数字标识符
HTTP 方法和网址:
GET https://videointelligence.googleapis.com/v1/OPERATION_NAME
如需发送您的请求,请展开以下选项之一:
curl(Linux、macOS 或 Cloud Shell)
执行以下命令:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_NUMBER" \
"https://videointelligence.googleapis.com/v1/OPERATION_NAME"
PowerShell (Windows)
执行以下命令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_NUMBER" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://videointelligence.googleapis.com/v1/OPERATION_NAME" | Select-Object -Expand Content
您应该收到类似以下内容的 JSON 响应:
响应
{
"name": "us-west1.10001026834554604237",
"metadata": {
"@type": "type.googleapis.com/google.cloud.videointelligence.v1.AnnotateVideoProgress",
"annotationProgress": [
{
"progressPercent": 100,
"startTime": "2020-02-08T21:26:56.577807Z",
"updateTime": "2020-02-08T21:28:09.620665Z"
}
]
},
"done": true,
"response": {
"@type": "type.googleapis.com/google.cloud.videointelligence.v1.AnnotateVideoResponse",
"annotationResults": [
{
"personDetectionAnnotations": [
{
"tracks": [
{
"segment": {
"startTimeOffset": "0s",
"endTimeOffset": "1.507436s"
}
},
...
]
}
]
}
]
}
}
Java
如需向 Video Intelligence 进行身份验证,请设置应用默认凭据。
如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
如需向 Video Intelligence 进行身份验证,请设置应用默认凭据。
如需了解详情,请参阅为本地开发环境设置身份验证。
Python
如需向 Video Intelligence 进行身份验证,请设置应用默认凭据。
如需了解详情,请参阅为本地开发环境设置身份验证。
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2026-10-23。
[null,null,["最后更新时间 (UTC):2026-10-23。"],[],[]]