Skip to content
RunAPI Developer Docs
EN 中文
API Reference
API Reference

Gemini Stream Generate Content

Send a request through RunAPI's Gemini-compatible Stream Generate Content operation.

View Markdown
01

Overview

Use RunAPI's Gemini-compatible Stream Generate Content operation with a compatible model and the protocol's request and response shapes.

Quick start

  1. Create an API key and set it as RUNAPI_API_KEY.
  2. Choose a compatible model, then send the documented path parameters and JSON body.
  3. Read the JSON response or server-sent events shown for this operation, and handle protocol errors.

Endpoint

POST /v1beta/models/{model}:streamGenerateContent?alt=sse
Base URL
https://runapi.ai
Contract version
v1
Preferred authentication
x-goog-api-key: YOUR_API_TOKEN
02

Authentication carriers

RunAPI accepts each carrier listed below. Generated samples use the protocol's preferred header.

header
Authorization: Bearer YOUR_API_TOKEN
header
x-api-key: YOUR_API_TOKEN
header - Preferred
x-goog-api-key: YOUR_API_TOKEN
query
?key=YOUR_API_TOKEN
03

Compatible models

Open a model page for current pricing, rate limits, and commercial-usage details.

Show 52 compatible models
04

Request contract

JSON body

Only fields with both public protocol and RunAPI support evidence are listed. Additional JSON body fields are passed through.

JSON body4 fields
contentsarray
Required

Conversation content in Gemini Content and Part format.

generationConfigobject
Optional

Gemini generation configuration for the request.

systemInstructionobject
Optional

System instructions represented as Gemini Content.

toolsarray
Optional

Tools the model may call.

Path parameters1 field
modelstring
Required

RunAPI model identifier placed in the wire path.

Request example

JSON 
{
  "contents": [
    {
      "parts": [
        {
          "text": "Say hello in one sentence."
        }
      ],
      "role": "user"
    }
  ]
}
05

SSE event: chunk

text/event-stream

Schema

JSON 
{
  "additionalProperties": true,
  "properties": {
    "candidates": {
      "items": {
        "additionalProperties": true,
        "properties": {
          "content": {
            "additionalProperties": true,
            "properties": {
              "parts": {
                "type": "array"
              },
              "role": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "finishReason": {
            "type": "string"
          },
          "index": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "type": "array"
    },
    "modelVersion": {
      "type": "string"
    },
    "responseId": {
      "type": "string"
    },
    "usageMetadata": {
      "additionalProperties": true,
      "properties": {
        "candidatesTokenCount": {
          "type": "integer"
        },
        "promptTokenCount": {
          "type": "integer"
        },
        "totalTokenCount": {
          "type": "integer"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}

Example

JSON 
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Hello"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "modelVersion": "gemini-3.5-flash",
  "responseId": "resp_example",
  "usageMetadata": {
    "candidatesTokenCount": 8,
    "promptTokenCount": 12,
    "totalTokenCount": 20
  }
}
06

Protocol error: invalid_request

HTTP 400

Schema

JSON 
{
  "additionalProperties": true,
  "properties": {
    "error": {
      "additionalProperties": true,
      "properties": {
        "code": {
          "type": "integer"
        },
        "message": {
          "type": "string"
        },
        "status": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message",
        "status"
      ],
      "type": "object"
    }
  },
  "required": [
    "error"
  ],
  "type": "object"
}

Example

JSON 
{
  "error": {
    "code": 400,
    "message": "contents is required",
    "status": "INVALID_ARGUMENT"
  }
}
07

Usage

Schema

JSON 
{
  "additionalProperties": true,
  "properties": {
    "candidatesTokenCount": {
      "type": "integer"
    },
    "promptTokenCount": {
      "type": "integer"
    },
    "totalTokenCount": {
      "type": "integer"
    }
  },
  "type": "object"
}

Example

JSON 
{
  "candidatesTokenCount": 8,
  "promptTokenCount": 12,
  "totalTokenCount": 20
}
08

Generated Code Samples

Each cURL, JavaScript, and Python sample sends the validated request from this contract without requiring a protocol-specific SDK.

CURL 
curl -X POST https://runapi.ai/v1beta/models/gemini-3.5-flash:streamGenerateContent\?alt\=sse \
  -H x-goog-api-key:\ YOUR_API_TOKEN \
  -H Content-Type:\ application/json \
  -d \{\"contents\":\[\{\"role\":\"user\",\"parts\":\[\{\"text\":\"Say\ hello\ in\ one\ sentence.\"\}\]\}\]\}
JAVASCRIPT 
const response = await fetch("https://runapi.ai/v1beta/models/gemini-3.5-flash:streamGenerateContent?alt=sse", {
  method: "POST",
  headers: {
  "x-goog-api-key": "YOUR_API_TOKEN",
  "Content-Type": "application/json"
},
  body: JSON.stringify({
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Say hello in one sentence."
        }
      ]
    }
  ]
})
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value, { stream: true }));
}

Install

BASH 
pip install requests
PYTHON 
import requests

response = requests.post(
    "https://runapi.ai/v1beta/models/gemini-3.5-flash:streamGenerateContent?alt=sse",
    headers={"x-goog-api-key": "YOUR_API_TOKEN", "Content-Type": "application/json"},
    json={"contents": [{"role": "user", "parts": [{"text": "Say hello in one sentence."}]}]},
    stream=True
)
response.raise_for_status()
for line in response.iter_lines(decode_unicode=True):
    if line:
        print(line)