Gemini API format

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

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.

{
  "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: 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:

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.