Gemini Responses

Call Gemini 4 Argon, Gemini 3.8 Flash and Gemini 3.1 Pro through the OpenAI Responses API with a BeatAPI key.

• One endpoint, POST /v1/responses, for every current Gemini model. Change model to switch.
• Streaming and function calling. gemini-4-argon also understands images and long video.
• Works with the OpenAI SDK: change the base URL and use a BeatAPI key. For an existing Chat Completions integration, see Chat Completions.
• Conversation state is not stored on the server: send the whole history in input on every turn.

Opens this endpoint in the API Explorer. Enter your BeatAPI API key and send: the call is real and is billed to your own balance.

Models

Send one of these IDs as model. Each is a separate model; do not treat them as aliases of each other.

• Prices are the base tier, discount already applied. A long-context tier, cached-input rates and cache writes are not in this table; see the price table.
• — means the catalogue does not publish the number.

Older IDs of this family still work and are listed on Legacy models.

Quick start

Install the openai package on your server, keep the key in BEATAPI_API_KEY, and never put it in browser code. output_text is the SDK’s shortcut for the answer text. These are request examples, not recorded model outputs.

Read the answer from output_text (or from the output_text parts of output), then check status and usage. An HTTP 200 alone does not prove the answer satisfies your task: validate it in your application. Text requests return directly; do not poll /v1/tasks for them.

curl --request POST \
  --url https://direct.beatapi.io/v1/responses \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gemini-3.8-flash",
  "max_output_tokens": 2000,
  "input": "Design a resilient webhook retry strategy for a payments API."
}'

Free versions

These models have a free version. It costs nothing per token, is called on the same endpoint with the free model ID, and has its own per-minute limit: 1 successful request per minute per account before the first top-up and 10 per minute after. Its stability is not guaranteed: it can be rate-limited or withdrawn at any time. See Free models.

gemini-3.8-flash-free

curl --request POST \
  --url https://direct.beatapi.io/v1/responses \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gemini-3.8-flash-free",
  "input": "Say hello in one sentence."
}'

Endpoint and authentication

POST https://direct.beatapi.io/v1/responses

Request parameters

Standard OpenAI Responses fields are accepted. Request-format compatibility does not mean every model-specific option or hosted tool is supported, so test the options you rely on.

Response

A non-streaming call returns one JSON object. This is an abbreviated example.

{
  "id": "resp_example",
  "object": "response",
  "model": "gemini-3.8-flash",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Retry with exponential backoff and jitter, and make every handler idempotent."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 19,
    "output_tokens": 16,
    "total_tokens": 35
  }
}

Response fields

Streaming

Set "stream": true. The stream starts with response.created, carries the answer in response.output_text.delta events and ends with response.completed.

• The response is text/event-stream; without streaming it is application/json.
• A function call arrives as its own output item, and its arguments stream in response.function_call_arguments.delta events.
• A failure before the model is called is returned as a normal JSON error with an HTTP status, not as a stream event.
• Set explicit timeouts and reconnect a streamed response safely.

event: response.created
data: {"type":"response.created","response":{"id":"resp_example","status":"in_progress"}}
event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"Retry"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":" with backoff"}
event: response.completed
data: {"type":"response.completed","response":{"id":"resp_example","status":"completed"}}

Errors

HTTP errors at a glance

Authentication, routing, rate-limit and unknown-model failures are answered before the model is called, in the BeatAPI envelope: error.code, error.message, retryable, request_id. Every other failure keeps the OpenAI SDK shape {"error": {"message", "type", "code"}}: the code is in error.code and the request id ends message. See Errors.

Full code table and retry policy: Errors.

Notes

• Gemini models also answer on Chat Completions, Anthropic Messages and Gemini native.
• Gemini models reason by default and bill thinking tokens as output, so budget max_output_tokens for the thinking as well as the answer.
• Cached input is billed at a lower rate: one twentieth of the input price on gemini-4-argon, one tenth on gemini-3.8-flash and gemini-3.1-pro-preview. There is no separate cache storage fee. Check the cached-input count in usage instead of assuming a hit. A gemini-3.1-pro-preview prompt over 200,000 tokens is billed at its higher tier for the whole request; see the price table.
• Keep API keys on trusted servers, log the response request ID, and retry only 429, 500 and 503.