跳到正文
RunAPI 开发者文档
EN 中文
API 参考
API 参考

Gemini Generate Content

通过 RunAPI 的 Gemini 兼容 Generate Content operation 发送请求。

查看 Markdown
01

概览

使用兼容模型和对应协议的请求、响应结构调用 RunAPI 的 Gemini 兼容 Generate Content operation。

快速开始

  1. 创建 API Key，并将其设置为 RUNAPI_API_KEY。
  2. 选择兼容模型，然后发送文档所列的路径参数和 JSON 请求体。
  3. 读取此 operation 展示的 JSON 响应或服务器发送事件，并处理协议错误。

端点

POST /v1beta/models/{model}:generateContent
基础 URL
https://runapi.ai
Contract 版本
v1
首选身份验证
x-goog-api-key: YOUR_API_TOKEN
02

身份验证载体

RunAPI 接受下列每种载体；生成的示例使用该协议的首选请求头。

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

兼容模型

打开模型页可查看当前价格、限流和商业使用详情。

展开 52 个兼容模型
04

请求 Contract

JSON 请求体

这里只列出同时具有公共协议与 RunAPI 支持证据的字段；其他 JSON 请求体字段会原样传递。

JSON 请求体4 个字段
contentsarray
必填

Conversation content in Gemini Content and Part format.

generationConfigobject
可选

Gemini generation configuration for the request.

systemInstructionobject
可选

System instructions represented as Gemini Content.

toolsarray
可选

Tools the model may call.

路径参数1 个字段
modelstring
必填

RunAPI model identifier placed in the wire path.

请求示例

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

同步响应

HTTP 200

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"
}

示例

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

协议错误：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"
}

示例

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"
}

示例

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

生成的代码示例

每个 cURL、JavaScript 和 Python 示例都会发送此 Contract 中经过验证的请求，无需协议专用 SDK。

CURL 
curl -X POST https://runapi.ai/v1beta/models/gemini-3.5-flash:generateContent \
  -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:generateContent", {
  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 data = await response.json();
console.log(data);

安装

BASH 
pip install requests
PYTHON 
import requests

response = requests.post(
    "https://runapi.ai/v1beta/models/gemini-3.5-flash:generateContent",
    headers={"x-goog-api-key": "YOUR_API_TOKEN", "Content-Type": "application/json"},
    json={"contents": [{"role": "user", "parts": [{"text": "Say hello in one sentence."}]}]}
)
response.raise_for_status()
print(response.json())
09

相关指南