> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Gemini Guides
> A comprehensive guide to Gemini API calls on our platform.
## Forwarding for Gemini Models
For the Gemini series, we provide **two** invocation methods: native API calls and OpenAI-compatible calls.\
Before you start, make sure to install or update the native dependency by running either `pip install google-genai` or `pip install -U google-genai`.
1️⃣ For native integration, Gemini takes care of routing traffic between AI Studio and VertexAI automatically. Just supply your **AIHubMix API key** and the appropriate **request URL**. Remember, this URL is different from the usual `base_url`—follow the example below to ensure proper setup.
```python theme={null}
client = genai.Client(
api_key="sk-***", # Replace with the key you generated from AiHubMix
http_options={"base_url": "https://aihubmix.com/gemini"},
)
```
2️⃣ For OpenAI-compatible formats, retain the universal `v1` endpoint.
```py theme={null}
client = OpenAI(
api_key="sk-***", # Replace with the key you generated from AiHubMix
base_url="https://aihubmix.com/v1",
)
```
3️⃣ For the 2.5 series, if you need to display the reasoning process, there are two ways to do it:
1. **Native invocation:** Pass `include_thoughts=True`
2. **OpenAI-compatible method:** Pass `reasoning_effort`
You can refer to the code examples below for detailed usage.
## **Gemini 3 Pro** Image Preview Instructions
Gemini 3 Pro Image Preview (Nano Banana Pro Preview) is designed for professional asset creation and complex instructions. This model offers the following features:
* Uses Google Search to retrieve real-time world knowledge
* Built-in “thinking” process (optimizes composition before generation)
* Can generate images with resolutions up to **4K**
Streaming Mode (`stream=True`)
→ reasoning stage only\
Non-Streaming Mode (`stream=False`)
→ final image generation
Generated images are not included in streaming responses
and must be retrieved using a non-streaming request
.
**Python usage examples:**
```python Text-to-Image theme={null}
import os
from google import genai
from google.genai import types
API_KEY = ""
client = genai.Client(
api_key=API_KEY,
http_options={"base_url": "https://aihubmix.com/gemini"},
)
prompt = (
"Da Vinci style anatomical sketch of a dissected Monarch butterfly. "
"Detailed drawings of the head, wings, and legs on textured parchment with notes in English."
)
# Optional parameters
aspect_ratio = "1:1" # Supported: "1:1","2:3","3:2","3:4","4:3","4:5","5:4","9:16","16:9","21:9"
resolution = "4K" # Default: 1K. Supported: "1K", "2K", "4K". Note: “K” must be uppercase.
response = client.models.generate_content(
model="gemini-3-pro-image-preview",
contents=prompt,
config=types.GenerateContentConfig(
response_modalities=['TEXT', 'IMAGE'],
image_config=types.ImageConfig(
aspect_ratio=aspect_ratio,
image_size=resolution,
),
),
)
# Save image & print text
for part in response.parts:
if part.text:
print(part.text)
elif image := part.as_image():
image.save("butterfly.png")
print("Image saved: butterfly.png")
```
```python Image-to-Image theme={null}
from google import genai
from PIL import Image
API_KEY = ""
client = genai.Client(
api_key=API_KEY,
http_options={"base_url": "https://aihubmix.com/gemini"}
)
prompt = (
"Create a picture of my cat eating a nano-banana "
"in a fancy restaurant under the Gemini constellation."
)
image = Image.open("cat_image.jpg")
response = client.models.generate_content(
model="gemini-2.5-flash-image",
contents=[prompt, image],
)
# Save image & print text
for part in response.parts:
if part.text is not None:
print(part.text)
elif part.inline_data is not None:
image = part.as_image()
image.save("generated_image.png")
```
```python Multiple Imag theme={null}
from google import genai
from google.genai import types
from PIL import Image
API_KEY = ""
prompt = "An office group photo of these people, they are making funny faces."
aspect_ratio = "5:4"
resolution = "2K"
client = genai.Client(
api_key=API_KEY,
http_options={"base_url": "https://aihubmix.com/gemini"}
)
response = client.models.generate_content(
model="gemini-3-pro-image-preview",
contents=[
prompt,
Image.open('person1.png'),
Image.open('person2.png'),
Image.open('person3.png'),
Image.open('person4.png'),
Image.open('person5.png'),
],
config=types.GenerateContentConfig(
response_modalities=['TEXT', 'IMAGE'],
image_config=types.ImageConfig(
aspect_ratio=aspect_ratio,
image_size=resolution,
),
)
)
# Save image & print text
for part in response.parts:
if part.text is not None:
print(part.text)
elif image := part.as_image():
image.save("office.png")
```
```python Google Search theme={null}
from google import genai
from google.genai import types
API_KEY = ""
prompt = (
"Visualize the current weather forecast for the next 5 days in Shanghai "
"as a clean, modern weather chart. Add a visual showing what I should wear each day."
) # Display Shanghai’s five-day weather in a chart format
aspect_ratio = "16:9"
client = genai.Client(
api_key=API_KEY,
http_options={"base_url": "https://aihubmix.com/gemini"}
)
response = client.models.generate_content(
model="gemini-3-pro-image-preview",
contents=prompt,
config=types.GenerateContentConfig(
response_modalities=['TEXT', 'IMAGE'],
image_config=types.ImageConfig(
aspect_ratio=aspect_ratio,
),
tools=[{"google_search": {}}]
)
)
# Save image & print text
for part in response.parts:
if part.text is not None:
print(part.text)
elif image := part.as_image():
image.save("weather.png")
```
## About Gemini 2.5 Inference Models
1. The entire 2.5 series consists of **inference models**.
2. **2.5 Flash** is a hybrid model, similar to Claude Sonnet 3.7. You can fine-tune its reasoning behavior by adjusting the `thinking_budget` parameter for optimal control.
3. **2.5 Pro** is a pure inference model. Thinking cannot be disabled, and `thinking_budget` should not be explicitly set.
**Python usage examples:**
```py StreamFalse theme={null}
from google import genai
from google.genai import types
def generate():
client = genai.Client(
api_key="sk-***", # 🔑 Replace it by your AiHubMix Key
http_options={"base_url": "https://aihubmix.com/gemini"},
)
model = "gemini-2.0-flash"
contents = [
types.Content(
role="user",
parts=[
types.Part.from_text(text="""How do I know I'm not wasting time?"""),
],
),
]
print(client.models.generate_content(
model=model,
contents=contents,
))
if __name__ == "__main__":
generate()
```
```py 2.0 Series-Stream theme={null}
from google import genai
from google.genai import types
def generate():
client = genai.Client(
api_key="sk-***", # 🔑 Replace it by your AiHubMix Key
http_options={"base_url": "https://aihubmix.com/gemini"},
)
model = "gemini-2.0-flash"
contents = [
types.Content(
role="user",
parts=[
types.Part.from_text(text="""How do I know I'm not wasting time?"""),
],
),
]
generate_content_config = types.GenerateContentConfig(
response_mime_type="text/plain",
)
for chunk in client.models.generate_content_stream(
model=model,
contents=contents,
config=generate_content_config,
):
print(chunk.text, end="")
if __name__ == "__main__":
generate()
```
```py 2.5 Flash-Stream theme={null}
from google import genai
from google.genai import types
def generate():
client = genai.Client(
api_key="sk-***", # 🔑 Replace it by your AiHubMix Key
http_options={"base_url": "https://aihubmix.com/gemini"},
)
model = "gemini-2.5-flash-preview-04-17" #gemini-2.5-pro-preview-03-25、gemini-2.5-flash-preview-04-17
contents = [
types.Content(
role="user",
parts=[
types.Part.from_text(text="""How do I know I'm not wasting time?"""),
],
),
]
generate_content_config = types.GenerateContentConfig(
thinking_config = types.ThinkingConfig(
thinking_budget=2048, #range: 0-16K。1024 as default，16000 for best performance
),
response_mime_type="text/plain",
)
for chunk in client.models.generate_content_stream(
model=model,
contents=contents,
config=generate_content_config,
):
print(chunk.text, end="")
if __name__ == "__main__":
generate()
```
```py 2.5 Pro-Stream theme={null}
from google import genai
from google.genai import types
def generate():
client = genai.Client(
api_key="sk-***", # 🔑 Replace it by your AiHubMix Key
http_options={"base_url": "https://aihubmix.com/gemini"},
)
model = "gemini-2.5-pro-preview-03-25"
contents = [
types.Content(
role="user",
parts=[
types.Part.from_text(text="""How do I know I'm not wasting time?"""),
],
),
]
generate_content_config = types.GenerateContentConfig(
response_mime_type="text/plain",
)
for chunk in client.models.generate_content_stream(
model=model,
contents=contents,
config=generate_content_config,
):
print(chunk.text, end="")
if __name__ == "__main__":
generate()
```
```py 2.5 Show Thinking theme={null}
from google import genai
from google.genai import types
def generate():
client = genai.Client(
api_key="sk-***", # 🔑 Replace it by your AiHubMix Key
http_options={"base_url": "https://aihubmix.com/gemini"},
)
model = "gemini-2.5-pro-preview-05-06"
contents = [
types.Content(
role="user",
parts=[
types.Part.from_text(text="""How is the "Rule of 72" in finance derived?"""),
],
),
]
generate_content_config = types.GenerateContentConfig(
response_mime_type="text/plain",
thinking_config=types.ThinkingConfig(
include_thoughts=True # Show Thinking Content
),
)
final_usage_metadata = None
for chunk in client.models.generate_content_stream(
model=model,
contents=contents,
config=generate_content_config,
):
if chunk.candidates and len(chunk.candidates) > 0:
for part in chunk.candidates[0].content.parts:
if part.text:
if part.thought:
print(part.text, end="")
else:
print(part.text, end="")
if chunk.usage_metadata:
final_usage_metadata = chunk.usage_metadata
if final_usage_metadata:
print(f"\n\n📊 Token Usage:")
print(f"Thinking tokens: {getattr(final_usage_metadata, 'thoughts_token_count', '不可用')}")
print(f"Output tokens: {getattr(final_usage_metadata, 'candidates_token_count', '不可用')}")
print(f"Total: {final_usage_metadata}")
if __name__ == "__main__":
generate()
```
## Gemini 2.5 Flash: Quick Task Support
Example for OpenAI-compatible invocation:
```py Python Disable thinking for rapid task theme={null}
from openai import OpenAI
client = OpenAI(
api_key="AIHUBMIX_API_KEY", # Replace with the key you generated in AiHubMix
base_url="https://aihubmix.com/v1",
)
completion = client.chat.completions.create(
model="gemini-2.5-flash-preview-04-17-nothink",
messages=[
{
"role": "user",
"content": "Explain the Occam's Razor concept and provide everyday examples of it"
}
]
)
print(completion.choices[0].message.content)
```
```py Python Reasoning Effort theme={null}
from openai import OpenAI
client = OpenAI(
api_key="sk-***", # Replace with the key you generated in AiHubMix
base_url="https://aihubmix.com/v1",
)
completion = client.chat.completions.create(
model="gemini-2.5-flash-preview-04-17",
reasoning_effort="low", #"low", "medium", and "high", map to 1K, 8K, and 16K thinking token budgets
messages=[
{
"role": "user",
"content": "Explain the Occam's Razor concept and provide everyday examples of it"
}
]
)
print(completion.choices[0].message.content)
```
```shell Curl-Basic theme={null}
curl -X POST https://aihubmix.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-***" \
-d '{
"model": "gemini-2.5-flash-preview-04-17-nothink",
"messages": [
{
"role": "user",
"content": "Explain the Occam'\''s Razor concept and provide an everyday example of it."
}
]
}'
```
```shell Curl-Show Thinking theme={null}
curl https://aihubmix.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-***" \
-d '{
"model": "gemini-2.5-pro-preview-05-06",
"messages": [
{
"role": "user",
"content": "Explain the Occam'\''s Razor concept and provide an everyday example of it."
}
],
"reasoning_effort": "low"
}'
```
1. For complex tasks, simply set the model id to the default `gemini-2.5-flash-preview-04-17` to enable thinking.
2. Gemini 2.5 Flash uses the `budget` parameter to control the depth of thinking, ranging from 0 to 16K. The default budget is 1024, and the optimal marginal effect is 16K.
## Media Understanding
* For multimedia files **under 20MB** (images, audio, video), upload them using `inline_data`.
* When a multimedia file is **larger than 20MB**, you must use the Files API.
### Files Under 20MB
By adding the `EDIARESOLUTION_MEDIUM` parameter, you can adjust the image resolution, which significantly reduces input costs and minimizes the risk of errors with large images.
**Supported media resolution values:**
| Name | Description |
| ------------------------------ | ---------------------------------------------------------------- |
| MEDIA\_RESOLUTION\_UNSPECIFIED | Media resolution has not been set. |
| MEDIA\_RESOLUTION\_LOW | Media resolution set to low (64 tokens). |
| MEDIA\_RESOLUTION\_MEDIUM | Media resolution set to medium (256 tokens). |
| MEDIA\_RESOLUTION\_HIGH | Media resolution set to high (zoomed reframing with 256 tokens). |
**Python usage examples:**
```python Image theme={null}
from google import genai
from google.genai import types
file_path = "yourpath/file.jpeg"
with open(file_path, "rb") as f:
file_bytes = f.read()
client = genai.Client(
api_key="sk-***", # Replace with the key you generated in AiHubMix
http_options={"base_url": "https://aihubmix.com/gemini"}
)
response = client.models.generate_content(
model="gemini-2.5-flash",
contents=types.Content(
parts=[
types.Part(
inline_data=types.Blob(
data=file_bytes,
mime_type="image/jpeg"
)
),
types.Part(
text="Describe the image."
)
]
),
config=types.GenerateContentConfig(
system_instruction="You are a helpful assistant that can describe images.",
max_output_tokens=768,
temperature=0.1,
thinking_config=types.ThinkingConfig(
thinking_budget=0, include_thoughts=False
),
media_resolution=types.MediaResolution.MEDIA_RESOLUTION_MEDIUM # 256 tokens
)
)
print(response.text)
```
```python Audio theme={null}
from google import genai
from google.genai import types
file_path = "yourpath/file.m4a"
with open(file_path, "rb") as f:
file_bytes = f.read()
client = genai.Client(
api_key="sk-***", # Replace with the key you generated in AiHubMix
http_options={"base_url": "https://aihubmix.com/gemini"}
)
response = client.models.generate_content(
model="gemini-2.0-flash",
contents=types.Content(
parts=[
types.Part(
inline_data=types.Blob(
data=file_bytes,
mime_type="audio/m4a"
)
),
types.Part(
text="Transcribe the audio to text."
)
]
)
)
print(response.text)
```
```python Video theme={null}
from google import genai
from google.genai import types
file_path = "yourpath/file.mp4"
with open(file_path, "rb") as f:
file_bytes = f.read()
client = genai.Client(
api_key="sk-***", # Replace with the key you generated in AiHubMix
http_options={"base_url": "https://aihubmix.com/gemini"}
)
response = client.models.generate_content(
model="gemini-2.0-flash",
contents=types.Content(
parts=[
types.Part(
inline_data=types.Blob(
data=file_bytes,
mime_type="video/mp4"
)
),
types.Part(
text="Summarize this video. Then create a quiz with an answer key based on the information in this video."
)
]
)
)
print(response.text)
```
```python Youtube URL theme={null}
from google import genai
from google.genai import types
client = genai.Client(
api_key="sk-***", # Replace with the key you generated in AiHubMix
http_options={"base_url": "https://aihubmix.com/gemini"}
)
response = client.models.generate_content(
model="gemini-2.0-flash",
contents=types.Content(
parts=[
types.Part(
file_data=types.FileData(
file_uri="https://www.youtube.com/watch?v=OoU7PwNyYUw"
)
),
types.Part(
text="Please summarize the video in 3 sentences."
)
]
)
)
print(response.text)
```
### Files API
Gemini can handle various types of input data simultaneously, including text, images, and audio. When the total request size (including files, text hints, system commands, etc.) exceeds **20 MB**, be sure to use the Files API.
* Listing uploaded files is not supported.
* Files will be automatically deleted after 48 hours, or you can manually delete uploaded files.
**Python usage examples:**
```python Upload a file theme={null}
from google import genai
client = genai.Client(
api_key="sk-****",
http_options={"base_url": "https://aihubmix.com/gemini"},
)
myfile = client.files.upload(file="path/to/sample.mp3")
response = client.models.generate_content(
model="gemini-2.5-flash", contents=["Describe this audio clip", myfile]
)
print(response.text)
```
```python Get metadata for a file theme={null}
from google import genai
client = genai.Client(
api_key="sk-****",
http_options={"base_url": "https://aihubmix.com/gemini"},
)
myfile = client.files.upload(file='path/to/sample.mp3')
file_name = myfile.name
myfile = client.files.get(name=file_name)
print(myfile)
```
```python Delete uploaded files theme={null}
from google import genai
client = genai.Client()
myfile = client.files.upload(file='path/to/sample.mp3')
client.files.delete(name=myfile.name)
```
## Code Execution
The code execution feature enables the model to generate and run Python code and learn iteratively from the results until it arrives at a final output. You can use this code execution capability to build applications that benefit from code-based reasoning and that produce text output. For example, you could use code execution in an application that solves equations or processes text.
```py Python theme={null}
from google import genai
from google.genai import types
file_path = "yourpath/file.csv"
with open(file_path, "rb") as f:
file_bytes = f.read()
client = genai.Client(
api_key="sk-***", # Replace with the key you generated in AiHubMix
http_options={"base_url": "https://aihubmix.com/gemini"}
)
response = client.models.generate_content(
model="gemini-2.0-flash",
contents=types.Content(
parts=[
types.Part(
inline_data=types.Blob(
data=file_bytes,
mime_type="text/csv"
)
),
types.Part(
text="Please analyze this CSV and summarize the key statistics. Use code execution if needed."
)
]
),
config=types.GenerateContentConfig(
tools=[types.Tool(
code_execution=types.ToolCodeExecution
)]
)
)
for part in response.candidates[0].content.parts:
if part.text is not None:
print(part.text)
if getattr(part, "executable_code", None) is not None:
print("Generated code:\n", part.executable_code.code)
if getattr(part, "code_execution_result", None) is not None:
print("Execution result:\n", part.code_execution_result.output)
```
## Interactions API
Interactions is Gemini's next-generation inference interface that returns structured `Interaction` objects, supporting text generation, native image generation (Nano Banana), and multi-step reasoning. **Synchronous mode** (`interactions.create()`) is currently supported; asynchronous mode (Background Interactions) is coming soon.
SDK version requirement: `@google/genai` **>= 2.0.0** (JS/TS) or `google-genai` **>= 2.0.0** (Python). Older SDK versions calling Interactions will be rejected by Google's backend (`legacy Interactions schema no longer supported`).
### Text Generation
Call `interactions.create()` to initiate inference. The returned `Interaction` object provides an `output_text` convenience property.
```js JavaScript theme={null}
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({
apiKey: "sk-***", // Replace with your AIHubMix API Key
httpOptions: { baseUrl: "https://aihubmix.com/gemini" },
});
const interaction = await ai.interactions.create({
model: "gemini-3.5-flash",
input: "Explain quantum computing in one sentence",
});
console.log(interaction.output_text);
console.log(interaction.usage);
// { total_tokens, total_input_tokens, total_output_tokens, ... }
```
```py Python theme={null}
from google import genai
client = genai.Client(
api_key="sk-***", # Replace with your AIHubMix API Key
http_options={"base_url": "https://aihubmix.com/gemini"},
)
interaction = client.interactions.create(
model="gemini-3.5-flash",
input="Explain quantum computing in one sentence",
)
print(interaction.output_text)
```
### Native Image Generation
Configure the output modality to image via `response_format`. The returned `Interaction` object provides an `output_image` convenience property.
* Recommended model: `gemini-3.1-flash-image` (Nano Banana 2, general-purpose image generation model).
* `response_modalities` values must be **lowercase** `['text', 'image']`; uppercase is the `generateContent` API convention and will return `400` in the Interactions API.
* Do not pass `delivery: 'inline'` (`400 Image delivery mode is not supported`) — results are returned inline by default.
```js JavaScript theme={null}
import { GoogleGenAI } from "@google/genai";
import fs from "node:fs";
const ai = new GoogleGenAI({
apiKey: "sk-***", // Replace with your AIHubMix API Key
httpOptions: { baseUrl: "https://aihubmix.com/gemini" },
});
const interaction = await ai.interactions.create({
model: "gemini-3.1-flash-image",
input: "A translucent banana-shaped glass lamp on a white desk, soft studio lighting.",
response_modalities: ["text", "image"],
response_format: { type: "image", aspect_ratio: "1:1", image_size: "1K" },
});
// output_image convenience property (gets the last generated image)
if (interaction.output_image?.data) {
fs.writeFileSync("output.png", Buffer.from(interaction.output_image.data, "base64"));
}
```
```py Python theme={null}
import base64
from google import genai
client = genai.Client(
api_key="sk-***", # Replace with your AIHubMix API Key
http_options={"base_url": "https://aihubmix.com/gemini"},
)
interaction = client.interactions.create(
model="gemini-3.1-flash-image",
input="A translucent banana-shaped glass lamp on a white desk, soft studio lighting.",
response_format={
"type": "image",
"aspect_ratio": "1:1",
"image_size": "1K",
},
)
if interaction.output_image:
with open("output.png", "wb") as f:
f.write(base64.b64decode(interaction.output_image.data))
```
### Streaming
Pass `stream: true` to enable SSE streaming. Incremental text is obtained via `event.delta.text`.
```js JavaScript theme={null}
const stream = await ai.interactions.create({
model: "gemini-3.5-flash",
input: "Write a haiku about the moon",
stream: true,
});
for await (const event of stream) {
if (event.event_type === "step.delta" && event.delta?.type === "text") {
process.stdout.write(event.delta.text);
}
if (event.event_type === "interaction.completed") {
console.log("\nUsage:", JSON.stringify(event.interaction?.usage));
}
}
```
> For the full SDK integration guide (including Embeddings, explicit caching CRUD, capabilities matrix, and more), see [Gemini Native SDK Integration](/en/api/Gemini-SDK).
## Context caching
Gemini's native API **enables implicit context caching by default**—no setup required. For every `generate_content` request, the system automatically caches the input content. If a subsequent request uses the exact same content, model, and parameters, the system will instantly return the previous result, dramatically speeding up response time and potentially reducing input token costs.
* **Caching is automatic—no manual configuration needed.**
* The cache is only hit when the content, model, and all parameters are exactly the same; any difference will result in a cache miss.
* The cache time-to-live (TTL) can be set by the developer, or left unset (defaults to 1 hour). There is no minimum or maximum TTL enforced by Google. Costs depend on the number of cached tokens and the cache duration.
* While Google places no restriction on TTL, as a forwarding platform, **we only support a limited TTL range**. For requirements beyond our platform’s limits, please contact us.
### Notes
* **No guaranteed cost savings:** Cache tokens are billed at 25% of the standard input price—so theoretically, caching can save you up to 75% of input token costs. However, [Google’s official docs](https://ai.google.dev/gemini-api/docs/caching?lang=python) make no guarantee of cost savings; the real-world effect depends on your cache hit rate, token types, and storage duration.
* **Cache hit conditions:** To maximize cache effectiveness, place repeatable context at the start of your input and dynamic content (like user input) at the end.
* **How to detect cache hits:** If a response comes from the cache, `response.usage_metadata` will include the `cache_tokens_details` field and `cached_content_token_count`. You can use these to determine cache usage.\
Example fields when a cache hit occurs:
```
cache_tokens_details=[ModalityTokenCount(modality=, token_count=2003)]
cached_content_token_count=2003
```
**Code example:**
```python theme={null}
from google import genai
client = genai.Client(
http_options={"base_url": "https://aihubmix.com/gemini"},
api_key="sk-***", # Replace with your AiHubMix API key
)
prompt = """
"""
def generate_content_sync():
response = client.models.generate_content(
model="gemini-2.5-flash-preview-05-20",
contents=prompt + "Analyze the major themes in 'Pride and Prejudice'.",
)
print(response.usage_metadata) # When cache is hit, cache_tokens_details and cached_content_token_count will appear
return response
generate_content_sync()
```
> When a cache hit occurs, `response.usage_metadata` will contain:
>
> ```
> cache_tokens_details=[ModalityTokenCount(modality=, token_count=2003)]
> cached_content_token_count=2003
> ```
**Core conclusion:** Implicit caching is automatic and provides clear cache hit feedback. Developers can check usage\_metadata for cache status. **Cost savings are not guaranteed**—actual benefit depends on request structure and cache hit rates.
## Function calling
By using the openai compatible way to call Gemini's function calling, you need to pass in `tool_choice="auto"` in the request body, otherwise it will report an error.
```py Python theme={null}
from openai import OpenAI
# Define the function declaration for the model
schedule_meeting_function = {
"name": "schedule_meeting",
"description": "Schedules a meeting with specified attendees at a given time and date.",
"parameters": {
"type": "object",
"properties": {
"attendees": {
"type": "array",
"items": {"type": "string"},
"description": "List of people attending the meeting.",
},
"date": {
"type": "string",
"description": "Date of the meeting (e.g., '2024-07-29')",
},
"time": {
"type": "string",
"description": "Time of the meeting (e.g., '15:00')",
},
"topic": {
"type": "string",
"description": "The subject or topic of the meeting.",
},
},
"required": ["attendees", "date", "time", "topic"],
},
}
# Configure the client
client = OpenAI(
api_key="AIHUBMIX_API_KEY", # Replace with the key you generated in AiHubMix
base_url="https://aihubmix.com/v1",
)
# Send request with function declarations using OpenAI compatible format
response = client.chat.completions.create(
model="gemini-2.0-flash",
messages=[
{"role": "user", "content": "Schedule a meeting with Bob and Alice for 03/14/2025 at 10:00 AM about the Q3 planning."}
],
tools=[{"type": "function", "function": schedule_meeting_function}],
tool_choice="auto" ## 📍 Added Aihubmix compatibility, more stable request method
)
# Check for a function call
if response.choices[0].message.tool_calls:
tool_call = response.choices[0].message.tool_calls[0]
function_call = tool_call.function
print(f"Function to call: {function_call.name}")
print(f"Arguments: {function_call.arguments}")
print(response.usage)
# In a real app, you would call your function here:
# result = schedule_meeting(**json.loads(function_call.arguments))
else:
print("No function call found in the response.")
print(response.choices[0].message.content)
```
**Output Example:**
```bash theme={null}
Function to call: schedule_meeting
Arguments: {"attendees":["Bob","Alice"],"date":"2025-03-14","time":"10:00","topic":"Q3 planning"}
CompletionUsage(completion_tokens=28, prompt_tokens=111, total_tokens=139, completion_tokens_details=None, prompt_tokens_details=None)
```
## Token Usage Tracking Made Simple
1. **Gemini** tracks token usage using `usage_metadata`. Here’s what each field means:
* `prompt_token_count`: number of input tokens
* `candidates_token_count`: number of output tokens
* `thoughts_token_count`: tokens used during reasoning (also counted as output)
* `total_token_count`: total tokens used (input + output)
For more details, check out their [official docs](https://ai.google.dev/gemini-api/docs/tokens?lang=python).
2. For APIs using the **OpenAI-compatible format**, token usage is tracked under `.usage` with the following fields:
* `usage.completion_tokens`: number of input tokens
* `usage.prompt_tokens`: number of output tokens (including reasoning)
* `usage.total_tokens`: total token usage
***
**Here’s how to use it in code:**
```py Gemini native theme={null}
from google import genai
from google.genai import types
import time
def generate():
client = genai.Client(
api_key="sk-***", # Replace this with your key from AiHubMix
http_options={"base_url": "https://aihubmix.com/gemini"},
)
model = "gemini-2.5-pro-preview-03-25"
contents = [
types.Content(
role="user",
parts=[
types.Part.from_text(text="""How is the "Rule of 72" derived in the financial world?"""),
],
),
]
generate_content_config = types.GenerateContentConfig(
response_mime_type="text/plain",
)
final_usage_metadata = None
for chunk in client.models.generate_content_stream(
model=model,
contents=contents,
config=generate_content_config,
):
print(chunk.text, end="")
if chunk.usage_metadata:
final_usage_metadata = chunk.usage_metadata
# Once all chunks are processed, print the full token usage
if final_usage_metadata:
print(f"\nUsage: {final_usage_metadata}")
if __name__ == "__main__":
generate()
```
```py OpenAI compatible theme={null}
from openai import OpenAI
client = OpenAI(
api_key="sk-***", # Replace this with your key from AiHubMix
base_url="https://aihubmix.com/v1",
)
completion = client.chat.completions.create(
model="gemini-2.5-flash-preview-04-17",
reasoning_effort="low", #"low", "medium", and "high", which behind the scenes we map to 1K, 8K, and 24K thinking token budgets. If you want to disable thinking, you can set the reasoning effort to "none".
messages=[
{
"role": "user",
"content": "How is the "Rule of 72" derived in the financial world?"
}
],
stream=True
)
#print(completion.choices[0].message.content)
for chunk in completion:
print(chunk.choices[0].delta)
# Only print token usage info on the last chunk (which includes full usage data)
if chunk.usage and chunk.usage.completion_tokens > 0:
print(f"Output tokens: {chunk.usage.completion_tokens}")
print(f"Input tokens: {chunk.usage.prompt_tokens}")
print(f"Total tokens: {chunk.usage.total_tokens}")
```
***
Last updated: 2026-07-07