Google Gemini API Guide
AvalAI provides Google Gemini models through one API key and several request formats. Choose gemini-4-hydrogen for coding, agent workflows, and multimodal knowledge work with text output, or gemini-decision-1 for typed judgments over shared evidence. The existing Gemini 3.7 Flash examples remain available below; follow the controls and limits of the exact model you select.
Gemini 4 Hydrogen
Use gemini-4-hydrogen for everyday coding, agent workflows, and multimodal knowledge work that needs a text answer. It is available from AvalAI tier 0 through native Gemini, Chat Completions, Responses, and Messages. Copy the complete body for the chosen endpoint; its schemas are different.
| Property | Hydrogen |
|---|---|
| Native generation route | /v1beta/models/gemini-4-hydrogen:generateContent |
| Compatible routes | /v1/chat/completions, /v1/responses, /v1/messages |
| Google's context contract | 1,048,576 tokens shared by input, thinking, and output |
| Synchronous output ceiling | 65,536 tokens including thinking |
| Thinking levels upstream | low, medium, high, xhigh; default high |
| AvalAI input / cached input / output | $1.50 / $0.075 / $7.50 per 1 million tokens |
| Caching | Implicit caching only; no explicit cache creation or cached-content references |
Google describes text, image, audio, video, and PDF input with text output. Choose the documented content transport for your actual route and evaluate it separately; this guide's new baseline uses text. Google's longer decoding workflows are separate from synchronous generation. The shared window does not establish one million synchronous output tokens or confirm AvalAI background execution. Reserve output room for thinking and the answer.
Start with the default thinking behavior and omit sampling controls. Google ignores in-range temperature, top_p/topP, and top_k/topK values for Hydrogen and rejects values outside the supported ranges. Its implicit cache threshold is 4,096 input tokens upstream, and an eligible hit receives the listed cached-input rate; a long repeated prompt alone does not prove a hit. Read actual usage and billed cost. Hydrogen returns text and does not support image/audio generation or the Live API upstream. Hosted tools require their own AvalAI route support and validation; the four generation routes alone do not establish that support.
Native Hydrogen baseline
This small request follows the native schema and confirmed AvalAI route. It has not been executed against the live AvalAI API. See the announcement for corresponding illustrative responses and examples for the compatible endpoints.
curl --fail-with-body --connect-timeout 10 --max-time 30 \
https://api.avalai.ir/v1beta/models/gemini-4-hydrogen:generateContent \
-H "Authorization: Bearer $AVALAI_API_KEY" \
-H "Content-Type: application/json" \
--data-binary '{
"contents": [
{
"role": "user",
"parts": [{"text": "Explain a token bucket rate limiter in three sentences."}]
}
]
}'Keep the SDK base URL at https://api.avalai.ir for native Gemini and at https://api.avalai.ir/v1 for the OpenAI SDK. Native Messages has its own authentication and body conventions. The Google provider page and v1beta reference describe model-specific boundaries.
Gemini Decision 1: choose a decision schema
Use gemini-decision-1 when the answer space is already defined: decide whether a condition holds, select a support queue or tool label, or score evidence against ordered criteria. It is available from AvalAI tier 0. It produces typed judgments with no generated output tokens; it does not write replies, generate tool arguments, or perform the selected action.
| Route | Shared evidence | Questions and binary type | Response |
|---|---|---|---|
Standard Decisions /v1/decisions | input | Array; name identifies each question; binary type predicate | Answer array; usage.input_tokens / output_tokens |
System One /v1/systemone | state | Map keyed by question ID; binary type noul; optional criteria.true / false | Answer map; usage.input_tokens / output_tokens |
Native Google Decisions /v1beta/decisions | input | Map keyed by question ID; binary type noul; optional criteria.true_description / false_description | Answer map; usage.total_input_tokens / total_output_tokens |
Standard Choice takes choices and standard Score takes levels; both native formats use criteria, with an option map for Choice and an ordered description array for Score. Changing only the URL leaves the wrong schema. Start with the paired text request and complete illustrative response in the selected reference. Serialize arbitrary structured records into shared text for the Google native input; do not borrow Jev's object-state examples as a Gemini transport guarantee.
Google's model window is 262,144 tokens for shared input plus all questions. Its native API allows up to 1,000 independent questions; this is an upstream limit, not a measured AvalAI capacity result or a replacement for OpenAI's and Clef's separate contracts. Input costs $0.10 per million tokens across input modalities. Shared evidence is billed once; each question contributes instruction, criteria, and formatting tokens. Output and cached-input catalog rates are $0.00, but caching is unsupported and the request still incurs input cost.
Google describes text, image, video, audio, and PDF capabilities. This release starts with shared text because PDF/document blocks, resolution controls, multipart text fidelity, remote media, and Files API forwarding have not been qualified through AvalAI. An upstream feature is not a verified transport path. No live response or decision-quality measurement for this new ID is provided by earlier Jev checks. Evaluate model judgments on labeled cases, preserve missing fields, route uncertain cases to review, and keep permission checks and action execution in deterministic application code. See the decision-model guide for integration policy.
Gemini 3.7 Flash at a Glance
| Property | Details |
|---|---|
| Model ID | gemini-3.7-flash |
| Input context | 1,048,576 tokens |
| Maximum output | 65,536 tokens |
| Inputs | Text, image, video, audio, PDF |
| Output | Text |
| Endpoints | v1beta/, v1/chat/completions, v1/messages, partial v1/responses |
| Promotional pricing | $0.75 input, $0.075 cached input, $3.75 output per 1M tokens through December 31, 2026 |
| Standard pricing | $1.50 input, $0.15 cached input, $7.50 output per 1M tokens after December 31, 2026 |
Choose an API Format
- Use
v1/chat/completionsfor OpenAI-compatible applications and the broadest migration compatibility. - Use
v1/messageswith the Anthropic SDK or an Anthropic-compatible request format. - Use native Gemini
v1beta/for Gemini-specific request fields and tools. - Use
v1/responsesonly after verifying that every parameter and tool required by your workflow is supported.
OpenAI-Compatible Example
curl https://api.avalai.ir/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AVALAI_API_KEY" \
-d '{
"model": "gemini-3.7-flash",
"messages": [{"role": "user", "content": "Review this architecture and return a phased implementation plan."}]
}'import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["AVALAI_API_KEY"],
base_url="https://api.avalai.ir/v1",
)
response = client.chat.completions.create(
model="gemini-3.7-flash",
messages=[
{
"role": "user",
"content": "Review this architecture and return a phased implementation plan.",
}
],
)
print(response.choices[0].message.content)import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.AVALAI_API_KEY,
baseURL: "https://api.avalai.ir/v1",
});
const response = await client.chat.completions.create({
model: "gemini-3.7-flash",
messages: [
{
role: "user",
content: "Review this architecture and return a phased implementation plan.",
},
],
});
console.log(response.choices[0].message.content);Native Gemini Example
curl https://api.avalai.ir/v1beta/models/gemini-3.7-flash:generateContent \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AVALAI_API_KEY" \
-d '{
"contents": [
{
"role": "user",
"parts": [{"text": "Design a reliable tool-using incident triage agent."}]
}
]
}'Production Guidance
- Keep API keys on the server and load them from environment variables.
- Evaluate representative prompts, tools, and multimodal inputs before moving production traffic.
- Add retries with backoff for transient failures and observe the documented rate limits.
- Validate structured outputs in application code even when using a response schema.
- Forecast long-running workloads using the standard Gemini 3.7 Flash rates that begin after December 31, 2026.