# Gemini API format

> Send Gemini content and function calls to Katara Cortex, with streaming and the same payment rules as Chat Completions.

Section: Developers. Web page: https://docs.staging.katara.com/developers/gemini/

Send Gemini-format requests to `https://api.staging.katara.com/v1beta/models/{model}:generateContent` or `:streamGenerateContent`. Katara translates the request and routes it through Katara Cortex.

## Model names

The `{model}` in the path can be any name, a Gemini model id included, and Katara Cortex serves it ([Model names in requests](https://docs.staging.katara.com/concepts/models.txt#model-names-in-requests)). A missing or malformed name is refused.

## Send a request

Use your Katara API key in `Authorization: Bearer …` or `x-goog-api-key`. Query-string keys are refused. Conflicting credentials are refused too.

```bash
curl 'https://api.staging.katara.com/v1beta/models/gemini-2.5-pro:generateContent' \
  -H "Authorization: Bearer $KATARA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain this function."}]}],"generationConfig":{"maxOutputTokens":512}}'
```

For server-sent events, use `:streamGenerateContent?alt=sse`. Without `alt=sse`, the streaming endpoint returns an incremental JSON array. Text parts arrive as they are produced. Read through the end of the stream: usage and cost can arrive after a candidate's `finishReason`.

The reply includes `candidates`, `usageMetadata`, `responseId` and `modelVersion`, which is `katara/cortex`. Katara also retains the original `usage` object and its `katara` extension. These carry the token counts and cost from the common payment path; translation does not estimate a second charge. Payment challenge, receipt and request-id headers remain available. A payment refusal keeps its status and body.

## Function calls

Declare functions in `tools[].functionDeclarations`. Use Gemini `parameters` with uppercase schema types, or `parametersJsonSchema` with JSON Schema. A declaration may use only one of those fields. A function name starts with a letter or `_` and has up to 128 letters, digits, `_`, `.`, `:` or `-`. Unsupported Gemini schema keywords return an error.

```json
{
  "contents": [{"role": "user", "parts": [{"text": "Read config.json."}]}],
  "tools": [{"functionDeclarations": [{
    "name": "read_file",
    "description": "Read a project file",
    "parameters": {
      "type": "OBJECT",
      "properties": {"path": {"type": "STRING"}},
      "required": ["path"]
    }
  }]}]
}
```

A model part contains `functionCall` with `id`, `name` and object-valued `args`. Keep the model turn in your history, then send a user part with `functionResponse`, the same `id` and `name`, and an object-valued `response`. Resolve every call before sending the next user text. A result with no id is accepted only when its name identifies exactly one pending call. Duplicate ids, ambiguous results and unmatched results are refused before inference.

`functionCallingConfig.mode` accepts `AUTO`, `NONE` and `ANY`. `allowedFunctionNames` restricts `ANY` to declared functions.

## Supported controls

Text contents, text system instructions, function declarations, calls and responses are supported. `generationConfig` accepts `temperature`, `topP`, `maxOutputTokens`, `stopSequences`, `seed`, and `candidateCount: 1`. `temperature` runs from 0 to 2 and `topP` from 0 to 1. Katara applies `stopSequences` itself: the reply ends before the first match.

`responseMimeType` accepts `text/plain` and `application/json`. JSON output uses the model's JSON-object mode. Response schemas, media parts, hosted tools, safety settings, cached content and thought signatures are refused. Unknown fields are refused instead of being dropped.

`thinkingConfig.thinkingLevel` (`LOW`, `MEDIUM`, `HIGH`) and any `thinkingBudget` from `-1` up are accepted, and Katara decides how much the model thinks whatever they say. Send one of the two, not both. `includeThoughts: false` omits thought text from the reply; it does not change model execution or its charge. Thought text that is returned has `thought: true`.

The `katara` request extension accepts the same controls as Chat Completions, including the Community preference, task and step summary. Session and payment rules are unchanged. A request cannot use this format to turn Community on for an account that has turned it off.

## Errors

Gateway errors keep the status and body of [Chat Completions](https://docs.staging.katara.com/developers/errors.txt):
`402 insufficient_quota` when the funds cannot cover the request, `429 provider_rate_limited`,
and `500` when every candidate's reply failed or was refused, and `503` (`provider_overloaded`,
`upstream_timeout`, `no_capacity`) with `Retry-After`. A body
over 32 MB is `413`, and a compressed body is `415`.

## Gemini CLI

Configure the CLI's custom endpoint and API-key authentication:

```bash
export GOOGLE_GEMINI_BASE_URL='https://api.staging.katara.com'
export GEMINI_API_KEY="$KATARA_API_KEY"
gemini --model gemini-2.5-pro
```

Use the API-key or gateway authentication mode, rather than Google-account or Vertex authentication. A CLI release that adds a format feature outside the supported set receives an explicit error. The client still executes its own tools and uses its own permission settings.