كيفية استخدام Gemini Omni 1.1 Flash API

تستدعي Gemini Omni 1.1 Flash باستخدام معرّف النموذج gemini-omni-1.1-flash من خلال واجهة برمجة تطبيقات التفاعلات (Interactions API) من Google، وليس نقطة النهاية generateContent التي تستخدمها لنماذج النصوص. هذا هو أول شيء يربك المستخدمين. إذا نسخت مقتطفًا نصيًا من Gemini وبدّلت اسم النموذج، فستحصل على خطأ 404.

يرشدك هذا الدليل من طرفية فارغة إلى طلب إنشاء فيديو تم اختباره. ستحصل على مفتاح، وتجري أول استدعاء لك في curl و Python، وتتعرف على المعلمات الموجودة (والقائمة المفاجئة التي لا توجد)، وتتعامل مع الاستجابات الكبيرة، وتحفظ كل ذلك كاختبار قابل للتكرار.

أصبح النموذج متاحًا بشكل عام (GA) في 27 أغسطس 2026. لمعرفة ما تم إصداره معه، انظر ما الجديد في Gemini Omni 1.1 Flash.

ما تحتاجه قبل أن تبدأ

حساب Google لتسجيل الدخول إلى AI Studio.
مفتاح Gemini API من Google AI Studio.
تفعيل الفوترة. لا تحتوي Omni على طبقة مجانية، على عكس المسار المجاني لنماذج النصوص. طلبك الأول سيكلفك المال.
طريقة لإرسال طلبات HTTP: مثل curl، أو حزمة Python SDK، أو عميل API.

احفظ المفتاح كمتغير بيئة بدلاً من لصقه في الكود المصدري:

export GEMINI_API_KEY="your_key_here"

تقرأ حزم SDK الرسمية هذا المتغير تلقائيًا، مما يحافظ على سرية المفتاح بعيدًا عن مستودعك.

أول استدعاء لإنشاء الفيديو الخاص بك

نقطة النهاية هي طلب POST إلى /v1beta/interactions. إليك كيفية القيام بذلك في curl:

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-1.1-flash",
    "input": "A marble rolling fast on a chain reaction style track, continuous smooth shot."
  }'

حقلان: النموذج والمدخلات. هذا هو الحد الأدنى للطلب. تحمل الاستجابة الفيديو الذي تم إنشاؤه بصيغة base64 في output_video.data.

في Python، قم بتثبيت حزمة SDK باستخدام pip install google-genai، ثم:

import base64
from google import genai

client = genai.Client()  # reads GEMINI_API_KEY from the environment

interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input="A marble rolling fast on a chain reaction style track, continuous smooth shot.",
)

with open("marble.mp4", "wb") as f:
    f.write(base64.b64decode(interaction.output_video.data))

تتبع JavaScript نفس النمط مع @google/genai:

import { GoogleGenAI } from '@google/genai';
import * as fs from 'fs';

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: 'gemini-omni-1.1-flash',
  input: 'A marble rolling fast on a chain reaction style track, continuous smooth shot.',
});

if (interaction.output_video?.data) {
  fs.writeFileSync('marble.mp4', Buffer.from(interaction.output_video.data, 'base64'));
}

يستغرق الإنشاء وقتًا. تتأثر مدة الاستجابة بالمدة، والدقة، وحِمل واجهة برمجة التطبيقات الحالي، لذا اضبط مهلة زمنية سخية للعميل قبل أن تقرر أن هناك خطأ ما.

التحكم في الدقة ونسبة العرض إلى الارتفاع

كل ما يتعلق بتنسيق الإخراج يذهب إلى response_format:

interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input="A drone shot of a mountain landscape at sunrise.",
    response_format={
        "type": "video",
        "aspect_ratio": "16:9",
        "resolution": "1080p",
    },
)

القيم المقبولة:

الحقل	القيم	الافتراضي
`type`	`video`	`video`
`aspect_ratio`	`16:9`, `9:16`	`16:9`
`resolution`	`360p`, `720p`, `1080p`, `4k`	`720p`
`delivery`	base64 مضمّن, `uri`	مضمّن

قم بالمسودة بدقة 360p. يُنشئ بسرعة تصل إلى 60% أسرع من 720p ويكلف ثلث السعر، لذا فإن محاولاتك الخمس عشرة الفاشلة ستكلف ما كانت تكلفه خمس محاولات في السابق. أعد عرض الفيديو الذي تحتفظ به بدقة أعلى. الدقتان 1080p و 4k هما ترقية (upscale) للإطارات التي تم إنشاؤها، وليست عروضًا أصلية. يعرض تفصيل الأسعار التكلفة الفعلية لكل مستوى لكل ثانية.

المعلمات غير الموجودة

هذه القائمة أهم من القائمة أعلاه، لأنك بخلاف ذلك ستهدر وقتًا طويلاً:

لا توجد تعليمات نظام
لا توجد temperature
لا توجد top_p
لا توجد تسلسلات توقف
لا يوجد حقل مطالبات سلبية

إذا كنت بحاجة إلى استبعاد شيء من اللقطة، فاكتب الاستبعاد في المطالبة نفسها. المثال الخاص بالوثائق يفعل ذلك تمامًا: "استخدم الرسم كدليل للحركة فقط، ولا تُظهر الرسم في الفيديو النهائي."

مدخلات الصور، والإطارات المفتاحية، والمراجع

مرر قائمة بدلاً من سلسلة نصية عندما تريد تضمين الوسائط. تحويل الصورة إلى فيديو:

interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input=[
        {"type": "image", "data": base64_image, "mime_type": "image/jpeg"},
        {"type": "text", "text": "turn this into realistic footage, using the drawing only as a guide for movement, do not show the drawing in the final video"},
    ],
)

تصبح صورتان إطارًا أولًا وإطارًا أخيرًا، وينشئ النموذج الحركة بينهما:

interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input=[
        {"type": "image", "data": first_frame_b64, "mime_type": "image/jpeg"},
        {"type": "image", "data": last_frame_b64, "mime_type": "image/jpeg"},
        {"type": "text", "text": "A smooth cinematic transition from a lush green forest at sunrise to a snowy forest under a starry night sky."},
    ],
)

تعمل مراجع الفيديو بنفس الطريقة من خلال Files API، بحد أقصى ثلاثة مقاطع مدة كل منها ثلاث ثوانٍ. يتم تجاهل الصوت في تلك المقاطع؛ يقرأ النموذج هذه المقاطع للحركة والمظهر.

التحرير متعدد الأدوار

هذا ما يميز Omni عن نقطة نهاية تحويل النص إلى فيديو العادية. أنشئ مرة واحدة، ثم حرر بشكل تفاعلي عن طريق تمرير معرّف التفاعل السابق:

res1 = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input="A woman playing violin outdoors.",
)

res2 = client.interactions.create(
    model="gemini-omni-1.1-flash",
    previous_interaction_id=res1.id,
    input="Make the violin invisible.",
)

لا حاجة لإعادة الرفع، ولا لإعادة وصف المشهد. نفس الآلية تدعم تمديد المشهد، وهو ما يتم تناوله في دليل التمديد لمدة 40 ثانية.

التعامل مع الفيديوهات التي تتجاوز 4 ميجابايت

أي شيء أكبر من 4 ميجابايت يعود كمعرف URI بدلاً من base64 المضمّن، ويجب أن يكتمل معالجة الملف قبل أن تتمكن من تنزيله. هذا هو الخطأ الذي يواجهه معظم الأشخاص عند دقة 1080p: يقوم المعالج الخاص بهم بقراءة output_video.data، فلا يجد شيئًا، ويبلغ عن فشل صامت.

اطلب تسليم URI صراحةً وقم بالاستعلام بشكل دوري (poll):

import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input="A beautiful sunset.",
    response_format={"type": "video", "delivery": "uri"},
)

video_output = interaction.output_video
file_name = video_output.uri.split("/")[-1]

while True:
    f_info = client.files.get(name=f"files/{file_name}")
    if f_info.state.name == "ACTIVE":
        break
    if f_info.state.name == "FAILED":
        raise RuntimeError("Generation failed.")
    time.sleep(5)

video_bytes = client.files.download(file=video_output.uri)
with open("output.mp4", "wb") as f:
    f.write(video_bytes)

اكتب معالج الاستجابة الخاص بك ليقبل كلا الشكلين من البداية. تغيير الدقة يغير الشكل الذي تحصل عليه.

اختبار الطلب في Apidog

بمجرد نجاح الاستدعاء، تتغير المشكلة. لديك الآن نقطة نهاية مكلفة، بطيئة، وغير حتمية تقع في مسارك الحرج، وتحتاج إلى معرفة متى يتغير سلوكها. أوامر curl المخصصة في سجل الأوامر (shell history) لن تخبرك بذلك.

قم بإعداده مرة واحدة في Apidog:

أنشئ مشروعًا وبيئة. ضع GEMINI_API_KEY و MODEL_ID في متغيرات البيئة لكي لا يظهر المفتاح في الطلب المحفوظ.
أضف الطلب. أرسل طلب POST إلى https://generativelanguage.googleapis.com/v1beta/interactions، مع نص JSON يحتوي على model و input. ارجع إلى المتغيرات باستخدام {{MODEL_ID}}.
زد المهلة الزمنية. يستغرق إنشاء الفيديو وقتًا أطول بكثير من إكمال النص، وستقوم المهلة الزمنية الافتراضية للعميل بقطعه.
أضف تأكيدات (Assertions). تحقق من رمز الحالة، وتأكد من وجود output_video، وتحقق من شكل الاستجابة الذي تتوقعه بدقتك. هذا هو التأكيد الذي يكتشف التبديل بين المضمّن (inline) و URI.
كرر لكل نوع مهمة. طلب محفوظ واحد لكل من تحويل النص إلى فيديو، والصورة إلى فيديو، والتمديد. عندما تصدر Google الإصدار Omni 1.2، ستجري ثلاثة طلبات وستعرف في دقائق ما الذي تغير.

Apidog لا ينشئ فيديوهات وهو ليس إطار عمل للذكاء الاصطناعي. إنه المكان الذي تبني فيه الطلب، ترسله، وتحتفظ بالاستجابة وفقًا لمعيار تحدده أنت. قم بتنزيل Apidog إذا كنت تريد هذا الإطار في مكانه قبل زيادة الإنفاق.

الأخطاء الشائعة والحلول

خطأ 404 في نقطة النهاية. أنت تستدعي /v1beta/models/gemini-omni-1.1-flash:generateContent. بينما تستخدم Omni /v1beta/interactions مع تحديد النموذج في نص الطلب.

output_video.data فارغ. عادت الاستجابة كمعرف URI لأن الفيديو تجاوز 4 ميجابايت. اقرأ output_video.uri وقم بالتنزيل من خلال Files API.

النموذج غير موجود. تحقق من وجود gemini-omni-flash-preview في إعداداتك. ستتوقف نقطة النهاية هذه عن العمل في 30 سبتمبر 2026.

فشل تحرير الفيديو المرفوع. تحرير الفيديوهات المرفوعة غير متاح في المنطقة الاقتصادية الأوروبية (EEA) وسويسرا والمملكة المتحدة. الفيديوهات التي ينشئها النموذج لا تزال تعمل هناك.

رفض طلب التمديد. تقتصر الفيديوهات المدخلة على 10 ثوانٍ، والتمديد يضيف فقط إلى النهاية، ولا يمكنك إضافة حوار عند تمديد فيديو تم رفعه.

الأسئلة الشائعة

ما هي نقطة النهاية التي تستخدمها Gemini Omni؟ POST https://generativelanguage.googleapis.com/v1beta/interactions، مع gemini-omni-1.1-flash في نص الطلب.

هل هناك طبقة مجانية لواجهة برمجة تطبيقات Gemini Omni؟ لا. يتم احتساب التكلفة لكل عملية إنشاء. نماذج النصوص هي التي تحتوي على مسار مجاني في AI Studio.

هل يمكنني تعيين temperature أو مطالبة سلبية؟ لا. تعليمات النظام، temperature، top_p، تسلسلات التوقف، والمطالبات السلبية كلها غير مدعومة. ضع الاستثناءات في نص المطالبة.

كيف أنشئ فيديو عمودي؟ اضبط aspect_ratio على 9:16 في response_format.

هل الفيديوهات التي تم إنشاؤها تحتوي على علامة مائية؟ نعم. جميع المخرجات تحمل SynthID، غير مرئية للمشاهدين وقابلة للاكتشاف برمجياً.

كيف يقارن هذا بواجهة برمجة تطبيقات Veo؟ نقطة نهاية مختلفة، تسعير مختلف، نقاط قوة مختلفة. تغطي مقارنة Omni 1.1 Flash و Veo 3.1 المقايضة، ويحتوي دليل Veo 3.1 API على تفاصيل هذا التكامل.

التكامل بأكمله يتكون من حقلين مطلوبين بالإضافة إلى معالج استجابة يتعامل مع كلا شكلي التسليم. ابدأ بتشغيل استدعاء بدقة 360p أولاً، واحفظه مع التأكيدات، ثم ارفع الدقة بمجرد أن تثق في الآلية. اقرأ وثائق Omni الرسمية للاطلاع على قائمة المعلمات مع تطورها.