تتيح واجهة Gemini API تحميل ملفات وسائط بشكل منفصل عن إدخالات الطلب، ما يتيح إعادة استخدام الوسائط في طلبات متعددة وطلبات متعددة. لمزيد من التفاصيل، يمكنك الاطّلاع على دليل الطلب باستخدام الوسائط.
الطريقة: media.upload
ينشئ File
.
نقطة نهاية
- تحميل عنوان URI، لطلبات تحميل الوسائط:
https://generativelanguage.googleapis.com/upload/v1beta/files
- معرّف الموارد المنتظم (URI) للبيانات الوصفية لطلبات البيانات الوصفية فقط:
https://generativelanguage.googleapis.com/v1beta/files
نص الطلب
يحتوي نص الطلب على بيانات بالبنية التالية:
file
object (File
)
اختياريّ. البيانات الوصفية للملف الذي سيتم إنشاؤه
مثال على الطلب
صورة
Python
Node.js
البدء
صَدفة
الصوت
Python
Node.js
البدء
صَدفة
النص
Python
Node.js
البدء
صَدفة
فيديو
Python
Node.js
البدء
صَدفة
Python
الطريقة: Files.get
توفر هذه الطريقة البيانات الوصفية الخاصة بـ File
المحدّد.
نقطة نهاية
الحصول على
https://generativelanguage.googleapis.com/v1beta/{name=files/*}
مَعلمات المسار
name
string
مطلوب. اسم File
المطلوب الحصول عليه. مثال: files/abc-123
تأخذ الشكل files/{file}
.
نص الطلب
يجب أن يكون نص الطلب فارغًا.
مثال على الطلب
Python
Node.js
البدء
صَدفة
نص الاستجابة
إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على مثال File
.
الطريقة: Files.list
يسرد البيانات الوصفية لتطبيقات File
التي يملكها المشروع الذي يقدّم الطلب.
نقطة نهاية
الحصول على
https://generativelanguage.googleapis.com/v1beta/files
معامِلات طلب البحث
pageSize
integer
اختياريّ. الحد الأقصى لعدد الثواني التي يمكن عرضها في كل صفحة هو File
. وفي حال عدم تحديد قيمة، يتم ضبط القيمة التلقائية على 10. الحد الأقصى لعدد pageSize
هو 100 طلب.
pageToken
string
اختياريّ. رمز مميّز للصفحة من استدعاء files.list
سابق.
نص الطلب
يجب أن يكون نص الطلب فارغًا.
مثال على الطلب
Python
Node.js
البدء
صَدفة
نص الاستجابة
ردّ على files.list
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
files[]
object (File
)
قائمة File
.
nextPageToken
string
هو رمز مميّز يمكن إرساله على أنّه pageToken
في استدعاء files.list
لاحق.
تمثيل JSON |
---|
{
"files": [
{
object ( |
الطريقة: Files.delete
يؤدي النقر على هذا الزر إلى حذف File
.
نقطة نهاية
حذف
https://generativelanguage.googleapis.com/v1beta/{name=files/*}
مَعلمات المسار
name
string
مطلوب. اسم File
المطلوب حذفه. مثال: files/abc-123
تأخذ الشكل files/{file}
.
نص الطلب
يجب أن يكون نص الطلب فارغًا.
مثال على الطلب
Python
Node.js
البدء
صَدفة
نص الاستجابة
إذا كانت الاستجابة ناجحة، يكون نص الاستجابة فارغًا.
مورد REST: الملفات
المرجع: ملف
ملف تم تحميله إلى واجهة برمجة التطبيقات
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
)
النتائج فقط. البيانات الوصفية للفيديو.
تمثيل JSON |
---|
{ "name": string, "displayName": string, "mimeType": string, "sizeBytes": string, "createTime": string, "updateTime": string, "expirationTime": string, "sha256Hash": string, "uri": string, "state": enum ( |
VideoMetadata
البيانات الوصفية للفيديو File
videoDuration
string (Duration
format)
تشير هذه العلامة إلى مدة الفيديو.
مدة بالثواني مكونة من تسعة أرقام كسور كحد أقصى وتنتهي بالأرقام "s
" مثال: "3.5s"
تمثيل JSON |
---|
{ "videoDuration": string } |
الحالة
الحالات التي تشملها دورة حياة الملف
عمليات التعداد | |
---|---|
STATE_UNSPECIFIED |
القيمة التلقائية. يتم استخدام هذه القيمة إذا تم حذف الحالة. |
PROCESSING |
تتم معالجة الملف ولا يمكن استخدامه للاستنتاج بعد. |
ACTIVE |
تتم معالجة الملف ويمكن استنتاجه. |
FAILED |
تعذّرت معالجة الملف. |
الحالة
يحدّد النوع Status
نموذج خطأ منطقي مناسبًا لبيئات البرمجة المختلفة، بما في ذلك واجهات برمجة تطبيقات REST وواجهات برمجة تطبيقات RPC. وتُستخدَم من قِبل gRPC. تحتوي كل رسالة Status
على ثلاث بيانات: رمز الخطأ ورسالة الخطأ وتفاصيل الخطأ.
يمكنك معرفة المزيد من المعلومات عن نموذج الخطأ هذا وكيفية التعامل معه في دليل تصميم واجهة برمجة التطبيقات.
code
integer
رمز الحالة، الذي يجب أن يكون قيمة تعداد بقيمة google.rpc.Code
.
message
string
رسالة خطأ مواجهة للمطوِّر، ويجب أن تكون باللغة الإنجليزية يجب ترجمة أي رسالة خطأ تظهر للمستخدم وإرسالها في الحقل google.rpc.Status.details
، أو ترجمتها من خلال البرنامج.
details[]
object
قائمة بالرسائل التي تتضمّن تفاصيل الخطأ. هناك مجموعة شائعة من أنواع الرسائل يمكن لواجهات برمجة التطبيقات استخدامها.
كائن يحتوي على حقول من نوع عشوائي يحتوي الحقل الإضافي "@type"
على معرف موارد منتظم (URI) يحدّد النوع. مثال: { "id": 1234, "@type": "types.example.com/standard/id" }
تمثيل JSON |
---|
{ "code": integer, "message": string, "details": [ { "@type": string, field1: ..., ... } ] } |