يمكن أن يحلّل Gemini الإدخال الصوتي ويفهمه، ما يتيح حالات استخدام مثل التالية:
- وصف المحتوى الصوتي أو تلخيصه أو الإجابة عن أسئلة حوله
- قدِّم نصًا للمحتوى الصوتي.
- تحليل أجزاء معيّنة من الملف الصوتي
يوضّح لك هذا الدليل كيفية استخدام Gemini API لإنشاء ردّ نصي على إدخال صوتي.
قبل البدء
قبل استدعاء واجهة برمجة التطبيقات Gemini API، تأكَّد من تثبيت حزمة تطوير البرامج (SDK) المفضّلة لديك ، وضبط مفتاح واجهة برمجة التطبيقات Gemini API وجاهزيته للاستخدام.
إدخال الصوت
يمكنك تقديم بيانات صوتية إلى Gemini بالطُرق التالية:
- حمِّل ملفًا صوتيًا قبل إرسال طلب إلى
generateContent
. - أرسِل بيانات الصوت المضمّنة مع الطلب إلى
generateContent
.
تحميل ملف صوتي
يمكنك استخدام واجهة برمجة التطبيقات Files API لتحميل ملف صوتي. استخدِم دائمًا Files API عندما يكون إجمالي حجم الطلب (بما في ذلك الملفات والطلبات النصية وتعليمات النظام وما إلى ذلك) أكبر من 20 ميغابايت.
تحمِّل التعليمة البرمجية التالية ملفًا صوتيًا، ثم تستخدم الملف في طلب موجَّه إلى
generateContent
.
from google import genai
client = genai.Client(api_key="GOOGLE_API_KEY")
myfile = client.files.upload(file="path/to/sample.mp3")
response = client.models.generate_content(
model="gemini-2.0-flash", contents=["Describe this audio clip", myfile]
)
print(response.text)
import {
GoogleGenAI,
createUserContent,
createPartFromUri,
} from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
async function main() {
const myfile = await ai.files.upload({
file: "path/to/sample.mp3",
config: { mimeType: "audio/mp3" },
});
const response = await ai.models.generateContent({
model: "gemini-2.0-flash",
contents: createUserContent([
createPartFromUri(myfile.uri, myfile.mimeType),
"Describe this audio clip",
]),
});
console.log(response.text);
}
await main();
file, err := client.UploadFileFromPath(ctx, "path/to/sample.mp3", nil)
if err != nil {
log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)
model := client.GenerativeModel("gemini-2.0-flash")
resp, err := model.GenerateContent(ctx,
genai.FileData{URI: file.URI},
genai.Text("Describe this audio clip"))
if err != nil {
log.Fatal(err)
}
printResponse(resp)
AUDIO_PATH="path/to/sample.mp3"
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 "https://generativelanguage.googleapis.com/upload/v1beta/files?key=${GOOGLE_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-2.0-flash:generateContent?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[
{"text": "Describe this audio clip"},
{"file_data":{"mime_type": "${MIME_TYPE}", "file_uri": '$file_uri'}}]
}]
}' 2> /dev/null > response.json
cat response.json
echo
jq ".candidates[].content.parts[].text" response.json
للاطّلاع على مزيد من المعلومات عن العمل مع ملفات الوسائط، يمكنك الاطّلاع على Files API.
تمرير بيانات الصوت مضمّنة
بدلاً من تحميل ملف صوتي، يمكنك تمرير بيانات صوتية مضمّنة في
الطلب إلى generateContent
:
from google.genai import types
with open('path/to/small-sample.mp3', 'rb') as f:
audio_bytes = f.read()
response = client.models.generate_content(
model='gemini-2.0-flash',
contents=[
'Describe this audio clip',
types.Part.from_bytes(
data=audio_bytes,
mime_type='audio/mp3',
)
]
)
print(response.text)
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";
const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
const base64AudioFile = fs.readFileSync("path/to/small-sample.mp3", {
encoding: "base64",
});
const contents = [
{ text: "Please summarize the audio." },
{
inlineData: {
mimeType: "audio/mp3",
data: base64AudioFile,
},
},
];
const response = await ai.models.generateContent({
model: "gemini-2.0-flash",
contents: contents,
});
console.log(response.text);
// Initialize a Gemini model appropriate for your use case.
model := client.GenerativeModel("gemini-2.0-flash")
bytes, err := os.ReadFile("path/to/small-sample.mp3")
if err != nil {
log.Fatal(err)
}
prompt := []genai.Part{
genai.Blob{MIMEType: "audio/mp3", Data: bytes},
genai.Text("Please summarize the audio."),
}
// Generate content using the prompt.
resp, err := model.GenerateContent(ctx, prompt...)
if err != nil {
log.Fatal(err)
}
// Handle the response of generated text
for _, c := range resp.Candidates {
if c.Content != nil {
fmt.Println(*c.Content)
}
}
في ما يلي بعض النقاط التي يجب أخذها في الاعتبار بشأن بيانات الصوت المضمّنة:
- الحد الأقصى لحجم الطلب هو 20 ميغابايت، ويشمل الطلبات طلبات نصية وتعليمات النظام والملفات المقدَّمة مضمّنة. إذا كان حجم ملفك يؤدي إلى تجاوز إجمالي حجم الطلب 20 ميغابايت، يمكنك استخدام واجهة برمجة التطبيقات Files API من أجل تحميل ملف صوتي لاستخدامه في الطلب.
- إذا كنت تستخدم عيّنة صوتية عدة مرات، من الأفضل تحميل ملف صوتي.
الحصول على نص
للحصول على نص للبيانات الصوتية، ما عليك سوى طلبه في الطلب:
myfile = client.files.upload(file='path/to/sample.mp3')
prompt = 'Generate a transcript of the speech.'
response = client.models.generate_content(
model='gemini-2.0-flash',
contents=[prompt, myfile]
)
print(response.text)
import {
GoogleGenAI,
createUserContent,
createPartFromUri,
} from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
const myfile = await ai.files.upload({
file: "path/to/sample.mp3",
config: { mimeType: "audio/mpeg" },
});
const result = await ai.models.generateContent({
model: "gemini-2.0-flash",
contents: createUserContent([
createPartFromUri(myfile.uri, myfile.mimeType),
"Generate a transcript of the speech.",
]),
});
console.log("result.text=", result.text);
// Initialize a Gemini model appropriate for your use case.
model := client.GenerativeModel("gemini-2.0-flash")
// Create a prompt using text and the URI reference for the uploaded file.
prompt := []genai.Part{
genai.FileData{URI: sampleAudio.URI},
genai.Text("Generate a transcript of the speech."),
}
// Generate content using the prompt.
resp, err := model.GenerateContent(ctx, prompt...)
if err != nil {
log.Fatal(err)
}
// Handle the response of generated text
for _, c := range resp.Candidates {
if c.Content != nil {
fmt.Println(*c.Content)
}
}
الرجوع إلى الطوابع الزمنية
يمكنك الإشارة إلى أقسام معيّنة من ملف صوتي باستخدام الطوابع الزمنية من النوع
MM:SS
. على سبيل المثال، يطلب الطلب التالي نصًا يحتوي على
- يبدأ بعد مرور دقيقتين و30 ثانية من بداية الملف.
تنتهي عند 3 دقائق و29 ثانية من بداية الملف.
# Create a prompt containing timestamps.
prompt = "Provide a transcript of the speech from 02:30 to 03:29."
// Create a prompt containing timestamps.
const prompt = "Provide a transcript of the speech from 02:30 to 03:29."
// Create a prompt containing timestamps.
prompt := []genai.Part{
genai.FileData{URI: sampleAudio.URI},
genai.Text("Provide a transcript of the speech from 02:30 to 03:29."),
}
احتساب الرموز المميّزة
استخدِم الطريقة countTokens
للحصول على عدد الرموز المميّزة فيملف صوتي. على سبيل المثال:
response = client.models.count_tokens(
model='gemini-2.0-flash',
contents=[myfile]
)
print(response)
import {
GoogleGenAI,
createUserContent,
createPartFromUri,
} from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
const myfile = await ai.files.upload({
file: "path/to/sample.mp3",
config: { mimeType: "audio/mpeg" },
});
const countTokensResponse = await ai.models.countTokens({
model: "gemini-2.0-flash",
contents: createUserContent([
createPartFromUri(myfile.uri, myfile.mimeType),
]),
});
console.log(countTokensResponse.totalTokens);
tokens, err := model.CountTokens(ctx, genai.FileData{URI: sampleAudio.URI})
if err != nil {
log.Fatal(err)
}
fmt.Printf("File %s is %d tokens", sampleAudio.DisplayName, tokens.TotalTokens)
تنسيقات الصوت المتوافقة
يتوافق Gemini مع أنواع MIME التالية لتنسيقات الصوت:
- WAV -
audio/wav
- MP3 -
audio/mp3
- AIFF -
audio/aiff
- AAC -
audio/aac
- OGG Vorbis -
audio/ogg
- FLAC -
audio/flac
التفاصيل الفنية حول الصوت
- يمثّل Gemini كل ثانية من المحتوى الصوتي على شكل 32 رمزًا، على سبيل المثال، يتم تمثيل دقيقة واحدة من المحتوى الصوتي على شكل 1,920 رمزًا.
- لا يمكن لخدمة Gemini استنتاج الردود إلا على المحتوى الصوتي باللغة الإنجليزية.
- يمكن أن "يفهم" Gemini المكونات غير الكلامية، مثل أصوات الطيور أو صفارات الإنذار.
- الحد الأقصى المسموح به لطول البيانات الصوتية في طلب واحد هو 9.5 ساعة. لا تفرض خدمة Gemini قيودًا على عدد الملفات الصوتية في طلب واحد، ولكن لا يمكن أن تتجاوز المدّة الإجمالية لجميع الملفات الصوتية في طلب واحد 9.5 ساعة.
- تُجري خدمة Gemini خفضًا في دقة ملفات الصوت إلى 16 كيلوبت في الثانية.
- إذا كان مصدر الصوت يتضمّن قنوات متعددة، يدمج Gemini هذه القنوات في قناة واحدة.
الخطوات التالية
يوضِّح هذا الدليل كيفية إنشاء نص استجابةً للبيانات الصوتية. لمزيد من المعلومات، يُرجى الاطّلاع على المراجع التالية:
- استراتيجيات طلب الملفات: تتيح واجهة برمجة التطبيقات Gemini API طلب البيانات النصية والمرئية والصوتية والفيديوية، والتي تُعرف أيضًا باسم طلبات البيانات المتعددة الوسائط.
- تعليمات النظام: تتيح لك تعليمات النظام توجيه سلوك النموذج استنادًا إلى احتياجاتك وحالات الاستخدام المحدّدة.
- إرشادات السلامة: في بعض الأحيان، تُنتج نماذج الذكاء الاصطناعي التوليدي نتائج غير متوقّعة، مثل النتائج غير الدقيقة أو المُتحيّزة أو المسيئة. إنّ المعالجة اللاحقة والتقييم البشري ضروريان لمحاولة الحد من خطر الضرر الناتج عن هذه النتائج.