Gemini API Integration Guide: Google Compatible Calls & Large Context

I. Overview

This site provides Google Gemini API compatible access, supporting both generateContent and streaming generation. Projects using the Google GenAI SDK or Gemini-compatible clients can connect by pointing their request URL to our gateway's Gemini endpoint and using an sk- key from our dashboard.

Currently available Gemini series models are based on the Model Square (e.g., gemini-3.7-flash, gemini-3.6-flash, gemini-3.5-flash, gemini-3.5-flash-lite, etc.). A complete list and unit pricing can be queried via GET /v1/models.

II. API Endpoints

Method	Path	Description
POST	/v1beta/models/{model}:generateContent	Gemini generation entry; request body is the generateContent payload
POST	/v1beta/models/{model}:streamGenerateContent?alt=sse	Streaming generation (SSE)
GET	/v1/models	List of models and unit prices (no authentication required)

Gateway URL: https://www.relay-api.com. The model name is appended to the URL (/v1beta/models/{model}:generateContent, matching the official Google format); the request body follows the generateContent payload structure.

III. Authentication

Consistent with other APIs on this site, use an sk- key:

Authorization: Bearer sk-your-key

The x-api-key header and the official Google x-goog-api-key: sk-your-key header are also supported.

IV. Quick Start (curl)

4.1 Non-Streaming

curl -X POST https://www.relay-api.com/v1beta/models/gemini-3.7-flash:generateContent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-key" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "Introduce the Gemini API in one sentence"}]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 512
    }
  }'

4.2 With System Instructions (systemInstruction)

curl -X POST https://www.relay-api.com/v1beta/models/gemini-3.7-flash:generateContent \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-your-key" \
  -d '{
    "model": "gemini-3.5-flash",
    "systemInstruction": {
      "parts": [{"text": "You are a senior API integration engineer; keep your answers concise."}]
    },
    "contents": [
      {"role": "user", "parts": [{"text": "How do I choose between streaming and non-streaming interfaces?"}]}
    ]
  }'

V. Request Parameters

Field	Type	Required	Description
model	string	Yes	Model slug, e.g., gemini-3.7-flash
contents	array	Yes	Conversation content, elements are {role, parts[]}; role values: user / model
contents[].parts	array	Yes	Content block, usually {text} for text blocks
systemInstruction	object	No	System instruction, structure {parts: [{text}]}
generationConfig.temperature	number	No	Sampling temperature, default 1.0
generationConfig.topP	number	No	Nucleus sampling
generationConfig.topK	int	No	Top-K sampling
generationConfig.maxOutputTokens	int	No	Maximum output tokens
generationConfig.stopSequences	array	No	Stop sequences
stream	bool	No	Whether to return streaming output, default false

VI. Response Structure

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{"text": "The Gemini API supports text, multimodal input, and streaming output."}]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 16,
    "candidatesTokenCount": 20,
    "totalTokenCount": 36
  }
}

Field	Description
candidates[].content.parts[].text	Model-generated text
candidates[].finishReason	Finish reason: STOP / MAX_TOKENS / SAFETY / RECITATION
usageMetadata.promptTokenCount	Input tokens (billing basis)
usageMetadata.candidatesTokenCount	Output tokens (billing basis)
usageMetadata.totalTokenCount	Total tokens

VII. Streaming Output

After adding "stream": true to the request body, the server returns candidate content chunk-by-chunk via SSE:

data: {"candidates": [{"content": {"parts": [{"text": "Gemini"}]}, "index": 0}]}

data: {"candidates": [{"content": {"parts": [{"text": " API supports streaming"}]}, "index": 0}]}

data: {"candidates": [{"content": {"parts": [{"text": " output."}]}, "index": 0, "finishReason": "STOP"}]}

The client parses each data: line and concatenates candidates[0].content.parts[0].text; when the finishReason of the last chunk is STOP, generation is complete.

VIII. Common Error Codes

HTTP Status	Meaning	Recommended Action
400	Bad request (missing contents, model not found, etc.)	Check request body and model name
401	Invalid or missing API key	Check Authorization / x-api-key headers
403	Key disabled, insufficient balance, or model/route not authorized	Top up or check key permissions
404	Model or endpoint not found	Verify the model slug
429	Too many requests	Back off and retry
500	Internal server error	Retry later; contact support if the issue persists

Error response body follows the structure: {"code": status_code, "message": "error message", "data": null}.

IX. Compatibility Notes

• Google GenAI SDK (google-genai) can be connected by configuring a custom endpoint.
• Supports various Gemini-compatible clients targeting generateContent.
• Use the slug returned by GET /v1/models for the model name.

Base URL Note: This site accepts both /v1beta/models/... and /v1beta/v1beta/models/... (as well as /v1/... and /v1/v1/...), so whether your client prepends /v1 or /v1beta does not affect connectivity; you can use the domain root or the path including /v1beta. Please copy the Model ID from the "Model ID" section in the top-right corner of the "Tokens" page in the console.