建立檔案¶
POST https://generativelanguage.googleapis.com/v1beta/files
建立 File。
要求主體¶
file: File
選填。要建立之檔案的中繼資料。
範例要求
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-3.8-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
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-3.8-flash",
contents=[
myfile,
"\n\n",
"Can you tell me about the instruments in this photo?",
],
)
print(f"{result.text=}")
// 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-3.8-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);
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-3.8-flash", contents, nil)
if err != nil {
log.Fatal(err)
}
text := response.Text()
fmt.Printf("result.text=%s\n", text)
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-3.8-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
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-3.8-flash", contents=[myfile, "Describe this audio clip"]
)
print(f"{result.text=}")
// 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-3.8-flash',
contents: createUserContent([
createPartFromUri(myfile.uri, myfile.mimeType),
'Describe this audio clip',
]),
});
console.log('result.text=', result.text);
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-3.8-flash", contents, nil)
if err != nil {
log.Fatal(err)
}
text := response.Text()
fmt.Printf("result.text=%s\n", text)
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-3.8-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
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-3.8-flash",
contents=[myfile, "\n\n", "Can you add a few more lines to this poem?"],
)
print(f"{result.text=}")
// 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-3.8-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);
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-3.8-flash", contents, nil)
if err != nil {
log.Fatal(err)
}
text := response.Text()
fmt.Printf("result.text=%s\n", text)
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-3.8-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
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-3.8-flash", contents=[myfile, "Describe this video clip"]
)
print(f"{result.text=}")
// 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-3.8-flash',
contents: createUserContent([
createPartFromUri(myfile.uri, myfile.mimeType),
'Describe this video clip',
]),
});
console.log('result.text=', result.text);
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-3.8-flash", contents, nil)
if err != nil {
log.Fatal(err)
}
text := response.Text()
fmt.Printf("result.text=%s\n", text)
from google import genai
client = genai.Client()
sample_pdf = client.files.upload(file=media / "test.pdf")
response = client.models.generate_content(
model="gemini-3.8-flash",
contents=["Give me a summary of this pdf file.", sample_pdf],
)
print(response.text)
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-3.8-flash", contents, nil)
if err != nil {
log.Fatal(err)
}
text := response.Text()
fmt.Println(text)
回應¶
file: File
所建立檔案的中繼資料。
資源¶
File¶
上傳至 API 的檔案。
屬性:
**metadata**: `Union type` File 的中繼資料。
聯合欄位 `metadata` 只能是下列其中之一:**videoMetadata**: `VideoFileMetadata` 僅供輸出。影片的中繼資料。
**videoDuration**: `string` 影片的長度。name: string
不可變動。識別碼。File 的資源名稱。ID(名稱不含 "files/" 前置字串)最多可包含 40 個字元,限小寫英數字元或連字號 (-)。ID 不得以連字號開頭或結尾。若建立時名稱為空,將產生唯一名稱。範例:files/123-456
displayName: string
選填。File 的人類可讀顯示名稱。顯示名稱的長度不得超過 512 個字元(含空格)。範例:"Welcome Image"
mimeType: string
僅供輸出。檔案的 MIME 類型。
sizeBytes: string
僅供輸出。檔案大小(以位元組計)。
createTime: string
僅供輸出。File 建立時間的時間戳記。
updateTime: string
僅供輸出。File 上次更新的時間戳記。
expirationTime: string
僅供輸出。File 將被刪除的時間戳記。僅在 File 已排定到期時才會設定。
sha256Hash: string
僅供輸出。所上傳位元組的 SHA-256 雜湊。
uri: string
僅供輸出。File 的 uri。
downloadUri: string
僅供輸出。File 的下載 uri。
**state**: `string enum` 僅供輸出。File 的處理狀態。
可能的值: - `STATE_UNSPECIFIED`:預設值。省略狀態時使用此值。 - `PROCESSING`:檔案正在處理中,尚無法用於推論。 - `ACTIVE`:檔案已處理完成,可用於推論。 - `FAILED`:檔案處理失敗。**source**: `string enum` File 的來源。
可能的值: - `SOURCE_UNSPECIFIED`:未指定來源時使用。 - `UPLOADED`:表示檔案由使用者上傳。 - `GENERATED`:表示檔案由 Google 產生。 - `REGISTERED`:表示檔案為已註冊的檔案,即 Google Cloud Storage 檔案。error: Status
僅供輸出。File 處理失敗時的錯誤狀態。
資料模型¶
Status¶
Status 類型定義了一種邏輯錯誤模型,適用於各種程式設計環境,包括 REST API 與 RPC API。此模型由 gRPC 使用。每個 Status 訊息包含三項資料:錯誤碼、錯誤訊息與錯誤詳細資訊。
如需進一步瞭解此錯誤模型以及如何使用,請參閱 API Design Guide。
屬性:
code: integer
狀態碼,應為 google.rpc.Code 的列舉值。
message: string
供開發人員參考的錯誤訊息,應以英文撰寫。任何要給使用者看的錯誤訊息都應本地化,並放在 google.rpc.Status.details 欄位中傳送,或由用戶端本地化。
details: object array
承載錯誤詳細資訊的訊息清單。API 有一組通用的訊息類型可供使用。