Video_REST.ipynb：使用REST API处理视频的完整指南

本教程面向有编程基础的开发者，深入讲解如何通过REST API（curl命令）调用Gemini API处理视频文件。内容涵盖环境配置、File API的可恢复上传机制、文件状态轮询、以及如何将视频作为多模态输入进行内容生成。教程不仅提供完整代码，还剖析了每个步骤的原理、设计决策和潜在问题，并给出生产环境优化建议，帮助开发者掌握AI视频处理的工程实践。

技术背景

随着多模态AI的发展，处理视频内容成为重要需求。Gemini API提供了强大的视频理解能力，但视频文件通常较大，直接通过常规API请求传输效率低且易失败。File API应运而生，它支持可恢复上传、异步处理，并允许在提示中引用已上传的媒体文件。本教程解决的核心问题是：如何高效、可靠地将视频文件上传至Gemini API并用于内容生成。适用场景包括视频内容分析、摘要生成、物体识别等。主要限制包括文件大小（<2GB）、存储配额（每项目20GB）、文件保留期（2天）以及API密钥的安全风险。

核心原理

核心原理是使用File API进行可恢复上传。流程分为三步：1) 发起上传任务，通过HTTP头（X-Goog-Upload-Protocol: resumable）告知API开始可恢复上传，并携带元数据（文件名、MIME类型、字节数），API返回上传URL（x-goog-upload-url）。2) 将视频字节通过PUT请求发送到该URL，使用X-Goog-Upload-Offset指定偏移量，支持断点续传。3) 上传完成后，文件进入PROCESSING状态，需轮询files.get端点直到状态变为ACTIVE。之后在generateContent请求中通过file_data部分引用文件URI，模型即可处理视频。关键设计决策包括：使用API密钥进行身份验证，但需注意密钥权限范围；文件与云项目关联，无法跨项目访问；文件保留2天，需及时使用。

架构分析

系统架构涉及三个主要组件：客户端（curl脚本）、Gemini API的File API和生成内容端点。数据流为：客户端上传视频至File API，File API存储并处理视频，返回文件URI；客户端随后调用generateContent端点，在请求体中包含file_data引用，模型读取视频并生成响应。设计思想是分离上传与推理，避免大文件阻塞推理请求，同时支持异步处理。File API采用可恢复上传协议，提高大文件传输的可靠性。组件关系：File API负责媒体生命周期管理，生成端点负责模型推理。可修改点包括：上传策略（分块大小）、轮询间隔、模型选择等。

完整实战教程

##### 版权所有 2026 Google LLC.

#@title Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

Gemini API：使用 REST 进行视频提示

本笔记本提供了快速代码示例，展示如何使用 curl 通过视频文件调用 Gemini API。在此示例中，您将使用 Big Buck Bunny 的短片片段。

您可以在 Google Colab 中运行此笔记本，或者将 curl 命令复制/粘贴到您的终端中。

设置环境

要运行此笔记本，您的 API 密钥必须存储在名为 GEMINI_API_KEY 的 Colab 密钥中。如果您在其他环境中运行，可以将密钥存储在环境变量中。请参阅 身份验证 了解更多信息。

身份验证概述

重要提示： File API 使用 API 密钥进行身份验证和访问控制。上传的文件与 API 密钥的云项目相关联。与其他使用 API 密钥的 Gemini API 不同，您的 API 密钥还授予对您上传到 File API 的数据的访问权限，因此请格外小心地保护您的 API 密钥。有关保护 API 密钥的最佳实践，请参阅 API 控制台支持中心。

import os
from google.colab import userdata

os.environ['GEMINI_API_KEY'] = userdata.get('GEMINI_API_KEY')

安装 jq 以帮助处理 JSON API 响应。

!apt install -q jq

使用 Gemini API 处理视频文件

Gemini API 通过 File API 接受视频文件格式。File API 接受小于 2GB 的文件，每个项目最多可存储 20GB 的文件。文件保留 2 天，且无法通过 API 下载。在本示例中，您将使用短片《大雄兔》。

《大雄兔》版权所有 (C) 2008，Blender Foundation / www.bigbuckbunny.org，并根据 知识共享署名 3.0 许可协议 授权。

注意：在 Colab 中，您也可以上传自己的文件 来使用。

!wget https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4

现在视频文件已在本地可用，生成一些将在后续步骤中使用的元数据。

%%bash

VIDEO_PATH="./BigBuckBunny_320x180.mp4"
DISPLAY_NAME="Big Buck Bunny"

# Auto-detect the metadata needed when you upload the video.
MIME_TYPE=$(file -b --mime-type "${VIDEO_PATH}")
NUM_BYTES=$(wc -c < "${VIDEO_PATH}")

echo $VIDEO_PATH $MIME_TYPE $NUM_BYTES

# Colab doesn't allow sharing shell variables between cells, so save them.
cat >./vars.sh <<-EOF
  export BASE_URL="https://generativelanguage.googleapis.com"
  export DISPLAY_NAME="${DISPLAY_NAME}"
  export VIDEO_PATH=${VIDEO_PATH}
  export MIME_TYPE=${MIME_TYPE}
  export NUM_BYTES=${NUM_BYTES}
EOF

启动上传任务

File API 中的媒体上传是可恢复的，因此第一步是定义一个上传任务。这个初始请求会为你提供一个引用，可用于后续的上传操作，并允许你在发送数据之前查询上传状态，以防数据传输过程中出现网络问题。

API 会在 x-goog-upload-url 头中返回上传 URL，因此请注意响应头中的该字段——你将把负载数据发送到这个 URL。

此初始请求不发送任何负载数据（视频字节）。

%%bash
. vars.sh

# Create the "new upload" request by providing the relevant metadata.
curl "${BASE_URL}/upload/v1beta/files?key=${GEMINI_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2>/dev/null

# Print the status.
head -1 upload-header.tmp

上传视频数据

现在你已经创建了上传任务，可以通过向返回的上传 URL 发送字节来上传文件数据。

%%bash
. vars.sh

# Extract the upload URL to use from the response headers.
upload_url=$(grep -i "x-goog-upload-url: " upload-header.tmp | cut -d" " -f2 | tr -d "\r")
# The header contains our API key, so don't leave it lying around.
rm upload-header.tmp

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${VIDEO_PATH}" >file_info.json 2>/dev/null

# Show the output. You will use it in a later step.
cat file_info.json

获取文件信息

上传文件后，您可以通过查询 files.get 端点 来验证 API 是否已成功接收文件。

files.get 允许您查看上传到 File API 且与您的 API 密钥所属的 Cloud 项目关联的文件。只有 name（以及由此扩展的 uri）是唯一的。

%%bash
. vars.sh

file_uri=$(jq -r ".file.uri" file_info.json)

curl "${file_uri}?key=${GEMINI_API_KEY}" 2>/dev/null

等待处理

文件上传后，文件服务将执行一些预处理，以便视频可供 LLM 使用。对于简单的媒体类型，这通常只需极短的时间，但对于视频内容，您可能需要稍等片刻。

您可以使用 state 字段查询视频是否已准备好使用。如果您过早地在提示中使用它，您将看到类似 The File ... is not in an ACTIVE state and usage is not allowed 的错误。

%%bash

state=$(jq -r ".file.state" file_info.json)
file_uri=$(jq -r ".file.uri" file_info.json)

while [[ "${state}" == "PROCESSING" ]];
do
  echo "Processing video..."
  sleep 5
  # Get the file of interest to check state
  curl "${file_uri}?key=${GEMINI_API_KEY}" >file_info.json 2>/dev/null
  state=$(jq -r ".state" file_info.json)
done

echo "Video is now ${state}."

使用视频进行提示

视频上传并处理完成后，您可以在提示中引用它。

在组装 contents 时，可以使用 file_data 部分引用视频，如下所示：

{
"file_data": {
"mime_type": "video/mp4",
"file_uri": "https://uri/from/previous/steps"
}
}

自己试试这个请求。

MODEL_ID = "gemini-3.7-flash" # @param ["gemini-3.1-pro-preview", "gemini-3.7-flash", "gemini-3.5-flash-lite", "gemini-2.5-pro"] {"allow-input":true, isTemplate: true}

%%bash
. vars.sh

file_uri=$(jq ".uri" file_info.json)

curl "${BASE_URL}/v1beta/models/${MODEL_ID}:generateContent?key=${GEMINI_API_KEY}" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "Please describe this file."},
          {"file_data": {
            "mime_type": "'${MIME_TYPE}'",
            "file_uri": '${file_uri}'}}]
        }]
       }' 2>/dev/null >response.json

jq -C .candidates[].content response.json

延伸阅读

File API 允许您上传多种多模态 MIME 类型，包括图像、音频和视频格式。File API 处理可用于通过内容生成端点生成内容的输入。

* 阅读 File API 参考文档。

* 在文档中了解有关使用媒体文件进行提示的更多信息，包括支持的格式和最大长度。

常见问题

常见错误及排查：1) 上传后文件状态非ACTIVE，提示'File is not in an ACTIVE state'，需等待处理完成，可增加轮询等待时间。2) 上传URL提取失败，检查响应头是否包含x-goog-upload-url，确保curl命令正确输出头信息。3) API密钥泄露风险，避免在日志中打印密钥，使用环境变量管理。4) 文件大小超限，检查文件是否超过2GB，可压缩或分段。5) MIME类型错误，使用file命令自动检测。6) 网络中断导致上传失败，利用可恢复上传的偏移量机制续传。生产环境优化：使用SDK而非curl，实现自动重试和并发控制；将文件URI缓存，避免重复上传；设置合理的轮询间隔（如5秒）减少API调用；监控API配额和成本。

企业应用扩展

进一步学习建议：1) 探索File API支持的其他媒体类型（图像、音频），了解不同格式的处理差异。2) 学习Gemini API的更多功能，如视频时间戳定位、帧提取等。3) 结合LangChain等框架构建视频分析应用。4) 研究如何将视频处理集成到生产流水线，包括异步任务队列、结果存储等。5) 关注API更新，如新模型版本对视频处理能力的增强。

总结

本教程面向有编程基础的开发者，深入讲解如何通过REST API（curl命令）调用Gemini API处理视频文件。内容涵盖环境配置、File API的可恢复上传机制、文件状态轮询、以及如何将视频作为多模态输入进行内容生成。教程不仅提供完整代码，还剖析了每个步骤的原理、设计决策和潜在问题，并给出生产环境优化建议，帮助开发者掌握AI视频处理的工程实践。

内容来源与验证

继续系统学习

站内还有更多完整实战教程

加入会员，解锁全部教程、完整代码与持续更新内容。

加入会员
查看全部图像与多模态教程