Gemini chat

The two Gemini plan groups support different parameters. Read "Group differences" below before you integrate.

Your first request

Gemini chat models can be called through three protocols: OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages. The example below uses Chat Completions. Authenticate with Authorization: Bearer sk-your-key; x-api-key also works.

curl https://api.hop-base.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Available Gemini models vary by plan group. Call GET /v1/models with the current key and only use complete IDs returned by that response.

x-goog-api-key and /v1beta/models/{model}:generateContent are not supported. Both Gemini groups serve /v1/chat/completions, /v1/responses, and /v1/messages; Gemini Official Direct also provides /v1/messages/count_tokens (a local estimate, not billed). The details of each protocol differ between the groups; see "Group differences" below.

Available models

Use gemini-3.8-flash by default. Treat every model ID containing preview as a preview without a stability guarantee.

Rates vary by plan group. The signed-in model catalog for the current key is authoritative.

Group differences

Gemini (all models, incl. image) supports structured output through response_format with json_object and json_schema.

Gemini Official Direct: Chat Completions parameters

• messages: supported content parts are text, image_url, input_audio, file, refusal; any other type returns 400. image_url accepts only base64 data URLs. For file, file_data must be a data URL, and file_id is not supported. role: "tool" results are sent to the model as function results.
• tools / tool_choice: tool_choice accepts auto, none, required, a named function, and allowed_tools. Parallel tool calls and multi-turn tool use are supported. With parallel_tool_calls: false, only the first call is kept. The legacy functions / function_call fields also work. Tool parameter schemas are accepted as full JSON Schema, so $ref, $defs, anyOf, additionalProperties, and similar keywords need no rewriting.
• response_format: json_object and json_schema.
• stop: a string or an array. n: 1–8, returning that many choices.
• max_tokens / max_completion_tokens: if both are sent, max_tokens wins; thinking tokens count against it, so use at least 4096.
• temperature / top_p: forwarded unchanged within the model's official range. seed and top_k are also supported.
• presence_penalty / frequency_penalty: ignored when 0. Non-zero values are forwarded unchanged, and current Gemini models return 400 Penalty is not enabled for this model.
• reasoning_effort: mapped to a thinking budget; see "Thinking" below.
• Fields that return 400: logprobs, top_logprobs, logit_bias, modalities, audio, web_search_options (modalities only when it includes a value other than text).
• Fields that are ignored and do not affect output: user, metadata, store, service_tier, safety_identifier, prompt_cache_key, stream_options, prediction, verbosity.

For general field descriptions, see the Chat Completions API reference.

Gemini Official Direct: Responses and Anthropic Messages

Responses (POST /v1/responses)

• Tools: function tools and custom free-form tools (such as Codex's apply_patch) are supported. Built-in or hosted tools (web_search, file_search, code_interpreter, computer, and so on) return 400. tool_choice takes the same values as on Chat Completions, and max_tool_calls truncates the number of calls.
• Stateless: previous_response_id, conversation, background, prompt templates, and item_reference return 400. Send the full history in input on every request (Codex does this by default).
• Structured output uses text.format.
• Fields that are ignored and do not affect output: store, include, user, metadata, safety_identifier, prompt_cache_key, service_tier, truncation, text.verbosity.

Anthropic Messages (POST /v1/messages)

• Set the Base URL to https://api.hop-base.com (no /v1). Claude Code connects directly through CC Switch. The model name must be a Gemini model ID such as gemini-3.8-flash; claude-* names are not mapped automatically.
• tool_choice accepts auto, any, tool, and none. With disable_parallel_tool_use: true, only the first call is kept.
• image / document blocks accept only base64 sources; url sources return 400. tool_result can carry images.
• Structured output uses output_format or output_config.format (json_schema).
• /v1/messages/count_tokens is a local estimate and is not billed.
• Fields that are ignored and do not affect output: metadata, service_tier, cache_control, context_management.

Thought signatures (multi-turn tool use)

Tool calls from Gemini 3 and later models carry a thought signature. Where it appears in each protocol:

Send the assistant message back unchanged on the next turn. If your client drops these fields, the request still succeeds: the gateway tries to recover the signature, and if it cannot, it skips validation the way the official API allows. Reasoning continuity may be slightly lower in that case.

Streaming with SSE (add "stream": true)

curl https://api.hop-base.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.1-pro-preview", "stream": true,
    "messages": [{"role": "user", "content": "Hello"}]}'

On the Gemini Official Direct group, all three protocols support "stream": true, and the events follow the OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages specifications respectively, including tool-call deltas. The stream may be sent in chunks only after the full response is generated, so the first chunk can arrive around the time the full response is ready; this applies to all three protocols. On Chat Completions, the last chunk always carries usage.

The Gemini (all models, incl. image) group streams token by token. Add stream_options.include_usage when you need usage.

A non-streaming response carries the charge in usage: cost_usd is the USD amount actually deducted from your balance, cost is the same charge in CNY, and currency is the currency of cost (always CNY), with the same values in the X-HopBase-Cost / X-HopBase-Cost-USD / X-HopBase-Currency response headers. Streaming responses carry none of these; check the charge under Usage in the console. See Charges.

Thinking

Gemini models think by default, and thinking cannot be fully turned off. Thinking tokens count against your output limit. If max_tokens is too low, you can get finish_reason=length with only a few characters of text, so use at least 4096.

In the OpenAI format, thinking tokens are included in completion_tokens and also reported in completion_tokens_details.reasoning_tokens (on Gemini Official Direct's Responses endpoint, in output_tokens_details.reasoning_tokens). In the native format they appear in usageMetadata.thoughtsTokenCount.

The Gemini Official Direct group maps reasoning_effort to a thinking budget:

gemini-4-argon accepts only thinking levels and does not use the budgets above: none / minimal → low, medium → medium, high → high; low behaves like omitting the field and uses the model's default level. Its thinking cannot be turned off.

On Responses, enabling reasoning.summary returns a reasoning summary. On Anthropic Messages, thinking.type set to enabled or adaptive returns thinking blocks, and budget_tokens above 24576 is capped at 24576.

Billing on Gemini Official Direct: thinking tokens are billed as output, and tokens that built-in tools feed back to the model (toolUsePromptTokenCount) are billed as input. usage follows each protocol's standard shape; on Anthropic Messages, input_tokens excludes cache reads, which are reported in cache_read_input_tokens.

On the Gemini (all models, incl. image) group, none noticeably reduces thinking.

Gemini-native payload passthrough

Request bodies carried over from the Gemini SDK can be sent as-is. On the Gemini Official Direct group, the same endpoint also accepts the native contents field and returns the native response shape.

curl https://api.hop-base.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "contents": [{"role": "user", "parts": [{"text": "Hello"}]}]
  }'

The native format accepts only the official top-level fields:

contents, systemInstruction, generationConfig, safetySettings, tools,
toolConfig, cachedContent, labels, serviceTier, model

Any other field, such as store, max_tokens, or messages, returns 400 Unknown name …. The native format does not support streaming, so do not send "stream": true.

Next steps

• For Gemini image generation (Banana), see the Image API
• When something fails, check Troubleshooting