Gemini API Integration Guide: Google-Compatible Calls and Large Context

1. Overview

This site provides Google Gemini API compatible access, supporting both generateContent and streaming generation methods. For projects using the Google GenAI SDK or Gemini-compatible clients, simply point your request URL to our site's Gemini gateway and use your local sk- API key to get started.

The available Gemini series models are subject to our model dashboard (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.

2. API Endpoints

Method	Path	Description
POST	/v1beta/models/{model}:generateContent	Gemini generation entry; request body is a generateContent payload
POST	/v1beta/models/{model}:streamGenerateContent?alt=sse	Streaming generation (SSE)
GET	/v1/models	List of models and pricing (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.

3. Authentication

As with other endpoints on this site, use your local sk- key:

Authorization: Bearer sk-your-api-key

We also support x-api-key and the official Google x-goog-api-key: sk-your-api-key headers.

4. 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-api-key" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "Introduce the Gemini API in one sentence."}]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 512
    }
  }'

4.2 Including 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-api-key" \
  -d '{
    "model": "gemini-3.5-flash",
    "systemInstruction": {
      "parts": [{"text": "You are a senior API integration engineer. Please be concise."}]
    },
    "contents": [
      {"role": "user", "parts": [{"text": "How do I choose between streaming and non-streaming interfaces?"}]}
    ]
  }'

5. 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 is user / model
contents[].parts	array	Yes	Content blocks, typically {text}
systemInstruction	object	No	System instructions, 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 enable streaming, default false

6. 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	Text generated by the model
candidates[].finishReason	Finish reason: STOP / MAX_TOKENS / SAFETY / RECITATION
usageMetadata.promptTokenCount	Input token count (basis for billing)
usageMetadata.candidatesTokenCount	Output token count (basis for billing)
usageMetadata.totalTokenCount	Total token count

7. Streaming Output

By adding "stream": true to the request body, the server returns candidate content in chunks 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"}]}

Clients should parse each data: line and concatenate candidates[0].content.parts[0].text; the process is complete when the final chunk's finishReason is STOP.

8. Common Error Codes

HTTP Status	Meaning	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 header
403	Key deactivated, insufficient balance, or unauthorized model	Recharge balance or check key permissions
404	Model or endpoint not found	Verify model slug
429	Too many requests	Implement backoff and retry
500	Internal server error	Retry later; contact support if the issue persists

Error responses follow the structure: {"code": status_code, "message": "error description", "data": null}.

9. Compatibility

• The Google GenAI SDK (google-genai) can be connected by configuring a custom endpoint.
• Supports various Gemini-compatible clients that target generateContent.
• Model names must match the slugs returned by GET /v1/models.