Google Gemini Video REST

Video REST

quickstartsrestgemini-cookbookgemini-apigemini

alph-notebooks/gemini-cookbook / Video_REST.ipynb

Export

Run Notebooks

Contents

No cells yet

Add cells to see them here

Copyright 2025 Google LLC.

[ ]

Gemini API: Video prompting with REST

This notebook provides quick code examples that show you how to prompt the Gemini API using a video file with curl. In this case, you'll use a short clip of Big Buck Bunny.

You can run this in Google Colab, or you can copy/paste the curl commands into your terminal.

Set up the environment

To run this notebook, your API key must be stored it in a Colab Secret named GOOGLE_API_KEY. If you are running in a different environment, you can store your key in an environment variable. See Authentication to learn more.

Authentication Overview

Important: The File API uses API keys for authentication and access. Uploaded files are associated with the API key's cloud project. Unlike other Gemini APIs that use API keys, your API key also grants access data you've uploaded to the File API, so take extra care in keeping your API key secure. For best practices on securing API keys, refer to the API console support center.

[ ]

Install jq to help with processing of JSON API responses.

[ ]

Use a video file with the Gemini API

The Gemini API accepts video file formats through the File API. The File API accepts files under 2GB in size and can store up to 20GB of files per project. Files last for 2 days and cannot be downloaded from the API. For this example, you will use the short film "Big Buck Bunny".

"Big Buck Bunny" is (C) Copyright 2008, Blender Foundation / www.bigbuckbunny.org and licensed under the Creative Commons Attribution 3.0 License.

Note: In Colab, you can also upload your own files to use.

[ ]

With the video file now available locally, generate some metadata that you will use in subsequent steps.

[8]

./BigBuckBunny_320x180.mp4 video/mp4 64657027

Start the upload task

Media uploads in the File API are resumable, so the first step is to define an upload task. This initial request gives you a reference you can use for subsequent upload operations, and allows you to query the status of the upload before sending data, in case of network issues during the data transfer.

The API returns the upload URL in the x-goog-upload-url header, so take note of that in the response headers - you will send the payload data to this URL.

No payload data (video bytes) are sent in this initial request.

[15]

HTTP/2 200

Upload video data

Now that you have created the upload task, you can upload the file data by sending bytes to the returned upload URL.

[16]

{
  "file": {
    "name": "files/4if4o2bqvugf",
    "displayName": "Big Buck Bunny",
    "mimeType": "video/mp4",
    "sizeBytes": "64657027",
    "createTime": "2024-08-26T08:24:56.068012Z",
    "updateTime": "2024-08-26T08:24:56.068012Z",
    "expirationTime": "2024-08-28T08:24:56.049455995Z",
    "sha256Hash": "Zjc4ZjM5NjAzZTY3NzQ5MDdmMmZhYWZhYmYyNmE2NjdmNGE2ZmMzMTc2OWVjMzA0YThhOGY3YzYyZDI4MDUwOA==",
    "uri": "https://generativelanguage.googleapis.com/v1beta/files/4if4o2bqvugf",
    "state": "PROCESSING"
  }
}

Get file info

After uploading the file, you can verify the API has successfully received the files by querying the files.get endpoint.

files.get lets you see the file uploaded to the File API that are associated with the Cloud project your API key belongs to. Only the name (and by extension, the uri) are unique.

[19]

{
  "name": "files/4if4o2bqvugf",
  "displayName": "Big Buck Bunny",
  "mimeType": "video/mp4",
  "sizeBytes": "64657027",
  "createTime": "2024-08-26T08:24:56.068012Z",
  "updateTime": "2024-08-26T08:25:03.977029Z",
  "expirationTime": "2024-08-28T08:24:56.049455995Z",
  "sha256Hash": "Zjc4ZjM5NjAzZTY3NzQ5MDdmMmZhYWZhYmYyNmE2NjdmNGE2ZmMzMTc2OWVjMzA0YThhOGY3YzYyZDI4MDUwOA==",
  "uri": "https://generativelanguage.googleapis.com/v1beta/files/4if4o2bqvugf",
  "state": "ACTIVE",
  "videoMetadata": {
    "videoDuration": "596s",
    "videoThumbnailBytes": "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"
  }
}

Wait for processing

Once the file is uploaded, the file service will perform some pre-processing to prepare the video for use in the LLM. For simple media types this is typically a negligible amount of time, but for video content you may need a short wait.

You can use the state field to query if the video is ready for use. If you use it in a prompt prematurely you will see an error like The File ... is not in an ACTIVE state and usage is not allowed.

[ ]

Processing video...
Processing video...
Processing video...
Video is now ACTIVE.

Prompt with the video

Now that the video is uploaded and processed, you can reference it in a prompt.

When assembling your contents, the video can be referenced using a file_data part, like this:

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

Try it yourself with this request.

[ ]

MODEL_ID

[ ]

{
  "parts": [
    {
      "text": "This is a 3D animated short film about a big bunny that gets tired of his usual diet of grass. He wants to try something different like fruit and learns the value of what he has. The film's title is Big Buck Bunny. "
    }
  ],
  "role": "model"
}