Using files

الطريقة: media.upload

ينشئ File.

نقطة نهاية

تحميل معرف الموارد المنتظم (URI)، لطلبات تحميل الوسائط:
`المشاركة
https://generativelanguage.googleapis.com/upload/v1beta/files

  • معرّف الموارد المنتظم (URI) للبيانات الوصفية لطلبات البيانات الوصفية فقط:
    POST https://generativelanguage.googleapis.com/v1beta/filesيستخدم عنوان URL بنية تحويل الترميز gRPC.

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

الحقول
file object (File)

اختياريّ. البيانات الوصفية للملف الذي سيتم إنشاؤه

مثال على الطلب

صورة

Python

myfile = genai.upload_file(media / "Cajun_instruments.jpg")
print(f"{myfile=}")

model = genai.GenerativeModel("gemini-1.5-flash")
result = model.generate_content(
    [myfile, "\n\n", "Can you tell me about the instruments in this photo?"]
)
print(f"{result.text=}")

Node.js

// Make sure to include these imports:
// import { GoogleAIFileManager } from "@google/generative-ai/server";
// import { GoogleGenerativeAI } from "@google/generative-ai";
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(
  `${mediaPath}/jetpack.jpg`,
  {
    mimeType: "image/jpeg",
    displayName: "Jetpack drawing",
  },
);
// View the response.
console.log(
  `Uploaded file ${uploadResult.file.displayName} as: ${uploadResult.file.uri}`,
);

const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
const result = await model.generateContent([
  "Tell me about this image.",
  {
    fileData: {
      fileUri: uploadResult.file.uri,
      mimeType: uploadResult.file.mimeType,
    },
  },
]);
console.log(result.response.text());

الصوت

Python

myfile = genai.upload_file(media / "sample.mp3")
print(f"{myfile=}")

model = genai.GenerativeModel("gemini-1.5-flash")
result = model.generate_content([myfile, "Describe this audio clip"])
print(f"{result.text=}")

Node.js

// Make sure to include these imports:
// import { GoogleAIFileManager, FileState } from "@google/generative-ai/server";
// import { GoogleGenerativeAI } from "@google/generative-ai";
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(
  `${mediaPath}/samplesmall.mp3`,
  {
    mimeType: "audio/mp3",
    displayName: "Audio sample",
  },
);

let file = await fileManager.getFile(uploadResult.file.name);
while (file.state === FileState.PROCESSING) {
  process.stdout.write(".");
  // Sleep for 10 seconds
  await new Promise((resolve) => setTimeout(resolve, 10_000));
  // Fetch the file from the API again
  file = await fileManager.getFile(uploadResult.file.name);
}

if (file.state === FileState.FAILED) {
  throw new Error("Audio processing failed.");
}

// View the response.
console.log(
  `Uploaded file ${uploadResult.file.displayName} as: ${uploadResult.file.uri}`,
);

const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
const result = await model.generateContent([
  "Tell me about this audio clip.",
  {
    fileData: {
      fileUri: uploadResult.file.uri,
      mimeType: uploadResult.file.mimeType,
    },
  },
]);
console.log(result.response.text());

النص

Python

myfile = genai.upload_file(media / "poem.txt")
print(f"{myfile=}")

model = genai.GenerativeModel("gemini-1.5-flash")
result = model.generate_content(
    [myfile, "\n\n", "Can you add a few more lines to this poem?"]
)
print(f"{result.text=}")

Node.js

// Make sure to include these imports:
// import { GoogleAIFileManager } from "@google/generative-ai/server";
// import { GoogleGenerativeAI } from "@google/generative-ai";
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(`${mediaPath}/a11.txt`, {
  mimeType: "text/plain",
  displayName: "Apollo 11",
});
// View the response.
console.log(
  `Uploaded file ${uploadResult.file.displayName} as: ${uploadResult.file.uri}`,
);

const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
const result = await model.generateContent([
  "Transcribe the first few sentences of this document.",
  {
    fileData: {
      fileUri: uploadResult.file.uri,
      mimeType: uploadResult.file.mimeType,
    },
  },
]);
console.log(result.response.text());

فيديو

Python

import time

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

# Videos need to be processed before you can use them.
while myfile.state.name == "PROCESSING":
    print("processing video...")
    time.sleep(5)
    myfile = genai.get_file(myfile.name)

model = genai.GenerativeModel("gemini-1.5-flash")
result = model.generate_content([myfile, "Describe this video clip"])
print(f"{result.text=}")

Node.js

// Make sure to include these imports:
// import { GoogleAIFileManager, FileState } from "@google/generative-ai/server";
// import { GoogleGenerativeAI } from "@google/generative-ai";
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(
  `${mediaPath}/Big_Buck_Bunny.mp4`,
  {
    mimeType: "video/mp4",
    displayName: "Big Buck Bunny",
  },
);

let file = await fileManager.getFile(uploadResult.file.name);
while (file.state === FileState.PROCESSING) {
  process.stdout.write(".");
  // Sleep for 10 seconds
  await new Promise((resolve) => setTimeout(resolve, 10_000));
  // Fetch the file from the API again
  file = await fileManager.getFile(uploadResult.file.name);
}

if (file.state === FileState.FAILED) {
  throw new Error("Video processing failed.");
}

// View the response.
console.log(
  `Uploaded file ${uploadResult.file.displayName} as: ${uploadResult.file.uri}`,
);

const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
const result = await model.generateContent([
  "Tell me about this video.",
  {
    fileData: {
      fileUri: uploadResult.file.uri,
      mimeType: uploadResult.file.mimeType,
    },
  },
]);
console.log(result.response.text());

نص الاستجابة

ردّ على media.upload

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

الحقول
file object (File)

البيانات الوصفية للملف الذي تم إنشاؤه.

تمثيل JSON
{
  "file": {
    object (File)
  }
}

الطريقة: Files.get

توفر هذه الطريقة البيانات الوصفية الخاصة بـ File المحدّد.

نقطة نهاية

الحصول على https://generativelanguage.googleapis.com/v1beta/{name=files/*}

مَعلمات المسار

name string

مطلوب. اسم File المطلوب الحصول عليه. مثال: files/abc-123 تأخذ الشكل files/{file}.

نص الطلب

يجب أن يكون نص الطلب فارغًا.

مثال على الطلب

Python

myfile = genai.upload_file(media / "poem.txt")
file_name = myfile.name
print(file_name)  # "files/*"

myfile = genai.get_file(file_name)
print(myfile)

Node.js

// Make sure to include these imports:
// import { GoogleAIFileManager } from "@google/generative-ai/server";
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResponse = await fileManager.uploadFile(
  `${mediaPath}/jetpack.jpg`,
  {
    mimeType: "image/jpeg",
    displayName: "Jetpack drawing",
  },
);

// Get the previously uploaded file's metadata.
const getResponse = await fileManager.getFile(uploadResponse.file.name);

// View the response.
console.log(
  `Retrieved file ${getResponse.displayName} as ${getResponse.uri}`,
);

نص الاستجابة

إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على مثال File.

الطريقة: Files.list

يسرد البيانات الوصفية لتطبيقات File التي يملكها المشروع الذي يقدّم الطلب.

نقطة نهاية

الحصول على https://generativelanguage.googleapis.com/v1beta/files

معامِلات طلب البحث

pageSize integer

اختياريّ. الحد الأقصى لعدد الثواني التي يمكن عرضها في كل صفحة هو File. وفي حال عدم تحديد قيمة، يتم ضبط القيمة التلقائية على 10. الحد الأقصى لعدد pageSize هو 100 طلب.

pageToken string

اختياريّ. رمز مميّز للصفحة من استدعاء files.list سابق.

نص الطلب

يجب أن يكون نص الطلب فارغًا.

مثال على الطلب

Python

print("My files:")
for f in genai.list_files():
    print("  ", f.name)

Node.js

// Make sure to include these imports:
// import { GoogleAIFileManager } from "@google/generative-ai/server";
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const listFilesResponse = await fileManager.listFiles();

// View the response.
for (const file of listFilesResponse.files) {
  console.log(`name: ${file.name} | display name: ${file.displayName}`);
}

نص الاستجابة

ردّ على files.list

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

الحقول
files[] object (File)

قائمة File.

nextPageToken string

هو رمز مميّز يمكن إرساله على أنّه pageToken في استدعاء files.list لاحق.

تمثيل JSON
{
  "files": [
    {
      object (File)
    }
  ],
  "nextPageToken": string
}

الطريقة: Files.delete

يؤدي النقر على هذا الزر إلى حذف File.

نقطة نهاية

حذف https://generativelanguage.googleapis.com/v1beta/{name=files/*}

مَعلمات المسار

name string

مطلوب. اسم File المطلوب حذفه. مثال: files/abc-123 تأخذ الشكل files/{file}.

نص الطلب

يجب أن يكون نص الطلب فارغًا.

مثال على الطلب

Python

myfile = genai.upload_file(media / "poem.txt")

myfile.delete()

try:
    # Error.
    model = genai.GenerativeModel("gemini-1.5-flash")
    result = model.generate_content([myfile, "Describe this file."])
except google.api_core.exceptions.PermissionDenied:
    pass

Node.js

// Make sure to include these imports:
// import { GoogleAIFileManager } from "@google/generative-ai/server";
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(
  `${mediaPath}/jetpack.jpg`,
  {
    mimeType: "image/jpeg",
    displayName: "Jetpack drawing",
  },
);

// Delete the file.
await fileManager.deleteFile(uploadResult.file.name);

console.log(`Deleted ${uploadResult.file.displayName}`);

نص الاستجابة

إذا كانت الاستجابة ناجحة، يكون نص الاستجابة فارغًا.

مورد REST: الملفات

المرجع: ملف

ملف تم تحميله إلى واجهة برمجة التطبيقات

تمثيل JSON
{
  "name": string,
  "displayName": string,
  "mimeType": string,
  "sizeBytes": string,
  "createTime": string,
  "updateTime": string,
  "expirationTime": string,
  "sha256Hash": string,
  "uri": string,
  "state": enum (State),
  "error": {
    object (Status)
  },

  // Union field metadata can be only one of the following:
  "videoMetadata": {
    object (VideoMetadata)
  }
  // End of list of possible types for union field metadata.
}
الحقول
name string

غير قابل للتغيير. المُعرّف. اسم المورد "File". يمكن أن يحتوي رقم التعريف (الاسم باستثناء البادئة "files/") على 40 حرفًا أبجديًا رقميًا صغيرًا أو شرطات (-). لا يمكن أن يبدأ المعرّف أو ينتهي بشرطة. إذا كان الاسم فارغًا عند الإنشاء، سيتم إنشاء اسم فريد. مثلاً: files/123-456

displayName string

اختياريّ. تمثّل هذه السمة الاسم المعروض لـ File الذي يمكن للمستخدمين قراءته. يجب ألا يزيد طول الاسم المعروض عن 512 حرفًا، بما في ذلك المسافات. مثال: "صورة ترحيبية"

mimeType string

النتائج فقط. نوع MIME للملف.

sizeBytes string (int64 format)

النتائج فقط. حجم الملف بالبايت.

createTime string (Timestamp format)

النتائج فقط. الطابع الزمني لوقت إنشاء File

طابع زمني بتنسيق RFC3339 حسب التوقيت العالمي المنسَّق (UTC) "زولو" بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z".

updateTime string (Timestamp format)

النتائج فقط. الطابع الزمني لوقت آخر تحديث لـ File.

طابع زمني بتنسيق RFC3339 حسب التوقيت العالمي المنسَّق (UTC) "زولو" بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z".

expirationTime string (Timestamp format)

النتائج فقط. الطابع الزمني لوقت حذف File لا يتم ضبط هذا الإعداد إلا في حال تحديد موعد انتهاء صلاحية File.

طابع زمني بتنسيق RFC3339 حسب التوقيت العالمي المنسَّق (UTC) "زولو" بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z".

sha256Hash string (bytes format)

النتائج فقط. تجزئة SHA-256 لوحدات البايت التي تم تحميلها

سلسلة بترميز base64.

uri string

النتائج فقط. تمثّل هذه السمة معرّف الموارد المنتظم (URI) الخاص بالسمة File.

state enum (State)

النتائج فقط. حالة معالجة الملف

error object (Status)

النتائج فقط. حالة خطأ في حال تعذُّر معالجة الملف

حقل الاتحاد metadata. البيانات الوصفية للملف يمكن أن يكون metadata واحدًا فقط مما يلي:
videoMetadata object (VideoMetadata)

النتائج فقط. البيانات الوصفية للفيديو.

VideoMetadata

البيانات الوصفية للفيديو File

تمثيل JSON
{
  "videoDuration": string
}
الحقول
videoDuration string (Duration format)

تشير هذه العلامة إلى مدة الفيديو.

مدة بالثواني مكونة من تسعة أرقام كسور كحد أقصى وتنتهي بـ "s" مثال: "3.5s"

الحالة

الحالات التي تشملها دورة حياة الملف

عمليات التعداد
STATE_UNSPECIFIED القيمة التلقائية. يتم استخدام هذه القيمة إذا تم حذف الحالة.
PROCESSING تتم معالجة الملف ولا يمكن استخدامه للاستنتاج بعد.
ACTIVE تتم معالجة الملف ويمكن استنتاجه.
FAILED تعذّرت معالجة الملف.

الحالة

يحدّد النوع Status نموذج خطأ منطقي مناسبًا لبيئات البرمجة المختلفة، بما في ذلك واجهات برمجة تطبيقات REST وواجهات برمجة تطبيقات RPC. وتُستخدَم من قِبل gRPC. تحتوي كل رسالة Status على ثلاث بيانات: رمز الخطأ ورسالة الخطأ وتفاصيل الخطأ.

يمكنك معرفة المزيد من المعلومات عن نموذج الخطأ هذا وكيفية التعامل معه في دليل تصميم واجهة برمجة التطبيقات.

تمثيل JSON
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
الحقول
code integer

رمز الحالة، الذي يجب أن يكون قيمة تعداد بقيمة google.rpc.Code.

message string

رسالة خطأ تظهر باللغة الإنجليزية يجب ترجمة أي رسالة خطأ تظهر للمستخدم وإرسالها في الحقل google.rpc.Status.details، أو ترجمتها من خلال البرنامج.

details[] object

قائمة بالرسائل التي تتضمّن تفاصيل الخطأ. وهناك مجموعة شائعة من أنواع الرسائل التي يمكن لواجهات برمجة التطبيقات استخدامها.

كائن يحتوي على حقول من نوع عشوائي يحتوي الحقل الإضافي "@type" على معرف موارد منتظم (URI) يحدّد النوع. مثال: { "id": 1234, "@type": "types.example.com/standard/id" }