API ReferenceText APIs
Gemini Native API
このプラットフォームでは、Gemini GenerateContent API と互換性のあるチャット / テキスト生成エンドポイントを提供しています。
このドキュメントはクライアント側で統合を行う開発者向けに、公開リクエストパス、認証方式、主要パラメータ、代表的なリクエスト例を説明するものです。フィールド名と JSON 構造は、できるだけ Gemini GenerateContent API のネイティブ仕様に寄せています。
概要:
- エンドポイント:
POST /v1beta/models/{model}:generateContentPOST /v1beta/models/{model}:streamGenerateContent
- 機能カテゴリ: チャット / テキスト生成
- レスポンス形式:
generateContent: 通常の JSON レスポンスstreamGenerateContent:text/event-streamの SSE レスポンス
- プロトコル上の特徴: リクエストボディはネイティブの
GenerateContentRequest構造に従い、余分なinputラッパーは使いません
1. API 概要
- HTTP メソッド:
POST - リクエストパス:
/v1beta/models/{model}:generateContent/v1beta/models/{model}:streamGenerateContent
- Content-Type:
application/json - レスポンス形式:
- 非ストリーミング:
application/json - ストリーミング:
text/event-stream
- 非ストリーミング:
2. 認証とヘッダー
ヘッダー例:
x-goog-api-key: YOUR_REACH_API_KEY
Content-Type: application/jsonAuthorization または x-goog-api-key のいずれかを指定してください。Gemini ネイティブ仕様に合わせるため、x-goog-api-key の利用を推奨します。
ヘッダー詳細:
| Header | 必須 | 説明 |
|---|---|---|
Authorization | いいえ | Bearer sk-xxxxxx 形式のプラットフォーム API キー |
x-goog-api-key | いいえ | Gemini 互換認証として、このヘッダーでプラットフォーム API キーを直接渡すこともできます |
Content-Type | はい | application/json である必要があります |
3. リクエストボディ
リクエストボディは、ネイティブの GenerateContentRequest 構造に従います。
{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Please introduce yourself in one sentence."
}
]
}
],
"generationConfig": {
"temperature": 0.2
}
}3.1 トップレベルパラメータ
| Field | Type | 必須 | 説明 |
|---|---|---|---|
contents | array<object> | はい | 会話コンテンツ配列。少なくとも 1 件必要です |
tools | array<object> | いいえ | ツールまたは関数宣言 |
toolConfig | object | いいえ | ツール呼び出し戦略の設定 |
safetySettings | array<object> | いいえ | セーフティポリシー上書き |
systemInstruction | object | いいえ | システム指示 |
generationConfig | object | いいえ | temperature, topP, topK, maxOutputTokens などの生成設定 |
cachedContent | string | いいえ | 再利用キャッシュコンテンツのリソース名 |
3.2 よく使う contents.parts パターン
テキスト入力例:
{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Write a short product introduction within 50 words."
}
]
}
]
}複数パート入力例:
{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Please describe this image."
},
{
"fileData": {
"mimeType": "image/png",
"fileUri": "https://cdn.example.com/demo.png"
}
}
]
}
]
}4. リクエスト例
4.1 非ストリーミングの標準リクエスト
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 ストリーミングリクエスト
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 関数宣言付きリクエスト
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. 正常レスポンス
非ストリーミングレスポンスの例:
{
"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
代表的なフィールド:
| Field | 説明 |
|---|---|
promptTokenCount | 入力トークン数 |
candidatesTokenCount | 候補出力トークン数 |
totalTokenCount | 合計トークン数 |
6. エラーレスポンス
Gemini 形式のエラー例:
{
"error": {
"code": 400,
"message": "Field `contents` is required",
"status": "INVALID_ARGUMENT"
}
}代表的なエラーケース:
contentsがない、または空- リクエストパラメータの形式が不正
- 認証に失敗した
7. 互換性に関する注意
- パス中の
{model}がモデル ID なので、リクエストボディ側にmodelは含めません - このドキュメントでは、よく使われるフィールドと代表的なペイロードのみを掲載しています。実際のフィールド名や構造は Gemini GenerateContent API に従います
tools、toolConfig、cachedContentのような高度機能を使う場合は、対象モデルが実際に対応しているか確認してくださいstreamGenerateContentを使う場合は、?alt=sseを明示的に付けることを推奨します
8. 対応モデルと参考価格
以下の価格は統一価格ドキュメントをもとに整理したもので、現在掲載している Gemini 系テキストモデルに適用されます。価格確認日は 2026-04-17 です。詳細な価格ルールは gemini.md を参照してください。
| Model | Input | Output | Cache read | Search 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 / 1M | First 1,500 RPD are free, then $35 / 1,000 grounded prompts |
gemini-2.5-flash-lite | $0.10 / 1M | $0.40 / 1M | $0.01 / 1M | First 1,500 RPD are free, then $35 / 1,000 grounded prompts |
補足:
- Gemini の一部モデルでは、
<= 200Kと> 200Kで入力トークン単価が分かれます - Search grounding の課金単位はモデル世代ごとに異なる場合があります。詳細は価格ドキュメントを参照してください
9. 参考資料
- Gemini API reference: https://ai.google.dev/api/generate-content
- Gemini text generation guide: https://ai.google.dev/gemini-api/docs/text-generation
- Unified platform pricing document:
gemini.md