Developer Dashboard

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.

PropertyHydrogen
Native generation route/v1beta/models/gemini-4-hydrogen:generateContent
Compatible routes/v1/chat/completions, /v1/responses, /v1/messages
Google's context contract1,048,576 tokens shared by input, thinking, and output
Synchronous output ceiling65,536 tokens including thinking
Thinking levels upstreamlow, medium, high, xhigh; default high
AvalAI input / cached input / output$1.50 / $0.075 / $7.50 per 1 million tokens
CachingImplicit 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.

bash
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.

RouteShared evidenceQuestions and binary typeResponse
Standard Decisions /v1/decisionsinputArray; name identifies each question; binary type predicateAnswer array; usage.input_tokens / output_tokens
System One /v1/systemonestateMap keyed by question ID; binary type noul; optional criteria.true / falseAnswer map; usage.input_tokens / output_tokens
Native Google Decisions /v1beta/decisionsinputMap keyed by question ID; binary type noul; optional criteria.true_description / false_descriptionAnswer 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 ​

PropertyDetails
Model IDgemini-3.7-flash
Input context1,048,576 tokens
Maximum output65,536 tokens
InputsText, image, video, audio, PDF
OutputText
Endpointsv1beta/, 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/completions for OpenAI-compatible applications and the broadest migration compatibility.
  • Use v1/messages with the Anthropic SDK or an Anthropic-compatible request format.
  • Use native Gemini v1beta/ for Gemini-specific request fields and tools.
  • Use v1/responses only after verifying that every parameter and tool required by your workflow is supported.

OpenAI-Compatible Example ​

bash
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."}]
  }'
python
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)
javascript
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 ​

bash
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.