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

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

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

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

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

الميزة v1 v1beta
إمكانات واجهة برمجة التطبيقات الأساسية
Interactions API
استدعاء الدوال
الناتج المنظَّم
التفكير / الاستدلال
تعليمات النظام
إخراج الصوت (إعدادات الكلام)
فئة الخدمة (أولوية / مرنة)
الأدوات
أداة تنفيذ الرموز البرمجية
تحديد المصدر في "بحث Google"
تحديد المصدر في "خرائط Google"
أداة "سياق عناوين URL"
أداة البحث عن الملفات
أداة استخدام الكمبيوتر
أداة خوادم MCP
واجهات برمجة التطبيقات في الوقت الفعلي
Live API (WebSockets)
Live Music API
الرموز المميزة المؤقتة (Live API)
واجهات برمجة التطبيقات الخاصة بالمنصة
Models API
مسار خدمة الملفات
مسار "البحث في الملفات"
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.8-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.8-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(""));

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, &genai.ClientConfig{
        HTTPOptions: genai.HTTPOptions{
            APIVersion: "v1",
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.6-flash"),
            Input: interactions.NewInteractionsInput("Explain how AI works"),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

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.8-flash",
    "input": "Explain how AI works",
  }'