Using files

Die Gemini API unterstützt das separate Hochladen von Mediendateien vom Prompt-Eingabe, sodass Ihre Medien in mehreren Anfragen und Prompts wiederverwendet werden können. Weitere Informationen finden Sie im Leitfaden Prompts mit Media.

Methode: media.upload

Erstellt ein File.

Endpunkt

  • Upload-URI für Media-Uploadanfragen:
 post https://generativelanguage.googleapis.com/upload/v1beta/files
  • Metadaten-URI für Anfragen mit ausschließlich Metadaten:
 post > https://generativelanguage.googleapis.com/v1beta/files > >
>

Anfragetext

Der Anfragetext enthält Daten mit folgender Struktur:

Felder
file object (File)

Optional. Metadaten für die zu erstellende Datei.

Beispielanfrage

Bild

Python

from google import genai

client = genai.Client()
myfile = client.files.upload(file=media / "Cajun_instruments.jpg")
print(f"{myfile=}")

result = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=[
        myfile,
        "\n\n",
        "Can you tell me about the instruments in this photo?",
    ],
)
print(f"{result.text=}")
files.py

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, "Cajun_instruments.jpg"),
  config: { mimeType: "image/jpeg" },
});
console.log("Uploaded file:", myfile);

const result = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: createUserContent([
    createPartFromUri(myfile.uri, myfile.mimeType),
    "\n\n",
    "Can you tell me about the instruments in this photo?",
  ]),
});
console.log("result.text=", result.text);
files.js

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(), "Cajun_instruments.jpg"), 
	&genai.UploadFileConfig{
		MIMEType : "image/jpeg",
	},
)
if err != nil {
	log.Fatal(err)
}
fmt.Printf("myfile=%+v\n", myfile)

parts := []*genai.Part{
	genai.NewPartFromURI(myfile.URI, myfile.MIMEType),
	genai.NewPartFromText("\n\n"),
	genai.NewPartFromText("Can you tell me about the instruments in this photo?"),
}

contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}

response, err := client.Models.GenerateContent(ctx, "gemini-2.0-flash", contents, nil)
if err != nil {
	log.Fatal(err)
}
text := response.Text()
fmt.Printf("result.text=%s\n", text)
files.go

Muschel

MIME_TYPE=$(file -b --mime-type "${IMG_PATH_2}")
NUM_BYTES=$(wc -c < "${IMG_PATH_2}")
DISPLAY_NAME=TEXT

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
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

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# 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 "@${IMG_PATH_2}" 2> /dev/null > file_info.json

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

# Now generate content using that file
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "Can you tell me about the instruments in this photo?"},
          {"file_data":
            {"mime_type": "image/jpeg", 
            "file_uri": '$file_uri'}
        }]
        }]
       }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json
files.sh

Audio

Python

from google import genai

client = genai.Client()
myfile = client.files.upload(file=media / "sample.mp3")
print(f"{myfile=}")

result = client.models.generate_content(
    model="gemini-2.0-flash", contents=[myfile, "Describe this audio clip"]
)
print(f"{result.text=}")
files.py

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, "sample.mp3"),
  config: { mimeType: "audio/mpeg" },
});
console.log("Uploaded file:", myfile);

const result = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: createUserContent([
    createPartFromUri(myfile.uri, myfile.mimeType),
    "Describe this audio clip",
  ]),
});
console.log("result.text=", result.text);
files.js

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(), "sample.mp3"), 
	&genai.UploadFileConfig{
		MIMEType : "audio/mpeg",
	},
)
if err != nil {
	log.Fatal(err)
}
fmt.Printf("myfile=%+v\n", myfile)

parts := []*genai.Part{
	genai.NewPartFromURI(myfile.URI, myfile.MIMEType),
	genai.NewPartFromText("Describe this audio clip"),
}

contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}

response, err := client.Models.GenerateContent(ctx, "gemini-2.0-flash", contents, nil)
if err != nil {
	log.Fatal(err)
}
text := response.Text()
fmt.Printf("result.text=%s\n", text)
files.go

Muschel

MIME_TYPE=$(file -b --mime-type "${AUDIO_PATH}")
NUM_BYTES=$(wc -c < "${AUDIO_PATH}")
DISPLAY_NAME=AUDIO

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
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

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# 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 "@${AUDIO_PATH}" 2> /dev/null > file_info.json

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

# Now generate content using that file
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "Describe this audio clip"},
          {"file_data":{"mime_type": "audio/mp3", "file_uri": '$file_uri'}}]
        }]
       }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json
files.sh

Text

Python

from google import genai

client = genai.Client()
myfile = client.files.upload(file=media / "poem.txt")
print(f"{myfile=}")

result = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=[myfile, "\n\n", "Can you add a few more lines to this poem?"],
)
print(f"{result.text=}")
files.py

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"),
});
console.log("Uploaded file:", myfile);

const result = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: createUserContent([
    createPartFromUri(myfile.uri, myfile.mimeType),
    "\n\n",
    "Can you add a few more lines to this poem?",
  ]),
});
console.log("result.text=", result.text);
files.js

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)
}
fmt.Printf("myfile=%+v\n", myfile)

parts := []*genai.Part{
	genai.NewPartFromURI(myfile.URI, myfile.MIMEType),
	genai.NewPartFromText("\n\n"),
	genai.NewPartFromText("Can you add a few more lines to this poem?"),
}

contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}

response, err := client.Models.GenerateContent(ctx, "gemini-2.0-flash", contents, nil)
if err != nil {
	log.Fatal(err)
}
text := response.Text()
fmt.Printf("result.text=%s\n", text)
files.go

Muschel

MIME_TYPE=$(file -b --mime-type "${TEXT_PATH}")
NUM_BYTES=$(wc -c < "${TEXT_PATH}")
DISPLAY_NAME=TEXT

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
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

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# 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 "@${TEXT_PATH}" 2> /dev/null > file_info.json

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

# Now generate content using that file
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "Can you add a few more lines to this poem?"},
          {"file_data":{"mime_type": "text/plain", "file_uri": '$file_uri'}}]
        }]
       }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json

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_uri

curl --request "DELETE" https://generativelanguage.googleapis.com/v1beta/files/$name?key=$GEMINI_API_KEY

files.sh

Video

Python

from google import genai
import time

client = genai.Client()
# Video clip (CC BY 3.0) from https://peach.blender.org/download/
myfile = client.files.upload(file=media / "Big_Buck_Bunny.mp4")
print(f"{myfile=}")

# Poll until the video file is completely processed (state becomes ACTIVE).
while not myfile.state or myfile.state.name != "ACTIVE":
    print("Processing video...")
    print("File state:", myfile.state)
    time.sleep(5)
    myfile = client.files.get(name=myfile.name)

result = client.models.generate_content(
    model="gemini-2.0-flash", contents=[myfile, "Describe this video clip"]
)
print(f"{result.text=}")
files.py

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
let myfile = await ai.files.upload({
  file: path.join(media, "Big_Buck_Bunny.mp4"),
  config: { mimeType: "video/mp4" },
});
console.log("Uploaded video file:", myfile);

// Poll until the video file is completely processed (state becomes ACTIVE).
while (!myfile.state || myfile.state.toString() !== "ACTIVE") {
  console.log("Processing video...");
  console.log("File state: ", myfile.state);
  await sleep(5000);
  myfile = await ai.files.get({ name: myfile.name });
}

const result = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: createUserContent([
    createPartFromUri(myfile.uri, myfile.mimeType),
    "Describe this video clip",
  ]),
});
console.log("result.text=", result.text);
files.js

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(), "Big_Buck_Bunny.mp4"), 
	&genai.UploadFileConfig{
		MIMEType : "video/mp4",
	},
)
if err != nil {
	log.Fatal(err)
}
fmt.Printf("myfile=%+v\n", myfile)

// Poll until the video file is completely processed (state becomes ACTIVE).
for myfile.State == genai.FileStateUnspecified || myfile.State != genai.FileStateActive {
	fmt.Println("Processing video...")
	fmt.Println("File state:", myfile.State)
	time.Sleep(5 * time.Second)

	myfile, err = client.Files.Get(ctx, myfile.Name, nil)
	if err != nil {
		log.Fatal(err)
	}
}

parts := []*genai.Part{
	genai.NewPartFromURI(myfile.URI, myfile.MIMEType),
	genai.NewPartFromText("Describe this video clip"),
}

contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}

response, err := client.Models.GenerateContent(ctx, "gemini-2.0-flash", contents, nil)
if err != nil {
	log.Fatal(err)
}
text := response.Text()
fmt.Printf("result.text=%s\n", text)
files.go

Muschel

MIME_TYPE=$(file -b --mime-type "${VIDEO_PATH}")
NUM_BYTES=$(wc -c < "${VIDEO_PATH}")
DISPLAY_NAME=VIDEO_PATH

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
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

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# 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}" 2> /dev/null > file_info.json

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

state=$(jq ".file.state" file_info.json)
echo state=$state

# Ensure the state of the video is 'ACTIVE'
while [[ "($state)" = *"PROCESSING"* ]];
do
  echo "Processing video..."
  sleep 5
  # Get the file of interest to check state
  curl https://generativelanguage.googleapis.com/v1beta/files/$name > file_info.json
  state=$(jq ".file.state" file_info.json)
done

# Now generate content using that file
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "Describe this video clip"},
          {"file_data":{"mime_type": "video/mp4", "file_uri": '$file_uri'}}]
        }]
       }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json
files.sh

PDF

Python

from google import genai

client = genai.Client()
sample_pdf = client.files.upload(file=media / "test.pdf")
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=["Give me a summary of this pdf file.", sample_pdf],
)
print(response.text)
files.py

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)
}
samplePdf, err := client.Files.UploadFromPath(
	ctx,
	filepath.Join(getMedia(), "test.pdf"),
	&genai.UploadFileConfig{
		MIMEType: "application/pdf",
	},
)
if err != nil {
	log.Fatal(err)
}

parts := []*genai.Part{
	genai.NewPartFromText("Give me a summary of this pdf file."),
	genai.NewPartFromURI(samplePdf.URI, samplePdf.MIMEType),
}

contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}

response, err := client.Models.GenerateContent(ctx, "gemini-2.0-flash", contents, nil)
if err != nil {
	log.Fatal(err)
}
text := response.Text()
fmt.Println(text)
files.go

Antworttext

Antwort für media.upload.

Bei Erfolg enthält der Antworttext Daten mit der folgenden Struktur:

Felder
file object (File)

Metadaten für die erstellte Datei.

JSON-Darstellung 
{
  "file": {
    object (File)
  }
}

Methode: files.get

Ruft die Metadaten für die angegebene File ab.

Endpunkt

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

Pfadparameter

name string

Erforderlich. Der Name der abzurufenden File. Beispiel: files/abc-123 Sie nimmt die Form files/{file} an.

Anfragetext

Der Anfragetext muss leer sein.

Beispielanfrage

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)
files.py

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);
files.js

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)
files.go

Muschel

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_uri
files.sh

Antworttext

Wenn der Vorgang erfolgreich abgeschlossen wurde, enthält der Antworttext eine Instanz von File.

Methode: files.list

Listet die Metadaten für Files auf, die dem anfragenden Projekt gehören.

Endpunkt

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

Suchparameter

pageSize integer

Optional. Maximale Anzahl der zurückzugebenden Files pro Seite. Wenn nicht angegeben, wird der Wert standardmäßig auf 10 gesetzt. Der Höchstwert für pageSize ist 100.

pageToken string

Optional. Ein Seitentoken aus einem vorherigen files.list-Aufruf.

Anfragetext

Der Anfragetext muss leer sein.

Beispielanfrage

Python

from google import genai

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

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();
}
files.js

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)
}
files.go

Muschel

echo "My files: "

curl "https://generativelanguage.googleapis.com/v1beta/files?key=$GEMINI_API_KEY"
files.sh

Antworttext

Antwort für files.list.

Bei Erfolg enthält der Antworttext Daten mit der folgenden Struktur:

Felder
files[] object (File)

Die Liste der Files.

nextPageToken string

Ein Token, das als pageToken in einem nachfolgenden files.list-Aufruf gesendet werden kann.

JSON-Darstellung 
{
  "files": [
    {
      object (File)
    }
  ],
  "nextPageToken": string
}

Methode: files.delete

Löscht die File.

Endpunkt

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

Pfadparameter

name string

Erforderlich. Der Name der zu löschenden File. Beispiel: files/abc-123 Sie nimmt die Form files/{file} an.

Anfragetext

Der Anfragetext muss leer sein.

Beispielanfrage

Python

from google import genai

client = genai.Client()
myfile = client.files.upload(file=media / "poem.txt")

client.files.delete(name=myfile.name)

try:
    result = client.models.generate_content(
        model="gemini-2.0-flash", contents=[myfile, "Describe this file."]
    )
    print(result)
except genai.errors.ClientError:
    pass
files.py

Node.js

// The Gen AI SDK for TypeScript and JavaScript is in preview.
// Some features have not been implemented.
README.md

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)
}
// Delete the file.
_, err = client.Files.Delete(ctx, myfile.Name, nil)
if err != nil {
	log.Fatal(err)
}
// Attempt to use the deleted file.
parts := []*genai.Part{
	genai.NewPartFromURI(myfile.URI, myfile.MIMEType,),
	genai.NewPartFromText("Describe this file."),
}

contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}

_, err = client.Models.GenerateContent(ctx, "gemini-2.0-flash", contents, nil)
// Expect an error when using a deleted file.
if err != nil {
	return nil
}
return fmt.Errorf("expected an error when using deleted file")
files.go

Muschel

curl --request "DELETE" https://generativelanguage.googleapis.com/v1beta/files/$name?key=$GEMINI_API_KEY
files.sh

Antworttext

Wenn der Vorgang erfolgreich abgeschlossen wurde, ist der Antworttext ein leeres JSON-Objekt.

Methode: files.register

Registriert eine Google Cloud Storage-Datei beim FileService. Der Nutzer muss Google Cloud Storage-URIs angeben und erhält im Gegenzug für jeden URI eine Dateiressource. Die Dateien werden nicht kopiert, sondern nur bei der File API registriert. Wenn die Registrierung einer Datei fehlschlägt, schlägt die gesamte Anfrage fehl.

Endpunkt

post https://generativelanguage.googleapis.com/v1beta/files:register

Anfragetext

Der Anfragetext enthält Daten mit folgender Struktur:

Felder
uris[] string

Erforderlich. Die Google Cloud Storage-URIs, die registriert werden sollen. Beispiel: gs://bucket/object.

Antworttext

Antwort für files.register.

Bei Erfolg enthält der Antworttext Daten mit der folgenden Struktur:

Felder
files[] object (File)

Die registrierten Dateien, die beim Aufrufen von GenerateContent verwendet werden sollen.

JSON-Darstellung 
{
  "files": [
    {
      object (File)
    }
  ]
}

REST-Ressource: files

Ressource: Datei

Eine Datei, die in die API hochgeladen wurde. Nächste ID: 15

Felder
name string

Nicht veränderbar. ID. Der Ressourcenname von File. Die ID (Name ohne das Präfix „files/“) darf bis zu 40 Zeichen enthalten, die alphanumerisch in Kleinschreibung oder Bindestriche (-) sein dürfen. Die ID darf nicht mit einem Bindestrich beginnen oder enden. Wenn der Name beim Erstellen leer ist, wird ein eindeutiger Name generiert. Beispiel: files/123-456

displayName string

Optional. Der für Menschen lesbare Anzeigename für File. Der Anzeigename darf maximal 512 Zeichen lang sein, einschließlich Leerzeichen. Beispiel: „Welcome Image“

mimeType string

Nur Ausgabe. MIME-Typ der Datei.

sizeBytes string (int64 format)

Nur Ausgabe. Größe der Datei in Byte.

createTime string (Timestamp format)

Nur Ausgabe. Der Zeitstempel für die Erstellung von File.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30"

updateTime string (Timestamp format)

Nur Ausgabe. Der Zeitstempel der letzten Aktualisierung von File.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30"

expirationTime string (Timestamp format)

Nur Ausgabe. Der Zeitstempel, der angibt, wann die File gelöscht wird. Wird nur festgelegt, wenn das File ablaufen soll.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30"

sha256Hash string (bytes format)

Nur Ausgabe. SHA-256-Hash der hochgeladenen Bytes.

Ein base64-codierter String.

uri string

Nur Ausgabe. Die URI der File.

downloadUri string

Nur Ausgabe. Die Download-URI der File.

state enum (State)

Nur Ausgabe. Verarbeitungsstatus der Datei.

source enum (Source)

Quelle der Datei.

error object (Status)

Nur Ausgabe. Fehlerstatus, wenn die Dateiverarbeitung fehlgeschlagen ist.

metadata Union type
Metadaten für die Datei. Für metadata ist nur einer der folgenden Werte zulässig:
videoMetadata object (VideoFileMetadata)

Nur Ausgabe. Metadaten für ein Video.

JSON-Darstellung 
{
  "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

Metadaten für ein Video File.

Felder
videoDuration string (Duration format)

Dauer des Videos.

Die Dauer in Sekunden mit bis zu neun Nachkommastellen und am Ende mit „s“. Beispiel: "3.5s".

JSON-Darstellung 
{
  "videoDuration": string
}

Bundesland

Zustände für den Lebenszyklus einer Datei.

Enums
STATE_UNSPECIFIED Der Standardwert. Dieser Wert wird verwendet, wenn der Bundesstaat nicht angegeben ist.
PROCESSING Die Datei wird gerade verarbeitet und kann noch nicht für die Inferenz verwendet werden.
ACTIVE Die Datei wurde verarbeitet und ist für die Inferenz verfügbar.
FAILED Die Verarbeitung der Datei ist fehlgeschlagen.

Quelle

Enums
SOURCE_UNSPECIFIED Wird verwendet, wenn keine Quelle angegeben ist.
UPLOADED Gibt an, dass die Datei vom Nutzer hochgeladen wurde.
GENERATED Gibt an, dass die Datei von Google generiert wurde.
REGISTERED Gibt an, dass die Datei registriert ist, d.h. eine Google Cloud Storage-Datei ist.

Status

Mit dem Typ Status wird ein logisches Fehlermodell definiert, das für verschiedene Programmierumgebungen wie REST APIs und RPC APIs geeignet ist. Dieses Modell wird von gRPC verwendet. Jede Status-Meldung enthält die folgenden drei Datenelemente: Fehlercode, Fehlermeldung und Fehlerdetails.

Weitere Informationen zu diesem Fehlermodell und zur Arbeit damit finden Sie in der API-Designanleitung.

Felder
code integer

Der Statuscode, der idealerweise ein ENUM-Wert von google.rpc.Code ist.

message string

Eine an Entwickler gerichtete Fehlermeldung, die englischsprachig sein sollte. Jede für Nutzer sichtbare Fehlermeldung sollte lokalisiert und im Feld google.rpc.Status.details gesendet werden. Sie kann auch clientseitig lokalisiert werden.

details[] object

Eine Auflistung aller Meldungen, die die Fehlerdetails enthalten. Es gibt einen gemeinsamen Satz von Nachrichtentypen, die APIs verwenden können.

Ein Objekt, das Felder eines beliebigen Typs enthält. Ein zusätzliches Feld "@type" enthält einen URI zur Identifizierung des Typs. Beispiel: { "id": 1234, "@type": "types.example.com/standard/id" }.

JSON-Darstellung 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}