Repository Public
1<br />23Gemini models are accessible using the OpenAI libraries (Python and TypeScript /4Javascript) along with the REST API, by updating three lines of code5and using your [Gemini API key](https://aistudio.google.com/apikey). If you6aren't already using the OpenAI libraries, we recommend that you call the7[Gemini API directly](https://ai.google.dev/gemini-api/docs/get-started).89### Python1011 from openai import OpenAI1213 client = OpenAI(14 api_key="GEMINI_API_KEY",15 base_url="https://generativelanguage.googleapis.com/v1beta/openai/"16 )1718 response = client.chat.completions.create(19 model="gemini-3.8-flash",20 messages=[21 { "role": "system",22 "content": "You are a helpful assistant."23 },24 {25 "role": "user",26 "content": "Explain to me how AI works"27 }28 ]29 )3031 print(response.choices[0].message)3233### JavaScript3435 import OpenAI from "openai";3637 const openai = new OpenAI({38 apiKey: "GEMINI_API_KEY",39 baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"40 });4142 const response = await openai.chat.completions.create({43 model: "gemini-3.8-flash",44 messages: [45 { role: "system",46 content: "You are a helpful assistant." 47 },48 {49 role: "user",50 content: "Explain to me how AI works",51 },52 ],53 });5455 console.log(response.choices[0].message);5657### REST5859 curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \60 -H "Content-Type: application/json" \61 -H "Authorization: Bearer $GEMINI_API_KEY" \62 -d '{63 "model": "gemini-3.8-flash",64 "messages": [65 {66 "role": "user",67 "content": "Explain to me how AI works"68 }69 ]70 }'7172What changed? Just three lines!7374- **`api_key="GEMINI_API_KEY"`** : Replace "`GEMINI_API_KEY`" with your actual Gemini75 API key, which you can get in [Google AI Studio](https://aistudio.google.com).7677- **`base_url="https://generativelanguage.googleapis.com/v1beta/openai/"`:** This78 tells the OpenAI library to send requests to the Gemini API endpoint instead of79 the default URL.8081- **`model="gemini-3.8-flash"`**: Choose a compatible Gemini model8283## Thinking8485Gemini models are trained to think through complex problems, leading86to significantly improved reasoning. The Gemini API comes with [thinking87parameters](https://ai.google.dev/gemini-api/docs/thinking) which give fine grain88control over how much the model will think.8990Different Gemini models have different reasoning configurations, you can see how91they map to OpenAI's reasoning efforts as follows:9293| `reasoning_effort` (OpenAI) | `thinking_level` (Gemini 3.1 Pro) | `thinking_level` (Gemini 3.1 Flash-Lite) | `thinking_level` (Gemini 3 Flash) | `thinking_budget` (Gemini 2.5) |94| `reasoning_effort` (OpenAI) | `thinking_level` (Gemini 3.1 Pro) | `thinking_level` (Gemini 3.1 Flash-Lite) | `thinking_level` (Gemini 3 Flash) | `thinking_budget` (Gemini 2.5) |95|---|---|---|---|---|96| `minimal` | `low` | `minimal` | `minimal` | `1,024` |97| `low` | `low` | `low` | `low` | `1,024` |98| `medium` | `medium` | `medium` | `medium` | `8,192` |99| `high` | `high` | `high` | `high` | `24,576` |100101If no `reasoning_effort` is specified, Gemini uses the model's102default [level](https://ai.google.dev/gemini-api/docs/thinking#levels) or [budget](https://ai.google.dev/gemini-api/docs/thinking#set-budget).103104If you want to disable thinking, you can set `reasoning_effort` to `"none"` for1052.5 models. Reasoning cannot be turned off for Gemini 2.5 Pro or 3 models.106107### Python108109 from openai import OpenAI110111 client = OpenAI(112 api_key="GEMINI_API_KEY",113 base_url="https://generativelanguage.googleapis.com/v1beta/openai/"114 )115116 response = client.chat.completions.create(117 model="gemini-3.8-flash",118 reasoning_effort="low",119 messages=[120 { "role": "system",121 "content": "You are a helpful assistant."122 },123 {124 "role": "user",125 "content": "Explain to me how AI works"126 }127 ]128 )129130 print(response.choices[0].message)131132### JavaScript133134 import OpenAI from "openai";135136 const openai = new OpenAI({137 apiKey: "GEMINI_API_KEY",138 baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"139 });140141 const response = await openai.chat.completions.create({142 model: "gemini-3.8-flash",143 reasoning_effort: "low",144 messages: [145 { role: "system",146 content: "You are a helpful assistant." 147 },148 {149 role: "user",150 content: "Explain to me how AI works",151 },152 ],153 });154155 console.log(response.choices[0].message);156157### REST158159 curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \160 -H "Content-Type: application/json" \161 -H "Authorization: Bearer $GEMINI_API_KEY" \162 -d '{163 "model": "gemini-3.8-flash",164 "reasoning_effort": "low",165 "messages": [166 {167 "role": "user",168 "content": "Explain to me how AI works"169 }170 ]171 }'172173Gemini thinking models also produce [thought summaries](https://ai.google.dev/gemini-api/docs/thinking#summaries).174You can use the [`extra_body`](https://ai.google.dev/gemini-api/docs/openai#extra-body) field to include Gemini fields175in your request.176177Note that `reasoning_effort` and `thinking_level`/`thinking_budget` overlap178functionality, so they can't be used at the same time.179180### Python181182 from openai import OpenAI183184 client = OpenAI(185 api_key="GEMINI_API_KEY",186 base_url="https://generativelanguage.googleapis.com/v1beta/openai/"187 )188189 response = client.chat.completions.create(190 model="gemini-3.8-flash",191 messages=[{"role": "user", "content": "Explain to me how AI works"}],192 extra_body={193 'extra_body': {194 "google": {195 "thinking_config": {196 "thinking_level": "low",197 "include_thoughts": True198 }199 }200 }201 }202 )203204 print(response.choices[0].message)205206### JavaScript207208 import OpenAI from "openai";209210 const openai = new OpenAI({211 apiKey: "GEMINI_API_KEY",212 baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"213 });214215 const response = await openai.chat.completions.create({216 model: "gemini-3.8-flash",217 messages: [{role: "user", content: "Explain to me how AI works",}],218 extra_body: {219 "google": {220 "thinking_config": {221 "thinking_level": "low",222 "include_thoughts": true223 }224 }225 }226 });227228 console.log(response.choices[0].message);229230### REST231232 curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \233 -H "Content-Type: application/json" \234 -H "Authorization: Bearer GEMINI_API_KEY" \235 -d '{236 "model": "gemini-3.8-flash",237 "messages": [{"role": "user", "content": "Explain to me how AI works"}],238 "extra_body": {239 "google": {240 "thinking_config": {241 "thinking_level": "low",242 "include_thoughts": true243 }244 }245 }246 }'247248Gemini 3 supports OpenAI compatibility for thought signatures in chat completion249APIs. You can find the full example on the [thought signatures](https://ai.google.dev/gemini-api/docs/thought-signatures#openai) page.250251## Streaming252253The Gemini API supports [streaming responses](https://ai.google.dev/gemini-api/docs/text-generation?lang=python#generate-a-text-stream).254255### Python256257 from openai import OpenAI258259 client = OpenAI(260 api_key="GEMINI_API_KEY",261 base_url="https://generativelanguage.googleapis.com/v1beta/openai/"262 )263264 response = client.chat.completions.create(265 model="gemini-3.8-flash",266 messages=[267 {268 "role": "system",269 "content": "You are a helpful assistant."270 },271 { "role": "user",272 "content": "Hello!"273 }274 ],275 stream=True276 )277278 for chunk in response:279 print(chunk.choices[0].delta)280281### JavaScript282283 import OpenAI from "openai";284285 const openai = new OpenAI({286 apiKey: "GEMINI_API_KEY",287 baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"288 });289290 async function main() {291 const completion = await openai.chat.completions.create({292 model: "gemini-3.8-flash",293 messages: [294 {295 "role": "system",296 "content": "You are a helpful assistant."297 },298 {299 "role": "user",300 "content": "Hello!"301 }302 ],303 stream: true,304 });305306 for await (const chunk of completion) {307 console.log(chunk.choices[0].delta.content);308 }309 }310311 main();312313### REST314315 curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \316 -H "Content-Type: application/json" \317 -H "Authorization: Bearer GEMINI_API_KEY" \318 -d '{319 "model": "gemini-3.8-flash",320 "messages": [321 {"role": "user", "content": "Explain to me how AI works"}322 ],323 "stream": true324 }'325326## Function calling327328Function calling makes it easier for you to get structured data outputs from329generative models and is [supported in the Gemini API](https://ai.google.dev/gemini-api/docs/function-calling/tutorial).330331### Python332333 from openai import OpenAI334335 client = OpenAI(336 api_key="GEMINI_API_KEY",337 base_url="https://generativelanguage.googleapis.com/v1beta/openai/"338 )339340 tools = [341 {342 "type": "function",343 "function": {344 "name": "get_weather",345 "description": "Get the weather in a given location",346 "parameters": {347 "type": "object",348 "properties": {349 "location": {350 "type": "string",351 "description": "The city and state, e.g. Chicago, IL",352 },353 "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},354 },355 "required": ["location"],356 },357 }358 }359 ]360361 messages = [{"role": "user", "content": "What's the weather like in Chicago today?"}]362 response = client.chat.completions.create(363 model="gemini-3.8-flash",364 messages=messages,365 tools=tools,366 tool_choice="auto"367 )368369 print(response)370371### JavaScript372373 import OpenAI from "openai";374375 const openai = new OpenAI({376 apiKey: "GEMINI_API_KEY",377 baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"378 });379380 async function main() {381 const messages = [{"role": "user", "content": "What's the weather like in Chicago today?"}];382 const tools = [383 {384 "type": "function",385 "function": {386 "name": "get_weather",387 "description": "Get the weather in a given location",388 "parameters": {389 "type": "object",390 "properties": {391 "location": {392 "type": "string",393 "description": "The city and state, e.g. Chicago, IL",394 },395 "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},396 },397 "required": ["location"],398 },399 }400 }401 ];402403 const response = await openai.chat.completions.create({404 model: "gemini-3.8-flash",405 messages: messages,406 tools: tools,407 tool_choice: "auto",408 });409410 console.log(response);411 }412413 main();414415### REST416417 curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \418 -H "Content-Type: application/json" \419 -H "Authorization: Bearer GEMINI_API_KEY" \420 -d '{421 "model": "gemini-3.8-flash",422 "messages": [423 {424 "role": "user",425 "content": "What'\''s the weather like in Chicago today?"426 }427 ],428 "tools": [429 {430 "type": "function",431 "function": {432 "name": "get_weather",433 "description": "Get the current weather in a given location",434 "parameters": {435 "type": "object",436 "properties": {437 "location": {438 "type": "string",439 "description": "The city and state, e.g. Chicago, IL"440 },441 "unit": {442 "type": "string",443 "enum": ["celsius", "fahrenheit"]444 }445 },446 "required": ["location"]447 }448 }449 }450 ],451 "tool_choice": "auto"452 }'453454## Image understanding455456Gemini models are natively multimodal and provide best in class performance on457[many common vision tasks](https://ai.google.dev/gemini-api/docs/vision).458459### Python460461 import base64462 from openai import OpenAI463464 client = OpenAI(465 api_key="GEMINI_API_KEY",466 base_url="https://generativelanguage.googleapis.com/v1beta/openai/"467 )468469 # Function to encode the image470 def encode_image(image_path):471 with open(image_path, "rb") as image_file:472 return base64.b64encode(image_file.read()).decode('utf-8')473474 # Getting the base64 string475 base64_image = encode_image("Path/to/agi/image.jpeg")476477 response = client.chat.completions.create(478 model="gemini-3.8-flash",479 messages=[480 {481 "role": "user",482 "content": [483 {484 "type": "text",485 "text": "What is in this image?",486 },487 {488 "type": "image_url",489 "image_url": {490 "url": f"data:image/jpeg;base64,{base64_image}"491 },492 },493 ],494 }495 ],496 )497498 print(response.choices[0])499500### JavaScript501502 import OpenAI from "openai";503 import fs from 'fs/promises';504505 const openai = new OpenAI({506 apiKey: "GEMINI_API_KEY",507 baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"508 });509510 async function encodeImage(imagePath) {511 try {512 const imageBuffer = await fs.readFile(imagePath);513 return imageBuffer.toString('base64');514 } catch (error) {515 console.error("Error encoding image:", error);516 return null;517 }518 }519520 async function main() {521 const imagePath = "Path/to/agi/image.jpeg";522 const base64Image = await encodeImage(imagePath);523524 const messages = [525 {526 "role": "user",527 "content": [528 {529 "type": "text",530 "text": "What is in this image?",531 },532 {533 "type": "image_url",534 "image_url": {535 "url": `data:image/jpeg;base64,${base64Image}`536 },537 },538 ],539 }540 ];541542 try {543 const response = await openai.chat.completions.create({544 model: "gemini-3.8-flash",545 messages: messages,546 });547548 console.log(response.choices[0]);549 } catch (error) {550 console.error("Error calling Gemini API:", error);551 }552 }553554 main();555556### REST557558 bash -c '559 base64_image=$(base64 -i "Path/to/agi/image.jpeg");560 curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \561 -H "Content-Type: application/json" \562 -H "Authorization: Bearer GEMINI_API_KEY" \563 -d "{564 \"model\": \"gemini-3.8-flash\",565 \"messages\": [566 {567 \"role\": \"user\",568 \"content\": [569 { \"type\": \"text\", \"text\": \"What is in this image?\" },570 {571 \"type\": \"image_url\",572 \"image_url\": { \"url\": \"data:image/jpeg;base64,${base64_image}\" }573 }574 ]575 }576 ]577 }"578 '579580## Generate an image581582Generate an image using `gemini-2.5-flash-image` or `gemini-3-pro-image-preview`. Supported parameters include `prompt`, `model`, `n`, `size`, and `response_format`. Any other parameters not listed here or in the [`extra_body`](https://ai.google.dev/gemini-api/docs/openai#extra-body) section will be silently ignored by the compatibility layer.583584> [!TIP]585> You can enable **Grounding with Google Search** and configure **safety settings** using the `extra_body` parameter. See the [`extra_body`](https://ai.google.dev/gemini-api/docs/openai#extra-body) section for available parameters. Grounding with Google Search is only available on Gemini 3 and newer models.586587### Python588589 import base64590 from openai import OpenAI591 from PIL import Image592 from io import BytesIO593594 client = OpenAI(595 api_key="GEMINI_API_KEY",596 base_url="https://generativelanguage.googleapis.com/v1beta/openai/",597 )598599 response = client.images.generate(600 model="gemini-2.5-flash-image",601 prompt="a portrait of a sheepadoodle wearing a cape",602 response_format='b64_json',603 n=1,604 )605606 for image_data in response.data:607 image = Image.open(BytesIO(base64.b64decode(image_data.b64_json)))608 image.show()609610### JavaScript611612 import OpenAI from "openai";613614 const openai = new OpenAI({615 apiKey: "GEMINI_API_KEY",616 baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",617 });618619 async function main() {620 const image = await openai.images.generate(621 {622 model: "gemini-2.5-flash-image",623 prompt: "a portrait of a sheepadoodle wearing a cape",624 response_format: "b64_json",625 n: 1,626 }627 );628629 console.log(image.data);630 }631632 main();633634### REST635636 curl "https://generativelanguage.googleapis.com/v1beta/openai/images/generations" \637 -H "Content-Type: application/json" \638 -H "Authorization: Bearer GEMINI_API_KEY" \639 -d '{640 "model": "gemini-2.5-flash-image",641 "prompt": "a portrait of a sheepadoodle wearing a cape",642 "response_format": "b64_json",643 "n": 1,644 }'645646## Generate a video647648Generate a video using `veo-3.1-generate-preview` via the Sora-compatible649`/v1/videos` endpoint. Supported top-level parameters are `prompt` and `model`. Additional parameters like `duration_seconds`, `image`, and `aspect_ratio` must be passed with `extra_body`. See the [`extra_body`](https://ai.google.dev/gemini-api/docs/openai#extra-body) section650for all available parameters.651652Video generation is a long-running operation that returns653an operation ID you can poll for completion.654655### Python656657 from openai import OpenAI658659 client = OpenAI(660 api_key="GEMINI_API_KEY",661 base_url="https://generativelanguage.googleapis.com/v1beta/openai/"662 )663664 # Returns a Long Running Operation (status: processing)665 response = client.videos.create(666 model="veo-3.1-generate-preview",667 prompt="A cinematic drone shot of a waterfall",668 )669670 print(f"Operation ID: {response.id}")671 print(f"Status: {response.status}")672673### JavaScript674675 import OpenAI from "openai";676677 const openai = new OpenAI({678 apiKey: "GEMINI_API_KEY",679 baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"680 });681682 async function main() {683 // Returns a Long Running Operation (status: processing)684 const response = await openai.videos.create({685 model: "veo-3.1-generate-preview",686 prompt: "A cinematic drone shot of a waterfall",687 });688689 console.log(`Operation ID: ${response.id}`);690 console.log(`Status: ${response.status}`);691 }692693 main();694695### REST696697 curl "https://generativelanguage.googleapis.com/v1beta/openai/videos" \698 -H "Authorization: Bearer $GEMINI_API_KEY" \699 -F "model=veo-3.1-generate-preview" \700 -F "prompt=A cinematic drone shot of a waterfall"701702### Check video status703704Video generation is asynchronous. Use `GET /v1/videos/{id}` to poll the status705and retrieve the final video URL when complete:706707### Python708709 import time710 from openai import OpenAI711712 client = OpenAI(713 api_key="GEMINI_API_KEY",714 base_url="https://generativelanguage.googleapis.com/v1beta/openai/"715 )716717 # Poll until video is ready718 video_id = response.id # From the create call719 while True:720 video = client.videos.retrieve(video_id)721 if video.status == "completed":722 print(f"Video URL: {video.url}")723 break724 elif video.status == "failed":725 print(f"Generation failed: {video.error}")726 break727 print(f"Status: {video.status}. Waiting...")728 time.sleep(10)729730### JavaScript731732 import OpenAI from "openai";733734 const openai = new OpenAI({735 apiKey: "GEMINI_API_KEY",736 baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"737 });738739 async function main() {740 // Poll until video is ready741 const videoId = response.id; // From the create call742 while (true) {743 const video = await openai.videos.retrieve(videoId);744 if (video.status === "completed") {745 console.log(`Video URL: ${video.url}`);746 break;747 } else if (video.status === "failed") {748 console.log(`Generation failed: ${video.error}`);749 break;750 }751 console.log(`Status: ${video.status}. Waiting...`);752 await new Promise(resolve => setTimeout(resolve, 10000));753 }754 }755756 main();757758### REST759760 curl "https://generativelanguage.googleapis.com/v1beta/openai/videos/VIDEO_ID" \761 -H "Authorization: Bearer $GEMINI_API_KEY"762763## Audio understanding764765Analyze audio input:766767### Python768769 import base64770 from openai import OpenAI771772 client = OpenAI(773 api_key="GEMINI_API_KEY",774 base_url="https://generativelanguage.googleapis.com/v1beta/openai/"775 )776777 with open("/path/to/your/audio/file.wav", "rb") as audio_file:778 base64_audio = base64.b64encode(audio_file.read()).decode('utf-8')779780 response = client.chat.completions.create(781 model="gemini-3.8-flash",782 messages=[783 {784 "role": "user",785 "content": [786 {787 "type": "text",788 "text": "Transcribe this audio",789 },790 {791 "type": "input_audio",792 "input_audio": {793 "data": base64_audio,794 "format": "wav"795 }796 }797 ],798 }799 ],800 )801802 print(response.choices[0].message.content)803804### JavaScript805806 import fs from "fs";807 import OpenAI from "openai";808809 const client = new OpenAI({810 apiKey: "GEMINI_API_KEY",811 baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",812 });813814 const audioFile = fs.readFileSync("/path/to/your/audio/file.wav");815 const base64Audio = Buffer.from(audioFile).toString("base64");816817 async function main() {818 const response = await client.chat.completions.create({819 model: "gemini-3.8-flash",820 messages: [821 {822 role: "user",823 content: [824 {825 type: "text",826 text: "Transcribe this audio",827 },828 {829 type: "input_audio",830 input_audio: {831 data: base64Audio,832 format: "wav",833 },834 },835 ],836 },837 ],838 });839840 console.log(response.choices[0].message.content);841 }842843 main();844845### REST846847> [!NOTE]848> **Note:** If you get an `Argument list too long` error, the encoding of your audio file might be too long for curl.849850 bash -c '851 base64_audio=$(base64 -i "/path/to/your/audio/file.wav");852 curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \853 -H "Content-Type: application/json" \854 -H "Authorization: Bearer GEMINI_API_KEY" \855 -d "{856 \"model\": \"gemini-3.8-flash\",857 \"messages\": [858 {859 \"role\": \"user\",860 \"content\": [861 { \"type\": \"text\", \"text\": \"Transcribe this audio file.\" },862 {863 \"type\": \"input_audio\",864 \"input_audio\": {865 \"data\": \"${base64_audio}\",866 \"format\": \"wav\"867 }868 }869 ]870 }871 ]872 }"873 '874875## Structured output876877Gemini models can output JSON objects in any [structure you define](https://ai.google.dev/gemini-api/docs/structured-output).878879### Python880881 from pydantic import BaseModel882 from openai import OpenAI883884 client = OpenAI(885 api_key="GEMINI_API_KEY",886 base_url="https://generativelanguage.googleapis.com/v1beta/openai/"887 )888889 class CalendarEvent(BaseModel):890 name: str891 date: str892 participants: list[str]893894 completion = client.beta.chat.completions.parse(895 model="gemini-3.8-flash",896 messages=[897 {"role": "system", "content": "Extract the event information."},898 {"role": "user", "content": "John and Susan are going to an AI conference on Friday."},899 ],900 response_format=CalendarEvent,901 )902903 print(completion.choices[0].message.parsed)904905### JavaScript906907 import OpenAI from "openai";908 import { zodResponseFormat } from "openai/helpers/zod";909 import { z } from "zod";910911 const openai = new OpenAI({912 apiKey: "GEMINI_API_KEY",913 baseURL: "https://generativelanguage.googleapis.com/v1beta/openai"914 });915916 const CalendarEvent = z.object({917 name: z.string(),918 date: z.string(),919 participants: z.array(z.string()),920 });921922 const completion = await openai.chat.completions.parse({923 model: "gemini-3.8-flash",924 messages: [925 { role: "system", content: "Extract the event information." },926 { role: "user", content: "John and Susan are going to an AI conference on Friday" },927 ],928 response_format: zodResponseFormat(CalendarEvent, "event"),929 });930931 const event = completion.choices[0].message.parsed;932 console.log(event);933934## Embeddings935936Text embeddings measure the relatedness of text strings and can be generated937using the [Gemini API](https://ai.google.dev/gemini-api/docs/embeddings). You can use938`gemini-embedding-2-preview` for multimodal embeddings or939`gemini-embedding-001` for text-only embeddings.940941### Python942943 from openai import OpenAI944945 client = OpenAI(946 api_key="GEMINI_API_KEY",947 base_url="https://generativelanguage.googleapis.com/v1beta/openai/"948 )949950 response = client.embeddings.create(951 input="Your text string goes here",952 model="gemini-embedding-2-preview"953 )954955 print(response.data[0].embedding)956957### JavaScript958959 import OpenAI from "openai";960961 const openai = new OpenAI({962 apiKey: "GEMINI_API_KEY",963 baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"964 });965966 async function main() {967 const embedding = await openai.embeddings.create({968 model: "gemini-embedding-2-preview",969 input: "Your text string goes here",970 });971972 console.log(embedding);973 }974975 main();976977### REST978979 curl "https://generativelanguage.googleapis.com/v1beta/openai/embeddings" \980 -H "Content-Type: application/json" \981 -H "Authorization: Bearer GEMINI_API_KEY" \982 -d '{983 "input": "Your text string goes here",984 "model": "gemini-embedding-2-preview"985 }'986987## Batch API988989You can create [batch jobs](https://ai.google.dev/gemini-api/docs/batch-mode), submit them, and check990their status using the OpenAI library.991992You'll need to prepare the JSONL file in OpenAI input format. For example:993994 {"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gemini-3.8-flash", "messages": [{"role": "user", "content": "Tell me a one-sentence joke."}]}}995 {"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gemini-3.8-flash", "messages": [{"role": "user", "content": "Why is the sky blue?"}]}}996997OpenAI compatibility for Batch supports creating a batch,998monitoring job status, and viewing batch results.9991000Compatibility for upload and download is currently not supported. Instead, the1001following example uses the `genai` client for uploading and downloading1002[files](https://ai.google.dev/gemini-api/docs/files), the same as when using the Gemini [Batch API](https://ai.google.dev/gemini-api/docs/batch-mode#input-file).10031004### Python10051006 from openai import OpenAI10071008 # Regular genai client for uploads & downloads1009 from google import genai1010 client = genai.Client()10111012 openai_client = OpenAI(1013 api_key="GEMINI_API_KEY",1014 base_url="https://generativelanguage.googleapis.com/v1beta/openai/"1015 )10161017 # Upload the JSONL file in OpenAI input format, using regular genai SDK1018 uploaded_file = client.files.upload(1019 file='my-batch-requests.jsonl',1020 config=types.UploadFileConfig(display_name='my-batch-requests', mime_type='jsonl')1021 )10221023 # Create batch1024 batch = openai_client.batches.create(1025 input_file_id=batch_input_file_id,1026 endpoint="/v1/chat/completions",1027 completion_window="24h"1028 )10291030 # Wait for batch to finish (up to 24h)1031 while True:1032 batch = client.batches.retrieve(batch.id)1033 if batch.status in ('completed', 'failed', 'cancelled', 'expired'):1034 break1035 print(f"Batch not finished. Current state: {batch.status}. Waiting 30 seconds...")1036 time.sleep(30)1037 print(f"Batch finished: {batch}")10381039 # Download results in OpenAI output format, using regular genai SDK1040 file_content = genai_client.files.download(file=batch.output_file_id).decode('utf-8')10411042 # See batch_output JSONL in OpenAI output format1043 for line in file_content.splitlines():1044 print(line) 10451046The OpenAI SDK also supports [generating embeddings with the Batch API](https://ai.google.dev/gemini-api/docs/batch-api#batch-embeddings). To do so, switch out the1047`create` method's `endpoint` field for an embeddings endpoint, as well as the1048`url` and `model` keys in the JSONL file:10491050 # JSONL file using embeddings model and endpoint1051 # {"custom_id": "request-1", "method": "POST", "url": "/v1/embeddings", "body": {"model": "ggemini-embedding-001", "messages": [{"role": "user", "content": "Tell me a one-sentence joke."}]}}1052 # {"custom_id": "request-2", "method": "POST", "url": "/v1/embeddings", "body": {"model": "gemini-embedding-001", "messages": [{"role": "user", "content": "Why is the sky blue?"}]}}10531054 # ...10551056 # Create batch step with embeddings endpoint1057 batch = openai_client.batches.create(1058 input_file_id=batch_input_file_id,1059 endpoint="/v1/embeddings",1060 completion_window="24h"1061 )10621063See the [Batch embedding generation](https://github.com/google-gemini/cookbook/blob/main/quickstarts/Get_started_OpenAI_Compatibility.ipynb)1064section of the OpenAI compatibility cookbook for a complete example.10651066## Flex and Priority inference10671068The Gemini API matches OpenAI's `service_tier` parameter in name and logic,1069enforcing limits and gracefully directing traffic for both the Flex and Priority1070inference tiers.10711072### Python10731074 from openai import OpenAI10751076 client = OpenAI(1077 api_key="GEMINI_API_KEY",1078 base_url="https://generativelanguage.googleapis.com/v1beta/openai/"1079 )10801081 completion = client.chat.completions.create(1082 model="gemini-3.8-flash",1083 messages=[1084 {"role": "user", "content": "Write a short poem about clouds."}1085 ],1086 service_tier="priority" # Or service_tier="flex"1087 )10881089 print(completion)10901091When not explicitly assigned, `service_tier` defaults to `standard`, equivalent1092to `default` for OpenAI.1093Learn more about inference tiers in the [Optimization](https://ai.google.dev/gemini-api/docs/optimization) documentation.10941095## Enable Gemini features with `extra_body`10961097There are several features supported by Gemini that are not available in OpenAI1098models but can be enabled using the `extra_body` field.10991100| Parameter | Type | Endpoint | Description |1101|---|---|---|---|1102| **`cached_content`** | Text | Chat | Corresponds to Gemini's general content cache. |1103| **`thinking_config`** | Object | Chat | Corresponds to Gemini's ThinkingConfig. |1104| **`aspect_ratio`** | Text | Images | Output aspect ratio (e.g., `"16:9"`, `"1:1"`, `"9:16"`). |1105| **`generation_config`** | Object | Images | Gemini generation config object (e.g., `{"responseModalities": ["IMAGE"], "candidateCount": 2}`). |1106| **`safety_settings`** | List | Images | Custom safety threshold filters (e.g., `[{"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE"}]`). |1107| **`tools`** | List | Images | Enables grounding (e.g., `[{"google_search": {}}]`). Only for `gemini-3-pro-image-preview`. |1108| **`aspect_ratio`** | Text | Video | Dimensions of the output video (`16:9` for landscape, `9:16` for portrait). Maps from `size` if not specified. |1109| **`resolution`** | Text | Video | Output resolution (`720p`, `1080p`, `4K`). Note: `1080p` and `4K` trigger upsampler pipeline. |1110| **`duration_seconds`** | Integer | Video | Generation length (values: `4`, `6`, `8`). Must be `8` when using `reference_images`, interpolation, or extension. |1111| **`frame_rate`** | Text | Video | Frame rate for video output (e.g., `"24"`). |1112| **`input_reference`** | Text | Video | Reference input for video generation. |1113| **`extend_video_id`** | Text | Video | ID of an existing video to extend. |1114| **`negative_prompt`** | Text | Video | Items to exclude (e.g., `"shaky camera"`). |1115| **`seed`** | Integer | Video | Integer for deterministic generation. |1116| **`style`** | Text | Video | Visual styling (`cinematic` default, `creative` for social-media optimized). |1117| **`person_generation`** | Text | Video | Controls generation of people (`allow_adult`, `allow_all`, `dont_allow`). |1118| **`reference_images`** | List | Video | Up to 3 images for style/character reference (base64 assets). |1119| **`image`** | Text | Video | Base64-encoded initial input image to condition the video generation. |1120| **`last_frame`** | Object | Video | Final image for interpolation (requires `image` as first frame). |11211122### Example using `extra_body`11231124Here's an example of using `extra_body` to set `cached_content`:11251126### Python11271128 from openai import OpenAI11291130 client = OpenAI(1131 api_key=MY_API_KEY,1132 base_url="https://generativelanguage.googleapis.com/v1beta/"1133 )11341135 stream = client.chat.completions.create(1136 model="gemini-3.8-flash",1137 n=1,1138 messages=[1139 {1140 "role": "user",1141 "content": "Summarize the video"1142 }1143 ],1144 stream=True,1145 stream_options={'include_usage': True},1146 extra_body={1147 'extra_body':1148 {1149 'google': {1150 'cached_content': "cachedContents/0000aaaa1111bbbb2222cccc3333dddd4444eeee"1151 }1152 }1153 }1154 )11551156 for chunk in stream:1157 print(chunk)1158 print(chunk.usage.to_dict())11591160## List models11611162Get a list of available Gemini models:11631164### Python11651166 from openai import OpenAI11671168 client = OpenAI(1169 api_key="GEMINI_API_KEY",1170 base_url="https://generativelanguage.googleapis.com/v1beta/openai/"1171 )11721173 models = client.models.list()1174 for model in models:1175 print(model.id)11761177### JavaScript11781179 import OpenAI from "openai";11801181 const openai = new OpenAI({1182 apiKey: "GEMINI_API_KEY",1183 baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",1184 });11851186 async function main() {1187 const list = await openai.models.list();11881189 for await (const model of list) {1190 console.log(model);1191 }1192 }1193 main();11941195### REST11961197 curl https://generativelanguage.googleapis.com/v1beta/openai/models \1198 -H "Authorization: Bearer GEMINI_API_KEY"11991200## Retrieve a model12011202Retrieve a Gemini model:12031204### Python12051206 from openai import OpenAI12071208 client = OpenAI(1209 api_key="GEMINI_API_KEY",1210 base_url="https://generativelanguage.googleapis.com/v1beta/openai/"1211 )12121213 model = client.models.retrieve("gemini-3.8-flash")1214 print(model.id)12151216### JavaScript12171218 import OpenAI from "openai";12191220 const openai = new OpenAI({1221 apiKey: "GEMINI_API_KEY",1222 baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",1223 });12241225 async function main() {1226 const model = await openai.models.retrieve("gemini-3.8-flash");1227 console.log(model.id);1228 }12291230 main();12311232### REST12331234 curl https://generativelanguage.googleapis.com/v1beta/openai/models/gemini-3.8-flash \1235 -H "Authorization: Bearer GEMINI_API_KEY"12361237## Current limitations12381239Support for the OpenAI libraries is still in beta while we extend feature support.12401241If you have questions about supported parameters, upcoming features, or run into1242any issues getting started with Gemini, join our [Developer Forum](https://discuss.ai.google.dev/c/gemini-api/4).12431244## What's next12451246Try our [OpenAI Compatibility Colab](https://colab.sandbox.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Get_started_OpenAI_Compatibility.ipynb) to work through more detailed1247examples.