KovAPIKovAPI
POST https://kovapi.com/v1/chat/completions

Gemini 4 Hydrogen Beta supports text chat, streaming and Low / Medium / High thinking levels (Low by default), plus image input, function calling and JSON structured output. Use the OpenAI SDK. Thinking tokens are billed as output.

📥 Context window (max input):The official context is 1,048,576 tokens shared by input and output. Split very long jobs during Beta.

Try in Playground →

Quick start

Two steps: send a request, then stream the answer. Replace YOUR_API_KEY with your key and the commands below run as they are. The endpoint matches OpenAI Chat Completions, so existing OpenAI code only needs a new base_url and model.

Step 1 · Send a request

curl
curl https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-4-hydrogen", "messages": [{"role": "user", "content": "Explain photosynthesis in one sentence"}]}'

Response (HTTP 200)

JSON
{
  "id": "chatcmpl-7f3c9a1e2b4d6f8a",
  "object": "chat.completion",
  "created": 1791281400,
  "model": "gemini-4-hydrogen",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Photosynthesis is how plants use sunlight to turn carbon dioxide and water into sugar, releasing oxygen.",
        "reasoning_content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 186,
    "total_tokens": 204,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 144}
  }
}

message.content is the answer and message.reasoning_content the thinking. usage holds the tokens this request is billed for: thinking tokens are part of completion_tokens and bill at the output price.

Step 2 · Stream the answer (recommended)

curl
curl -N https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-4-hydrogen", "stream": true, "messages": [{"role": "user", "content": "Explain photosynthesis in one sentence"}]}'

The stream is standard SSE: each chunk carries text in choices[0].delta.content, the last chunk carries usage, and it ends with data: [DONE]. Stream long answers and thinking models: a non-streaming request is cut off after about 10 minutes.

Python (OpenAI SDK)

Python
from openai import OpenAI

client = OpenAI(base_url="https://kovapi.com/v1", api_key="YOUR_API_KEY")

# 1. One request, one answer
resp = client.chat.completions.create(
    model="gemini-4-hydrogen",
    messages=[{"role": "user", "content": "Explain photosynthesis in one sentence"}],
)
print(resp.choices[0].message.content)

# 2. Streaming
stream = client.chat.completions.create(
    model="gemini-4-hydrogen",
    messages=[{"role": "user", "content": "Explain photosynthesis in one sentence"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Authentication

Header
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Create an API Key in the console to start.

At a glance

Context window~1,000,000 tokens
InputText, images
ThinkingChoose low / medium / high; default: low. All levels use the same token rates.
Tool callingYes (OpenAI tools format)
JSON outputYes (response_format)
Web searchYes (web_search: true; the search itself is free)
Endpoints/v1/chat/completions
StreamingYes (stream: true, SSE)
BillingPer token: input, output (thinking included) and cache hits each have a price; failures are free

Request parameters

The JSON body of POST /v1/chat/completions, the same as OpenAI Chat Completions. The common parameters, and what each one does on this model:

ParameterTypeRequiredDescription
modelstringYesThe model id: gemini-4-hydrogen.
messagesarrayYesThe conversation: each message has a role (system, user, assistant or tool) and content. content is a string, or an array of text and image_url parts (image input, see below). For multi-turn chat, send the whole history in order.
streambooleanNotrue streams the answer as SSE, with usage in the last chunk. Defaults to false.
max_tokensintegerNoRequested output length, including thinking. To manage costs, also constrain the length in the prompt.
temperature / top_pnumberNoSampling parameters, passed to the model as sent (temperature from 0 to 2). Thinking models may not follow them.
reasoning_effortstringNoChoose low / medium / high; default: low. All levels use the same token rates.
tools / tool_choicearray / stringNoFunction calling in the standard OpenAI format. When the model calls a function it returns finish_reason: "tool_calls" with tool_calls; see below.
response_formatobjectNo{"type": "json_object"} makes the model return valid JSON only; also say in the prompt that you want JSON and which fields.
web_searchbooleanNotrue runs a web search first and hands the results to the model as reference; see below.

Other OpenAI parameters (such as stop, seed, user) are passed to the model as sent; whether they take effect is up to the model.

Price

Billed per token at the live rates below (per million tokens). Only successful requests are billed, on actual usage: failures, timeouts and refusals are free. 1 credit = $0.005.

TypeUSD / 1M tokensCredits / 1M tokens
Input$0.4590
Output (thinking included)$2.25450
Cache hit$0.02254.5

For example, a request with 2,000 input tokens and 1,000 output tokens (thinking included) costs about $0.0032.

Thinking

Set reasoning_effort to low, medium or high; omitted values default to low.

usage.completion_tokens includes thinking and answer tokens; do not add thinking tokens a second time.

All levels have the same rates. Higher thinking effort consumes more output tokens.

Thinking tokens are part of usage.completion_tokens and bill at the output price (some models also break them out in completion_tokens_details.reasoning_tokens).

JSON · reasoning_effort
{
  "model": "gemini-4-hydrogen",
  "messages": [{"role": "user", "content": "Explain photosynthesis in one sentence"}],
  "reasoning_effort": "medium"
}

Prompt caching

Automatic implicit caching is supported. Repeated long inputs may hit the cache; actual hits cost one twentieth of the normal input rate. Repetition does not guarantee a hit, and explicit cache creation is not provided.

usage.prompt_tokens is total input. usage.prompt_tokens_details.cached_tokens is the cached portion of that total. Only actual hits use the cached rate.

Image input

Put an image_url part in the content array. A base64 data URI (data:image/png;base64,...) is the recommended form and can always be read; a public image link has to be downloaded first, and occasionally it cannot be fetched or times out. Images count as input tokens by the model vendor rules.

curl
curl https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-4-hydrogen", "messages": [{"role": "user", "content": [{"type": "text", "text": "What is in this image"}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}}]}]}'

Tool calling (function calling)

Describe your functions in tools with JSON Schema. When the model decides to call one, it returns finish_reason: "tool_calls" with the function name and arguments (a JSON string) in message.tool_calls.

curl
curl https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-4-hydrogen", "messages": [{"role": "user", "content": "What is the weather in Shanghai right now"}], "tools": [{"type": "function", "function": {"name": "get_weather", "description": "Current weather of a city", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}}}]}'

Run the function, append the result as a role: "tool" message with the matching tool_call_id, and send the conversation again; the model then gives its final answer. tool_choice takes auto, none, required or a named function.

Beta limits

  • Text chat, streaming, three thinking levels, image input, function calling and JSON structured output have been verified.
  • The official context is about 1M tokens shared by input and output; split very long tasks.
  • Failed requests are not billed; interrupted requests that produced output settle at actual usage.

Errors and refunds

Errors come back as an error object (message, type, code, param); decide by the HTTP status and code, never by matching the text of message. Failed requests are not billed; the full list is in Error codes.

HTTPcodeCauseWhat to do
400invalid_messages / invalid_role / invalid_max_tokensA chat request's messages is missing, empty or malformed, a role is not one of the allowed values, or max_tokens is not a positive integer. param names the field.Fix the field named in param.
400model_not_foundThe model id is misspelled, model is missing, or the model cannot be used on this endpoint (a chat model on the image endpoint, for example).Use a model id from GET /v1/models or the API reference.
400max_tokens_too_smallA reasoning model spent all of max_tokens thinking and wrote no answer (non-streaming chat).Raise max_tokens and retry.
4xxinvalid_requestThe model provider rejected the request (an over-long context or an unsupported parameter, for example); the status and message are passed on as the provider sent them, and code is the provider's value.Change the request as message says.
401invalid_api_keyThe key does not exist, was deleted or is disabled, or the account is disabled.Check the key on the API Keys page of the console.
402insufficient_quotaNot enough balance to hold this request. The gateway holds the highest possible cost of the request first, so a burst of concurrent calls can trigger it too.After a burst, wait a few seconds and retry; otherwise top up.
403permission_deniedThe model is not on the key's model allowlist.Use a model on the allowlist, or edit the allowlist in the console.
429rate_limit_exceededOver the requests-per-minute limit set on this key (counted over the last 60 seconds). No Retry-After header.Wait a few seconds and retry, or raise the key's limit in the console.
429rate_limit_exceededThe model is at capacity and the request was not sent. Chat endpoints only: image and video jobs are never refused but queue instead. The OpenAI-compatible endpoints add Retry-After.Wait the seconds in Retry-After, then retry.
502upstream_timeoutThe upstream timed out, including taking too long to send the first token.Retry; use stream: true for long answers.
502upstream_unavailableThe upstream failed or is unavailable for the moment.Retry shortly.
502upstream_busyThe model provider is rate-limiting. A provider's 429 is never passed on as a 429; you get this 502 instead.Retry shortly.
502empty_completionThe model provider returned empty content. This is not a judgement of your content.Retry.
503model_maintenanceThe model is under maintenance and takes no requests; no other model answers in its place meanwhile.Retry when maintenance ends; see Status.

If a stream fails after it started sending, the status code stays as it was: the error arrives as a data line carrying error, or the stream just ends (without data: [DONE]). Treat it as interrupted.