Reach APIReach API
Dashboard

Gemini Native API

This platform provides a chat and text-generation endpoint compatible with the Gemini GenerateContent API.

This document is intended for client-side integrators and focuses on the public request path, authentication method, request parameters, and example payloads. Field names and JSON structure are kept as close as possible to the native Gemini GenerateContent API.

Overview:

  • Endpoints:
    • POST /v1beta/models/{model}:generateContent
    • POST /v1beta/models/{model}:streamGenerateContent
  • Capability type: chat / text generation
  • Response modes:
    • generateContent: standard JSON response
    • streamGenerateContent: text/event-stream SSE response
  • Protocol style: the request body follows the native GenerateContentRequest structure and does not wrap content in an extra input field

1. API Overview

  • HTTP method: POST
  • Request paths:
    • /v1beta/models/{model}:generateContent
    • /v1beta/models/{model}:streamGenerateContent
  • Content-Type: application/json
  • Response type:
    • Non-streaming: application/json
    • Streaming: text/event-stream

2. Authentication and Headers

Example headers:

x-goog-api-key: YOUR_REACH_API_KEY
Content-Type: application/json

At least one of Authorization or x-goog-api-key must be provided. We recommend x-goog-api-key to stay aligned with the native Gemini protocol.

Header details:

HeaderRequiredDescription
AuthorizationNoPlatform API key in the format Bearer sk-xxxxxx
x-goog-api-keyNoYou can also pass the platform API key directly in this header for Gemini-compatible authentication
Content-TypeYesMust be application/json

3. Request Body

The request body follows the native GenerateContentRequest object structure:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Please introduce yourself in one sentence."
        }
      ]
    }
  ],
  "generationConfig": {
    "temperature": 0.2
  }
}

3.1 Top-Level Parameters

FieldTypeRequiredDescription
contentsarray<object>YesConversation content list, at least one item
toolsarray<object>NoTool or function declarations
toolConfigobjectNoTool calling strategy configuration
safetySettingsarray<object>NoSafety policy overrides
systemInstructionobjectNoSystem instruction
generationConfigobjectNoGeneration parameters such as temperature, topP, topK, and maxOutputTokens
cachedContentstringNoResource name for reused cached content

3.2 Common contents.parts Patterns

Text input example:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Write a short product introduction within 50 words."
        }
      ]
    }
  ]
}

Multi-part input example:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Please describe this image."
        },
        {
          "fileData": {
            "mimeType": "image/png",
            "fileUri": "https://cdn.example.com/demo.png"
          }
        }
      ]
    }
  ]
}

4. Request Examples

4.1 Standard Non-Streaming Request

curl -X POST "https://direct.reachapi.ai/v1beta/models/YOUR_MODEL_ID:generateContent" \
  -H "x-goog-api-key: YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Introduce ReachAPI in one sentence."
          }
        ]
      }
    ],
    "generationConfig": {
      "temperature": 0.2
    }
  }'

4.2 Streaming Request

curl -X POST "https://direct.reachapi.ai/v1beta/models/YOUR_MODEL_ID:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Summarize today'\''s priorities in three lines."
          }
        ]
      }
    ]
  }'

4.3 Request with Function Declarations

curl -X POST "https://direct.reachapi.ai/v1beta/models/YOUR_MODEL_ID:generateContent" \
  -H "x-goog-api-key: YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Help me check the weather in Shanghai."
          }
        ]
      }
    ],
    "tools": [
      {
        "functionDeclarations": [
          {
            "name": "get_weather",
            "description": "Get weather information for a city",
            "parameters": {
              "type": "OBJECT",
              "properties": {
                "city": {
                  "type": "STRING"
                }
              },
              "required": ["city"]
            }
          }
        ]
      }
    ]
  }'

5. Successful Response

Example non-streaming response:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "ReachAPI is a unified AI gateway."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ],
  "modelVersion": "YOUR_MODEL_VERSION",
  "responseId": "resp_xxx",
  "usageMetadata": {
    "promptTokenCount": 18,
    "candidatesTokenCount": 22,
    "totalTokenCount": 40
  }
}

5.1 usageMetadata

Common fields include:

FieldDescription
promptTokenCountNumber of input tokens
candidatesTokenCountNumber of candidate output tokens
totalTokenCountTotal number of tokens

6. Error Response

Gemini-style error example:

{
  "error": {
    "code": 400,
    "message": "Field `contents` is required",
    "status": "INVALID_ARGUMENT"
  }
}

Common scenarios:

  • contents is missing or empty
  • Invalid request parameter format
  • Authentication failure

7. Compatibility Notes

  • {model} in the path is the model ID, so model is not passed in the request body
  • This document lists commonly used fields and example payloads. Actual field names and structures follow the Gemini GenerateContent API
  • If you use advanced capabilities such as tools, toolConfig, or cachedContent, confirm that the target model actually supports them
  • When calling streamGenerateContent, explicitly adding ?alt=sse is recommended

8. Supported Models and Reference Pricing

The following prices are summarized from the unified pricing document and apply to the Gemini text models currently listed. Pricing was checked on 2026-04-17. For detailed pricing rules, refer to gemini.md.

ModelInputOutputCache readSearch grounding
gemini-3.1-pro-preview$2.00 / 1M (<= 200K) / $4.00 / 1M (> 200K)$12.00 / 1M (<= 200K) / $18.00 / 1M (> 200K)$0.20 / 1M (<= 200K) / $0.40 / 1M (> 200K)First 5,000 prompts / month are free, then $14 / 1,000 search queries
gemini-2.5-pro$1.25 / 1M (<= 200K) / $2.50 / 1M (> 200K)$10.00 / 1M (<= 200K) / $15.00 / 1M (> 200K)$0.125 / 1M (<= 200K) / $0.25 / 1M (> 200K)First 1,500 RPD are free, then $35 / 1,000 grounded prompts
gemini-2.5-flash$0.30 / 1M$2.50 / 1M$0.03 / 1MFirst 1,500 RPD are free, then $35 / 1,000 grounded prompts
gemini-2.5-flash-lite$0.10 / 1M$0.40 / 1M$0.01 / 1MFirst 1,500 RPD are free, then $35 / 1,000 grounded prompts

Notes:

  • Some Gemini models use different input token pricing tiers, with different unit prices for <= 200K and > 200K
  • The billing unit for Search grounding may vary across model generations. See the detailed pricing document for specifics

9. References

On this page

1. API Overview
2. Authentication and Headers
3. Request Body
3.1 Top-Level Parameters
3.2 Common contents.parts Patterns
4. Request Examples
4.1 Standard Non-Streaming Request
4.2 Streaming Request
4.3 Request with Function Declarations
5. Successful Response
5.1 usageMetadata
6. Error Response
7. Compatibility Notes
8. Supported Models and Reference Pricing
9. References