سازگاری OpenAI

مدل‌های Gemini با استفاده از کتابخانه‌های OpenAI (پایتون و تایپ‌اسکریپت / جاوااسکریپت) به همراه REST API، با به‌روزرسانی سه خط کد و استفاده از کلید API Gemini شما، قابل دسترسی هستند. اگر قبلاً از کتابخانه‌های OpenAI استفاده نمی‌کردید، توصیه می‌کنیم مستقیماً API Gemini را فراخوانی کنید.

پایتون

from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

response = client.chat.completions.create(
    model="gemini-3-flash-preview",
    messages=[
        {   "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "Explain to me how AI works"
        }
    ]
)

print(response.choices[0].message)

جاوا اسکریپت

import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "GEMINI_API_KEY",
    baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});

const response = await openai.chat.completions.create({
    model: "gemini-3-flash-preview",
    messages: [
        {   role: "system",
            content: "You are a helpful assistant." 
        },
        {
            role: "user",
            content: "Explain to me how AI works",
        },
    ],
});

console.log(response.choices[0].message);

استراحت

curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3-flash-preview",
    "messages": [
      {
        "role": "user",
        "content": "Explain to me how AI works"
      }
    ]
  }'

چه چیزی تغییر کرد؟ فقط سه خط!

  • api_key="GEMINI_API_KEY" : عبارت " GEMINI_API_KEY " را با کلید API واقعی Gemini خود که می‌توانید از Google AI Studio دریافت کنید، جایگزین کنید.

  • base_url="https://generativelanguage.googleapis.com/v1beta/openai/" : این به کتابخانه OpenAI می‌گوید که درخواست‌ها را به جای URL پیش‌فرض، به نقطه پایانی Gemini API ارسال کند.

  • model="gemini-3-flash-preview" : یک مدل سازگار با Gemini را انتخاب کنید

تفکر

مدل‌های Gemini برای تفکر در مورد مسائل پیچیده آموزش دیده‌اند که منجر به بهبود قابل توجه استدلال می‌شود. API Gemini دارای پارامترهای تفکر است که کنترل دقیقی بر میزان تفکر مدل ارائه می‌دهد.

مدل‌های مختلف Gemini پیکربندی‌های استدلال متفاوتی دارند، می‌توانید نحوه‌ی نگاشت آن‌ها به تلاش‌های استدلال OpenAI را به صورت زیر مشاهده کنید:

reasoning_effort (OpenAI) thinking_level (Gemini 3.1 Pro) thinking_level (Gemini 3.1 Flash-Lite) thinking_level (جمینی ۳ فلش) thinking_budget (جمینی ۲.۵)
minimal low minimal minimal 1,024
low low low low 1,024
medium medium medium medium 8,192
high high high high 24,576

اگر هیچ reasoning_effort مشخص نشده باشد، Gemini از سطح یا budget پیش‌فرض مدل استفاده می‌کند.

اگر می‌خواهید قابلیت تفکر را غیرفعال کنید، می‌توانید برای مدل‌های ۲.۵، reasoning_effort روی "none" تنظیم کنید. برای مدل‌های Gemini 2.5 Pro یا ۳، قابلیت Reasoning را نمی‌توان غیرفعال کرد.

پایتون

from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

response = client.chat.completions.create(
    model="gemini-3-flash-preview",
    reasoning_effort="low",
    messages=[
        {   "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "Explain to me how AI works"
        }
    ]
)

print(response.choices[0].message)

جاوا اسکریپت

import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "GEMINI_API_KEY",
    baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});

const response = await openai.chat.completions.create({
    model: "gemini-3-flash-preview",
    reasoning_effort: "low",
    messages: [
        {   role: "system",
            content: "You are a helpful assistant." 
        },
        {
            role: "user",
            content: "Explain to me how AI works",
        },
    ],
});

console.log(response.choices[0].message);

استراحت

curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3-flash-preview",
    "reasoning_effort": "low",
    "messages": [
      {
        "role": "user",
        "content": "Explain to me how AI works"
      }
    ]
  }'

مدل‌های تفکر Gemini همچنین خلاصه‌های فکری تولید می‌کنند. می‌توانید از فیلد extra_body برای گنجاندن فیلدهای Gemini در درخواست خود استفاده کنید.

توجه داشته باشید که reasoning_effort و thinking_level / thinking_budget عملکرد همپوشانی دارند، بنابراین نمی‌توان آنها را همزمان استفاده کرد.

پایتون

from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

response = client.chat.completions.create(
    model="gemini-3-flash-preview",
    messages=[{"role": "user", "content": "Explain to me how AI works"}],
    extra_body={
      'extra_body': {
        "google": {
          "thinking_config": {
            "thinking_level": "low",
            "include_thoughts": True
          }
        }
      }
    }
)

print(response.choices[0].message)

جاوا اسکریپت

import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "GEMINI_API_KEY",
    baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});

const response = await openai.chat.completions.create({
    model: "gemini-3-flash-preview",
    messages: [{role: "user", content: "Explain to me how AI works",}],
    extra_body: {
      "google": {
        "thinking_config": {
          "thinking_level": "low",
          "include_thoughts": true
        }
      }
    }
});

console.log(response.choices[0].message);

استراحت

curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer GEMINI_API_KEY" \
  -d '{
      "model": "gemini-3-flash-preview",
        "messages": [{"role": "user", "content": "Explain to me how AI works"}],
        "extra_body": {
          "google": {
            "thinking_config": {
              "thinking_level": "low",
              "include_thoughts": true
            }
          }
        }
      }'

جمینی ۳ از سازگاری OpenAI برای امضاهای فکری در APIهای تکمیل چت پشتیبانی می‌کند. می‌توانید مثال کامل را در صفحه امضاهای فکری پیدا کنید.

پخش جریانی

رابط برنامه‌نویسی نرم‌افزار Gemini از پاسخ‌های استریمینگ پشتیبانی می‌کند.

پایتون

from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

response = client.chat.completions.create(
  model="gemini-3-flash-preview",
  messages=[
    {
        "role": "system",
        "content": "You are a helpful assistant."
    },
    {   "role": "user",
        "content": "Hello!"
    }
  ],
  stream=True
)

for chunk in response:
    print(chunk.choices[0].delta)

جاوا اسکریپت

import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "GEMINI_API_KEY",
    baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});

async function main() {
  const completion = await openai.chat.completions.create({
    model: "gemini-3-flash-preview",
    messages: [
      {
          "role": "system",
          "content": "You are a helpful assistant."
      },
      {
          "role": "user",
          "content": "Hello!"
      }
    ],
    stream: true,
  });

  for await (const chunk of completion) {
    console.log(chunk.choices[0].delta.content);
  }
}

main();

استراحت

curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer GEMINI_API_KEY" \
  -d '{
      "model": "gemini-3-flash-preview",
      "messages": [
          {"role": "user", "content": "Explain to me how AI works"}
      ],
      "stream": true
    }'

فراخوانی تابع

فراخوانی تابع، دریافت خروجی‌های داده ساختاریافته از مدل‌های مولد را برای شما آسان‌تر می‌کند و در رابط برنامه‌نویسی کاربردی (API) جمینی (Gemini) پشتیبانی می‌شود.

پایتون

from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

tools = [
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get the weather in a given location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. Chicago, IL",
          },
          "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
        },
        "required": ["location"],
      },
    }
  }
]

messages = [{"role": "user", "content": "What's the weather like in Chicago today?"}]
response = client.chat.completions.create(
  model="gemini-3-flash-preview",
  messages=messages,
  tools=tools,
  tool_choice="auto"
)

print(response)

جاوا اسکریپت

import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "GEMINI_API_KEY",
    baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});

async function main() {
  const messages = [{"role": "user", "content": "What's the weather like in Chicago today?"}];
  const tools = [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the weather in a given location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. Chicago, IL",
              },
              "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
            },
            "required": ["location"],
          },
        }
      }
  ];

  const response = await openai.chat.completions.create({
    model: "gemini-3-flash-preview",
    messages: messages,
    tools: tools,
    tool_choice: "auto",
  });

  console.log(response);
}

main();

استراحت

curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer GEMINI_API_KEY" \
-d '{
  "model": "gemini-3-flash-preview",
  "messages": [
    {
      "role": "user",
      "content": "What'\''s the weather like in Chicago today?"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. Chicago, IL"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"]
            }
          },
          "required": ["location"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}'

درک تصویر

مدل‌های Gemini ذاتاً چندوجهی هستند و در بسیاری از وظایف بینایی رایج، بهترین عملکرد را در کلاس خود ارائه می‌دهند.

پایتون

import base64
from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

# Function to encode the image
def encode_image(image_path):
  with open(image_path, "rb") as image_file:
    return base64.b64encode(image_file.read()).decode('utf-8')

# Getting the base64 string
base64_image = encode_image("Path/to/agi/image.jpeg")

response = client.chat.completions.create(
  model="gemini-3-flash-preview",
  messages=[
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is in this image?",
        },
        {
          "type": "image_url",
          "image_url": {
            "url":  f"data:image/jpeg;base64,{base64_image}"
          },
        },
      ],
    }
  ],
)

print(response.choices[0])

جاوا اسکریپت

import OpenAI from "openai";
import fs from 'fs/promises';

const openai = new OpenAI({
  apiKey: "GEMINI_API_KEY",
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});

async function encodeImage(imagePath) {
  try {
    const imageBuffer = await fs.readFile(imagePath);
    return imageBuffer.toString('base64');
  } catch (error) {
    console.error("Error encoding image:", error);
    return null;
  }
}

async function main() {
  const imagePath = "Path/to/agi/image.jpeg";
  const base64Image = await encodeImage(imagePath);

  const messages = [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is in this image?",
        },
        {
          "type": "image_url",
          "image_url": {
            "url": `data:image/jpeg;base64,${base64Image}`
          },
        },
      ],
    }
  ];

  try {
    const response = await openai.chat.completions.create({
      model: "gemini-3-flash-preview",
      messages: messages,
    });

    console.log(response.choices[0]);
  } catch (error) {
    console.error("Error calling Gemini API:", error);
  }
}

main();

استراحت

bash -c '
  base64_image=$(base64 -i "Path/to/agi/image.jpeg");
  curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer GEMINI_API_KEY" \
    -d "{
      \"model\": \"gemini-3-flash-preview\",
      \"messages\": [
        {
          \"role\": \"user\",
          \"content\": [
            { \"type\": \"text\", \"text\": \"What is in this image?\" },
            {
              \"type\": \"image_url\",
              \"image_url\": { \"url\": \"data:image/jpeg;base64,${base64_image}\" }
            }
          ]
        }
      ]
    }"
'

ایجاد یک تصویر

با استفاده از gemini-2.5-flash-image یا gemini-3-pro-image-preview یک تصویر تولید کنید. پارامترهای پشتیبانی شده شامل prompt ، model ، n ، size و response_format هستند. هر پارامتر دیگری که در اینجا یا در بخش extra_body ذکر نشده باشد، توسط لایه سازگاری نادیده گرفته خواهد شد.

پایتون

import base64
from openai import OpenAI
from PIL import Image
from io import BytesIO

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)

response = client.images.generate(
    model="gemini-2.5-flash-image",
    prompt="a portrait of a sheepadoodle wearing a cape",
    response_format='b64_json',
    n=1,
)

for image_data in response.data:
  image = Image.open(BytesIO(base64.b64decode(image_data.b64_json)))
  image.show()

جاوا اسکریپت

import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: "GEMINI_API_KEY",
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});

async function main() {
  const image = await openai.images.generate(
    {
      model: "gemini-2.5-flash-image",
      prompt: "a portrait of a sheepadoodle wearing a cape",
      response_format: "b64_json",
      n: 1,
    }
  );

  console.log(image.data);
}

main();

استراحت

curl "https://generativelanguage.googleapis.com/v1beta/openai/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer GEMINI_API_KEY" \
  -d '{
        "model": "gemini-2.5-flash-image",
        "prompt": "a portrait of a sheepadoodle wearing a cape",
        "response_format": "b64_json",
        "n": 1,
      }'

تولید ویدیو

با استفاده از veo-3.1-generate-preview از طریق نقطه پایانی Sora-compatible /v1/videos یک ویدیو تولید کنید. پارامترهای سطح بالای پشتیبانی شده عبارتند از prompt و model . پارامترهای اضافی مانند duration_seconds ، image و aspect_ratio باید با extra_body ارسال شوند. برای مشاهده همه پارامترهای موجود، به بخش extra_body مراجعه کنید.

تولید ویدیو یک عملیات طولانی‌مدت است که یک شناسه عملیات را برمی‌گرداند که می‌توانید برای تکمیل آن از آن نمونه‌برداری کنید.

پایتون

from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

# Returns a Long Running Operation (status: processing)
response = client.videos.create(
    model="veo-3.1-generate-preview",
    prompt="A cinematic drone shot of a waterfall",
)

print(f"Operation ID: {response.id}")
print(f"Status: {response.status}")

جاوا اسکریپت

import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "GEMINI_API_KEY",
    baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});

async function main() {
    // Returns a Long Running Operation (status: processing)
    const response = await openai.videos.create({
        model: "veo-3.1-generate-preview",
        prompt: "A cinematic drone shot of a waterfall",
    });

    console.log(`Operation ID: ${response.id}`);
    console.log(`Status: ${response.status}`);
}

main();

استراحت

curl "https://generativelanguage.googleapis.com/v1beta/openai/videos" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=A cinematic drone shot of a waterfall"

بررسی وضعیت ویدیو

تولید ویدیو ناهمزمان است. GET /v1/videos/{id} برای نظرسنجی وضعیت و بازیابی URL نهایی ویدیو پس از اتمام استفاده کنید:

پایتون

import time
from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

# Poll until video is ready
video_id = response.id  # From the create call
while True:
    video = client.videos.retrieve(video_id)
    if video.status == "completed":
        print(f"Video URL: {video.url}")
        break
    elif video.status == "failed":
        print(f"Generation failed: {video.error}")
        break
    print(f"Status: {video.status}. Waiting...")
    time.sleep(10)

جاوا اسکریپت

import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "GEMINI_API_KEY",
    baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});

async function main() {
    // Poll until video is ready
    const videoId = response.id;  // From the create call
    while (true) {
        const video = await openai.videos.retrieve(videoId);
        if (video.status === "completed") {
            console.log(`Video URL: ${video.url}`);
            break;
        } else if (video.status === "failed") {
            console.log(`Generation failed: ${video.error}`);
            break;
        }
        console.log(`Status: ${video.status}. Waiting...`);
        await new Promise(resolve => setTimeout(resolve, 10000));
    }
}

main();

استراحت

curl "https://generativelanguage.googleapis.com/v1beta/openai/videos/VIDEO_ID" \
  -H "Authorization: Bearer $GEMINI_API_KEY"

درک صوتی

تجزیه و تحلیل ورودی صدا:

پایتون

import base64
from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

with open("/path/to/your/audio/file.wav", "rb") as audio_file:
  base64_audio = base64.b64encode(audio_file.read()).decode('utf-8')

response = client.chat.completions.create(
    model="gemini-3-flash-preview",
    messages=[
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Transcribe this audio",
        },
        {
              "type": "input_audio",
              "input_audio": {
                "data": base64_audio,
                "format": "wav"
          }
        }
      ],
    }
  ],
)

print(response.choices[0].message.content)

جاوا اسکریپت

import fs from "fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "GEMINI_API_KEY",
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});

const audioFile = fs.readFileSync("/path/to/your/audio/file.wav");
const base64Audio = Buffer.from(audioFile).toString("base64");

async function main() {
  const response = await client.chat.completions.create({
    model: "gemini-3-flash-preview",
    messages: [
      {
        role: "user",
        content: [
          {
            type: "text",
            text: "Transcribe this audio",
          },
          {
            type: "input_audio",
            input_audio: {
              data: base64Audio,
              format: "wav",
            },
          },
        ],
      },
    ],
  });

  console.log(response.choices[0].message.content);
}

main();

استراحت

bash -c '
  base64_audio=$(base64 -i "/path/to/your/audio/file.wav");
  curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer GEMINI_API_KEY" \
    -d "{
      \"model\": \"gemini-3-flash-preview\",
      \"messages\": [
        {
          \"role\": \"user\",
          \"content\": [
            { \"type\": \"text\", \"text\": \"Transcribe this audio file.\" },
            {
              \"type\": \"input_audio\",
              \"input_audio\": {
                \"data\": \"${base64_audio}\",
                \"format\": \"wav\"
              }
            }
          ]
        }
      ]
    }"
'

خروجی ساختاریافته

مدل‌های Gemini می‌توانند اشیاء JSON را در هر ساختاری که شما تعریف می‌کنید، خروجی دهند.

پایتون

from pydantic import BaseModel
from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

completion = client.beta.chat.completions.parse(
    model="gemini-3-flash-preview",
    messages=[
        {"role": "system", "content": "Extract the event information."},
        {"role": "user", "content": "John and Susan are going to an AI conference on Friday."},
    ],
    response_format=CalendarEvent,
)

print(completion.choices[0].message.parsed)

جاوا اسکریپت

import OpenAI from "openai";
import { zodResponseFormat } from "openai/helpers/zod";
import { z } from "zod";

const openai = new OpenAI({
    apiKey: "GEMINI_API_KEY",
    baseURL: "https://generativelanguage.googleapis.com/v1beta/openai"
});

const CalendarEvent = z.object({
  name: z.string(),
  date: z.string(),
  participants: z.array(z.string()),
});

const completion = await openai.chat.completions.parse({
  model: "gemini-3-flash-preview",
  messages: [
    { role: "system", content: "Extract the event information." },
    { role: "user", content: "John and Susan are going to an AI conference on Friday" },
  ],
  response_format: zodResponseFormat(CalendarEvent, "event"),
});

const event = completion.choices[0].message.parsed;
console.log(event);

جاسازی‌ها

جاسازی‌های متنی میزان ارتباط رشته‌های متنی را اندازه‌گیری می‌کنند و می‌توانند با استفاده از API Gemini ایجاد شوند. می‌توانید gemini-embedding-2-preview برای جاسازی‌های چندوجهی یا gemini-embedding-001 برای جاسازی‌های فقط متنی استفاده کنید.

پایتون

from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

response = client.embeddings.create(
    input="Your text string goes here",
    model="gemini-embedding-2-preview"
)

print(response.data[0].embedding)

جاوا اسکریپت

import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "GEMINI_API_KEY",
    baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});

async function main() {
  const embedding = await openai.embeddings.create({
    model: "gemini-embedding-2-preview",
    input: "Your text string goes here",
  });

  console.log(embedding);
}

main();

استراحت

curl "https://generativelanguage.googleapis.com/v1beta/openai/embeddings" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer GEMINI_API_KEY" \
-d '{
    "input": "Your text string goes here",
    "model": "gemini-embedding-2-preview"
  }'

API دسته‌ای

شما می‌توانید با استفاده از کتابخانه OpenAI، کارهای دسته‌ای ایجاد کنید، آنها را ارسال کنید و وضعیت آنها را بررسی کنید.

شما باید فایل JSONL را با فرمت ورودی OpenAI آماده کنید. برای مثال:

{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gemini-3-flash-preview", "messages": [{"role": "user", "content": "Tell me a one-sentence joke."}]}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gemini-3-flash-preview", "messages": [{"role": "user", "content": "Why is the sky blue?"}]}}

سازگاری OpenAI برای Batch از ایجاد یک Batch، نظارت بر وضعیت کار و مشاهده نتایج Batch پشتیبانی می‌کند.

سازگاری برای آپلود و دانلود در حال حاضر پشتیبانی نمی‌شود. در عوض، مثال زیر از کلاینت genai برای آپلود و دانلود فایل‌ها استفاده می‌کند، همانند زمانی که از Gemini Batch API استفاده می‌کنیم.

پایتون

from openai import OpenAI

# Regular genai client for uploads & downloads
from google import genai
client = genai.Client()

openai_client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

# Upload the JSONL file in OpenAI input format, using regular genai SDK
uploaded_file = client.files.upload(
    file='my-batch-requests.jsonl',
    config=types.UploadFileConfig(display_name='my-batch-requests', mime_type='jsonl')
)

# Create batch
batch = openai_client.batches.create(
    input_file_id=batch_input_file_id,
    endpoint="/v1/chat/completions",
    completion_window="24h"
)

# Wait for batch to finish (up to 24h)
while True:
    batch = client.batches.retrieve(batch.id)
    if batch.status in ('completed', 'failed', 'cancelled', 'expired'):
        break
    print(f"Batch not finished. Current state: {batch.status}. Waiting 30 seconds...")
    time.sleep(30)
print(f"Batch finished: {batch}")

# Download results in OpenAI output format, using regular genai SDK
file_content = genai_client.files.download(file=batch.output_file_id).decode('utf-8')

# See batch_output JSONL in OpenAI output format
for line in file_content.splitlines():
    print(line)    

کیت توسعه نرم‌افزار OpenAI همچنین از تولید جاسازی‌ها با استفاده از Batch API پشتیبانی می‌کند. برای انجام این کار، فیلد endpoint متد create را با یک نقطه پایانی جاسازی‌ها و همچنین کلیدهای url و model را در فایل JSONL جایگزین کنید:

# JSONL file using embeddings model and endpoint
# {"custom_id": "request-1", "method": "POST", "url": "/v1/embeddings", "body": {"model": "ggemini-embedding-001", "messages": [{"role": "user", "content": "Tell me a one-sentence joke."}]}}
# {"custom_id": "request-2", "method": "POST", "url": "/v1/embeddings", "body": {"model": "gemini-embedding-001", "messages": [{"role": "user", "content": "Why is the sky blue?"}]}}

# ...

# Create batch step with embeddings endpoint
batch = openai_client.batches.create(
    input_file_id=batch_input_file_id,
    endpoint="/v1/embeddings",
    completion_window="24h"
)

برای مشاهده‌ی یک مثال کامل، به بخش تولید جاسازی دسته‌ای در کتاب راهنمای سازگاری OpenAI مراجعه کنید.

فعال کردن ویژگی‌های Gemini با extra_body

چندین ویژگی توسط Gemini پشتیبانی می‌شوند که در مدل‌های OpenAI موجود نیستند اما می‌توان آن‌ها را با استفاده از فیلد extra_body فعال کرد.

پارامتر نوع نقطه پایانی توضیحات
cached_content متن چت مربوط به حافظه پنهان محتوای عمومی Gemini است.
thinking_config شیء چت مربوط به ThinkingConfig در Gemini است.
aspect_ratio متن تصاویر نسبت ابعاد خروجی (مثلاً "16:9" ، "1:1" ، "9:16" ).
generation_config شیء تصاویر شیء پیکربندی نسل Gemini (به عنوان مثال، {"responseModalities": ["IMAGE"], "candidateCount": 2} ).
safety_settings فهرست تصاویر فیلترهای آستانه ایمنی سفارشی (به عنوان مثال، [{"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE"}] ).
tools فهرست تصاویر فعال کردن اتصال به زمین (grounding) (مثلاً [{"google_search": {}}] ). فقط برای gemini-3-pro-image-preview .
aspect_ratio متن ویدئو ابعاد ویدیوی خروجی ( 16:9 برای حالت افقی، 9:16 برای حالت عمودی). در صورت عدم مشخص شدن size ، آن را از روی آن رسم می‌کند.
resolution متن ویدئو وضوح خروجی ( 720p ، 1080p ، 4K ). توجه: 1080p و 4K باعث فعال شدن خط لوله upsampler می‌شوند.
duration_seconds عدد صحیح ویدئو طول نسل (مقادیر: 4 ، 6 ، 8 ). هنگام استفاده از reference_images ، درون‌یابی یا افزونه، باید 8 باشد.
frame_rate متن ویدئو نرخ فریم برای خروجی ویدئو (مثلاً "24" ).
input_reference متن ویدئو ورودی مرجع برای تولید ویدیو.
extend_video_id متن ویدئو شناسه‌ی ویدیوی موجود برای گسترش.
negative_prompt متن ویدئو مواردی که باید حذف شوند (مثلاً "shaky camera" ).
seed عدد صحیح ویدئو عدد صحیح برای تولید قطعی.
style متن ویدئو استایل بصری (پیش‌فرض cinematic ، creative برای رسانه‌های اجتماعی بهینه شده).
person_generation متن ویدئو تولید افراد ( allow_adult ، allow_all ، dont_allow ) را کنترل می‌کند.
reference_images فهرست ویدئو حداکثر ۳ تصویر برای ارجاع به سبک/کاراکتر (دارایی‌های base64).
image متن ویدئو تصویر ورودی اولیه کدگذاری شده با Base64 برای شرط بندی تولید ویدیو.
last_frame شیء ویدئو تصویر نهایی برای درون‌یابی (نیاز به image به عنوان فریم اول دارد).

مثال با استفاده از extra_body

در اینجا مثالی از استفاده از extra_body برای تنظیم cached_content آورده شده است:

پایتون

from openai import OpenAI

client = OpenAI(
    api_key=MY_API_KEY,
    base_url="https://generativelanguage.googleapis.com/v1beta/"
)

stream = client.chat.completions.create(
    model="gemini-3-flash-preview",
    n=1,
    messages=[
        {
            "role": "user",
            "content": "Summarize the video"
        }
    ],
    stream=True,
    stream_options={'include_usage': True},
    extra_body={
        'extra_body':
        {
            'google': {
              'cached_content': "cachedContents/0000aaaa1111bbbb2222cccc3333dddd4444eeee"
          }
        }
    }
)

for chunk in stream:
    print(chunk)
    print(chunk.usage.to_dict())

مدل‌ها را فهرست کنید

لیستی از مدل‌های موجود Gemini را دریافت کنید:

پایتون

from openai import OpenAI

client = OpenAI(
  api_key="GEMINI_API_KEY",
  base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

models = client.models.list()
for model in models:
  print(model.id)

جاوا اسکریپت

import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: "GEMINI_API_KEY",
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});

async function main() {
  const list = await openai.models.list();

  for await (const model of list) {
    console.log(model);
  }
}
main();

استراحت

curl https://generativelanguage.googleapis.com/v1beta/openai/models \
-H "Authorization: Bearer GEMINI_API_KEY"

بازیابی یک مدل

یک مدل Gemini را بازیابی کنید:

پایتون

from openai import OpenAI

client = OpenAI(
  api_key="GEMINI_API_KEY",
  base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

model = client.models.retrieve("gemini-3-flash-preview")
print(model.id)

جاوا اسکریپت

import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: "GEMINI_API_KEY",
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});

async function main() {
  const model = await openai.models.retrieve("gemini-3-flash-preview");
  console.log(model.id);
}

main();

استراحت

curl https://generativelanguage.googleapis.com/v1beta/openai/models/gemini-3-flash-preview \
-H "Authorization: Bearer GEMINI_API_KEY"

محدودیت‌های فعلی

پشتیبانی از کتابخانه‌های OpenAI هنوز در مرحله بتا است، در حالی که ما پشتیبانی از ویژگی‌ها را گسترش می‌دهیم.

اگر در مورد پارامترهای پشتیبانی‌شده، ویژگی‌های آینده سؤالی دارید یا در شروع کار با Gemini با مشکلی مواجه شدید، به انجمن توسعه‌دهندگان ما بپیوندید.

قدم بعدی چیست؟

برای کار با مثال‌های دقیق‌تر، از OpenAI Compatibility Colab ما استفاده کنید.