شرح إصدارات واجهة برمجة التطبيقات

يقدّم هذا المستند نظرة عامة شاملة على الاختلافات بين الإصدارين v1 وv1beta من Gemini API.

  • v1: إصدار ثابت من واجهة برمجة التطبيقات تتوفّر الميزات في الإصدار الثابت بشكل كامل طوال فترة توفّر رقم الإصدار الرئيسي. في حال حدوث أي تغييرات قد تؤدي إلى عطل، سيتم إنشاء رقم إصدار رئيسي جديد من واجهة برمجة التطبيقات وسيتم إيقاف الإصدار الحالي نهائيًا بعد فترة زمنية معقولة. قد يتم إدخال تغييرات غير متوافقة مع الإصدارات السابقة على واجهة برمجة التطبيقات بدون تغيير الإصدار الرئيسي. تتوفّر Interactions API وميزاتها الأساسية بشكل عام في v1.
  • v1beta: يتضمّن هذا الإصدار ميزات وإمكانات مبكرة لا تزال قيد التطوير. مع أنّ الميزات في v1beta قد تخضع لتغييرات أثناء تحسينها استنادًا إلى الملاحظات، يتيح لك هذا الإصدار تجربة إمكانات جديدة قبل أن تتم ترقيتها إلى إصدار ثابت.

التوافق مع الإمكانات والميزات

يوضّح الجدول التالي تفاصيل مدى توفّر الإمكانات في v1 (إصدار متاح للجميع) وv1beta (إصدار تجريبي). تنطبق إمكانات وأدوات واجهة برمجة التطبيقات الأساسية على كل من واجهة برمجة التطبيقات Interactions API وgenerateContent ما لم يُذكر خلاف ذلك:

الميزة v1 v1beta
إمكانات Core API
Interactions API
استدعاء الدوال
الناتج المنظَّم
التفكير / الاستدلال
تعليمات النظام
إخراج الصوت (إعدادات الكلام)
فئة الخدمة (أولوية / مرنة)
الأدوات
أداة تنفيذ الرموز البرمجية
تحديد المصدر في "بحث Google"
الاستناد إلى بيانات "خرائط Google"
أداة "سياق عناوين URL"
أداة البحث عن الملفات
أداة استخدام الكمبيوتر
أداة خوادم MCP
واجهات برمجة التطبيقات في الوقت الفعلي
واجهة برمجة التطبيقات Live API (WebSockets)
Live Music API
الرموز المميزة المؤقتة (Live API)
واجهات برمجة التطبيقات الخاصة بالمنصة
Models API
مسار خدمة الملفات
File Search Stores Route
Agents API
Webhooks API
التخزين المؤقت للسياق
  • - متوافق

ضبط إصدار واجهة برمجة التطبيقات في حزمة تطوير البرامج (SDK)

تستخدِم حِزم تطوير البرامج (SDK) الخاصة بواجهة Gemini API الإصدار v1beta تلقائيًا، ولكن يمكنك تحديد الإصدارات بشكل صريح من خلال ضبط إصدار واجهة برمجة التطبيقات كما هو موضّح في عينة التعليمات البرمجية التالية:

Python

from google import genai

client = genai.Client(http_options={'api_version': 'v1'})

interaction = client.interactions.create(
    model='gemini-3.7-flash',
    input="Explain how AI works",
)

print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  httpOptions: { apiVersion: "v1" },
});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.7-flash",
    input: "Explain how AI works",
  });
  console.log(interaction.output_text);
}

await main();

جافا

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.HttpOptions;

Client client = Client.builder()
    .httpOptions(HttpOptions.builder().apiVersion("v1").build())
    .build();

CreateModelInteraction req = CreateModelInteraction.builder()
    .model(Model.of("gemini-3.6-flash"))
    .input(InteractionsInput.of("Explain how AI works"))
    .build();
var interaction = client.interactions.create(CreateInteractionRequestBody.of(req)).interaction().get();
System.out.println(interaction.outputText().orElse(""));

REST

curl -X POST "https://generativelanguage.googleapis.com/v1/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.7-flash",
    "input": "Explain how AI works",
  }'