Skip to content
Documentation
StartGemini API

Gemini API

Gemini 4 Argon and Gemini 3.8 Flash through Messages, Chat Completions, and Responses: window, dated prices, reasoning, search, connection, and the server prompt.

Gemini uses the same gd-… key and shared Guard balance. Generation exposes two exact model IDs: gemini-4-argon and gemini-3.8-flash. The short name gemini resolves to Gemini 4 Argon, the newest model. No other public Gemini IDs exist.

Get a key from @guardapi, then choose HTTP, the Python SDK, or the Node.js SDK. One shared key is issued; no separate Google account is required.

Quick start

  1. Save the key in GUARD_API_KEY; do not commit it or print it to logs.
  2. Choose Messages, Chat Completions, or Responses. Applications with an OpenAI-compatible API use https://api.guardrelay.ai/v1, Anthropic clients use https://api.guardrelay.ai.
  3. Send the exact model (gemini-4-argon) and an output budget. Use a regular JSON response for the first request.
  4. Check the text, terminal state, and usage; then enable stream: true if needed.
bash
export GUARD_API_KEY="gd-your-key"
curl https://api.guardrelay.ai/v1/chat/completions \
  -H "Authorization: Bearer $GUARD_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"gemini-4-argon","messages":[{"role":"user","content":"Reply with OK"}],"max_tokens":4096}'
powershell
$env:GUARD_API_KEY = "gd-your-key"
$headers = @{ Authorization = "Bearer $env:GUARD_API_KEY" }
$body = @{
  model = "gemini-4-argon"
  max_tokens = 4096
  messages = @(@{ role = "user"; content = "Reply with OK" })
} | ConvertTo-Json -Depth 10
Invoke-RestMethod -Method Post `
  -Uri "https://api.guardrelay.ai/v1/chat/completions" `
  -Headers $headers `
  -ContentType "application/json" `
  -Body $body

One address, three APIs

APIPathOutput budget
MessagesPOST /v1/messagesmax_tokens, required
Chat CompletionsPOST /v1/chat/completionsmax_tokens / max_completion_tokens; 4096 when omitted
ResponsesPOST /v1/responsesmax_output_tokens; 4096 when omitted

The maximum answer of a regular (synchronous) request is 65,536 tokens for both models. The default of 4096 is set by the Guard gateway, not by the model.

The family is selected by the exact model on the shared address. Anthropic clients use https://api.guardrelay.ai (the client appends /v1/messages itself), OpenAI-compatible ones use https://api.guardrelay.ai/v1.

Messages:

bash
curl https://api.guardrelay.ai/v1/messages \
  -H "Authorization: Bearer $GUARD_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"gemini-4-argon","max_tokens":4096,"messages":[{"role":"user","content":"Reply with OK"}]}'

Responses:

bash
curl https://api.guardrelay.ai/v1/responses \
  -H "Authorization: Bearer $GUARD_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"gemini-4-argon","input":"Reply with OK","max_output_tokens":4096}'

Chat Completions is shown above, in the quick start.

Models and input

Model IDNameWindowAnswer limitReasoningInput
gemini-4-argonGemini 4 Argon1,048,576, shared by input and answerup to 65,536Low, Medium, HighText, images, PDF
gemini-3.8-flashGemini 3.8 Flashinput up to 1,048,576up to 65,536Low, Medium, HighText, images, PDF

Images and PDF are accepted as embedded base64 data or as an https link. How to send them is shown on the Vision and PDF / documents pages.

Pricing

ModelPeriodUncached input / 1MCache read / 1MOutput / 1M
gemini-4-argonuntil December 1, 2026, 00:00 UTC$2.00$0.10$10.00
gemini-4-argonfrom December 1, 2026, 00:00 UTC$4.00$0.20$20.00
gemini-3.8-flashuntil January 1, 2027, 00:00 UTC$0.75$0.075$3.75
gemini-3.8-flashfrom January 1, 2027, 00:00 UTC$1.50$0.15$7.50

Rates are USD per 1M tokens and equal the Gemini API rates. Google changes them on fixed dates: the new rates apply from the date shown.

The Gemini cache is Google's automatic cache only. cache_control markers are accepted, but the cache retention time is not promised. The discount applies only to tokens that Google actually read from the cache: a cache read is billed at the rate in the table. Writing to the cache has no separate charge.

For gemini-4-argon at the rates until December 1, 2026, 00:00 UTC, 4,000 uncached input + 8,000 cached input + 1,000 output tokens cost 4000×2.00/1M + 8000×0.10/1M + 1000×10.00/1M = $0.01880000. From December 1, 2026, 00:00 UTC the same tokens cost $0.03760000.

Web search is billed separately: $0.014 for each Gemini search request, starting with the first. Retrieved text is billed as ordinary input tokens. See the search section below for details.

Reasoning

Gemini reasoning cannot be turned off completely. The level is set by a field of the selected API.

APILevel fieldAlso
Chat Completionsreasoning_effortno other fields
Responsesreasoning.effortwith reasoning.summary: "auto" the model returns a short summary of its reasoning
Messagesoutput_config.effortthe thinking field accepts {"type": "adaptive"} with an optional display, or {"type": "enabled"} with no other fields, budget_tokens included; display: "omitted" together with adaptive hides the reasoning text
ModelLevel valuesDefault
gemini-4-argonlow, medium, highhigh
gemini-3.8-flashlow, medium, highmedium

Any other level value gets a 400 error with the code invalid_request (in Chat Completions and Responses with param: "reasoning_effort"); Guard does not replace it with another one. Other settings the model does not have (for example, turning reasoning off) also get a clear error, not a substitution.

Gemini searches the web with Google search. Search works on all three APIs and is switched on by an object in tools; it is billed separately, by the number of search requests.

APIObject in tools
Messages{"type": "web_search_20250305", "name": "web_search"}
Chat Completions{"type": "web_search"}
Responses{"type": "web_search"}
json
{
  "model": "gemini-4-argon",
  "max_tokens": 4096,
  "messages": [{"role": "user", "content": "What is new today?"}],
  "tools": [{"type": "web_search_20250305", "name": "web_search"}]
}
ItemCharge
A search request$0.014 for each request, starting with the first
Before the answerthe cost of one search ($0.014) is held; the final charge uses the actual number of searches
Retrieved textordinary input tokens
  • Claude Code sends the web_search_20250305 tool too, so search from Claude Code works.
  • Gemini has no separate web_fetch tool yet: a request with it gets a clear refusal, while Google search works.
  • The search limit max_uses is accepted but not kept: Google decides how many searches to run. Every search is billed at the price above.
  • Site lists (allowed_domains, blocked_domains) are not supported: a request with them gets a clear refusal.

Token counting

POST /v1/messages/count_tokens works for Gemini free of charge. The count before an answer returns an approximate estimate of the whole input (system instructions, tools, and the server prompt when it applies), not an exact Google count. It is a reference number: the charge follows the actual usage, not the estimate.

Server prompt

The Gemini server prompt is configured like that of the other families: the key needs an active entitlement for the Gemini family and the application option turned on. Without them, the request goes without a prompt. See Server prompts for details.

Errors and limits

  • The error format, codes, and request_id are shared by all families: see Error codes.
  • A clear refusal comes back for, among other cases: video and audio; an image or PDF at an address that is not https; a reasoning level the model does not have (invalid_request) and turning reasoning off; a reasoning budget budget_tokens; site lists in search; a separate web_fetch tool.

Where to go next

MessagesBody, usage, stop_reason, tools, and SSE.Chat CompletionsThe OpenAI-compatible request and response.ResponsesThe Responses request and terminal usage.Server promptsEntitlement, option, and the UNLOCK mark.Python SDKExamples for anthropic and openai.Node.js SDKExamples for the two SDKs.

Sections

On this page