Using files

Gemini API hỗ trợ việc tải tệp đa phương tiện lên riêng biệt với dữ liệu đầu vào của câu lệnh, cho phép bạn sử dụng lại nội dung nghe nhìn của mình trên nhiều yêu cầu và nhiều câu lệnh. Để biết thêm thông tin chi tiết, hãy xem hướng dẫn Tạo câu lệnh bằng nội dung nghe nhìn.

Tài nguyên REST: files

Tài nguyên: Tệp

Một tệp được tải lên API.

Trường
name string

Không thể thay đổi. Giá trị nhận dạng. Tên tài nguyên File. Mã nhận dạng (tên không bao gồm tiền tố "files/") có thể chứa tối đa 40 ký tự là chữ và số viết thường hoặc dấu gạch ngang (-). Mã nhận dạng không được bắt đầu hoặc kết thúc bằng dấu gạch ngang. Nếu tên trống khi tạo, một tên riêng biệt sẽ được tạo. Ví dụ: files/123-456

displayName string

Không bắt buộc. Tên hiển thị dễ đọc cho File. Tên hiển thị không được dài quá 512 ký tự, bao gồm cả dấu cách. Ví dụ: "Hình ảnh chào mừng"

mimeType string

Chỉ có đầu ra. Loại MIME của tệp.

sizeBytes string (int64 format)

Chỉ có đầu ra. Kích thước của tệp tính bằng byte.

createTime string (Timestamp format)

Chỉ có đầu ra. Dấu thời gian cho biết thời điểm tạo File.

Hãy dùng RFC 3339, trong đó dữ liệu đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các khoảng lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".

updateTime string (Timestamp format)

Chỉ có đầu ra. Dấu thời gian cho biết lần cập nhật gần đây nhất của File.

Hãy dùng RFC 3339, trong đó dữ liệu đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các khoảng lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".

expirationTime string (Timestamp format)

Chỉ có đầu ra. Dấu thời gian cho biết thời điểm File sẽ bị xoá. Chỉ đặt nếu File được lên lịch hết hạn.

Hãy dùng RFC 3339, trong đó dữ liệu đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các khoảng lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".

sha256Hash string (bytes format)

Chỉ có đầu ra. Hàm băm SHA-256 của các byte đã tải lên.

Một chuỗi được mã hoá base64.

uri string

Chỉ có đầu ra. URI của File.

downloadUri string

Chỉ có đầu ra. URI tải xuống của File.

state enum (State)

Chỉ có đầu ra. Trạng thái xử lý của Tệp.

source enum (Source)

Nguồn của tệp.

error object (Status)

Chỉ có đầu ra. Trạng thái lỗi nếu quá trình Xử lý tệp không thành công.

metadata Union type
Siêu dữ liệu cho Tệp. Sau đây là danh sách các trường loại trừ lẫn nhau. Tối đa một trong các trường sẽ được đặt trong phản hồi:
videoMetadata object (VideoFileMetadata)

Chỉ có đầu ra. Siêu dữ liệu của một video.

Kết thúc các trường xung khắc.
Biểu diễn dưới dạng JSON
{
  "name": string,
  "displayName": string,
  "mimeType": string,
  "sizeBytes": string,
  "createTime": string,
  "updateTime": string,
  "expirationTime": string,
  "sha256Hash": string,
  "uri": string,
  "downloadUri": string,
  "state": enum (State),
  "source": enum (Source),
  "error": {
    object (Status)
  },

  // metadata
  "videoMetadata": {
    object (VideoFileMetadata)
  }
  // Union type
}

VideoFileMetadata

Siêu dữ liệu của một video File.

Trường
videoDuration string (Duration format)

Thời lượng của video.

Thời lượng tính bằng giây, có tối đa 9 chữ số thập phân và kết thúc bằng "s". Ví dụ: "3.5s".

Biểu diễn dưới dạng JSON
{
  "videoDuration": string
}

Tiểu bang

Các trạng thái cho vòng đời của một tệp.

Enum
STATE_UNSPECIFIED Giá trị mặc định. Giá trị này được dùng nếu bạn bỏ qua trạng thái.
PROCESSING Tệp đang được xử lý và chưa thể dùng để suy luận.
ACTIVE Tệp được xử lý và có thể dùng để suy luận.
FAILED Không xử lý được tệp.

Nguồn

Enum
SOURCE_UNSPECIFIED Được dùng nếu bạn không chỉ định nguồn.
UPLOADED Cho biết người dùng đã tải tệp lên.
GENERATED Cho biết tệp này do Google tạo.
REGISTERED Cho biết tệp là tệp đã đăng ký, tức là tệp Google Cloud Storage.

Phương thức: files.get

Lấy siêu dữ liệu cho File đã cho.

Điểm cuối

get https://generativelanguage.googleapis.com/v1beta/{name=files/*}

Tham số đường dẫn

name string

Bắt buộc. Tên của File cần lấy. Ví dụ: files/abc-123 Tên này có dạng files/{file}.

Nội dung yêu cầu

Nội dung yêu cầu phải trống.

Ví dụ về yêu cầu

Python

from google import genai

client = genai.Client()
myfile = client.files.upload(file=media / "poem.txt")
file_name = myfile.name
print(file_name)  # "files/*"

myfile = client.files.get(name=file_name)
print(myfile)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const myfile = await ai.files.upload({
  file: path.join(media, "poem.txt"),
});
const fileName = myfile.name;
console.log(fileName);

const fetchedFile = await ai.files.get({ name: fileName });
console.log(fetchedFile);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}
myfile, err := client.Files.UploadFromPath(
	ctx,
	filepath.Join(getMedia(), "poem.txt"), 
	&genai.UploadFileConfig{
		MIMEType: "text/plain",
	},
)
if err != nil {
	log.Fatal(err)
}
fileName := myfile.Name
fmt.Println(fileName)
file, err := client.Files.Get(ctx, fileName, nil)
if err != nil {
	log.Fatal(err)
}
fmt.Println(file)

Shell

name=$(jq ".file.name" file_info.json)
# Get the file of interest to check state
curl https://generativelanguage.googleapis.com/v1beta/files/$name > file_info.json
# Print some information about the file you got
name=$(jq ".file.name" file_info.json)
echo name=$name
file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uripan>.sh

Phương thức: files.list

Liệt kê siêu dữ liệu cho các File do dự án yêu cầu sở hữu.

Điểm cuối

get https://generativelanguage.googleapis.com/v1beta/files

Tham số truy vấn

pageSize integer

Không bắt buộc. Số lượng File tối đa cần trả về trên mỗi trang. Nếu không được chỉ định, giá trị mặc định là 10. Tối đa pageSize là 100.

pageToken string

Không bắt buộc. Mã thông báo trang từ lệnh gọi files.list trước đó.

Nội dung yêu cầu

Nội dung yêu cầu phải trống.

Ví dụ về yêu cầu

Python

from google import genai

client = genai.Client()
print("My files:")
for f in client.files.list():
    print("  ", f.name)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
console.log("My files:");
// Using the pager style to list files
const pager = await ai.files.list({ config: { pageSize: 10 } });
let page = pager.page;
const names = [];
while (true) {
  for (const f of page) {
    console.log("  ", f.name);
    names.push(f.name);
  }
  if (!pager.hasNextPage()) break;
  page = await pager.nextPage();
}

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}
fmt.Println("My files:")
page, err := client.Files.List(ctx, nil)
if err != nil {
	log.Fatal(err)
}
for _, f := range page.Items {
	fmt.Println("  ", f.Name)
}