Gemini ネイティブ形式: ストリーミングと非ストリーミング応答

When you call Gemini のネイティブ形式 (/v1beta generateContent), the response uses Google’s candidates / parts 構造で、OpenAI 互換モードとは異なります。このページでは、非ストリーミング（generateContent）とストリーミング（streamGenerateContent）の両方を解析する方法を説明します。

リクエスト側（base_url は https://api.apiyi.com で、/v1 なし、x-goog-api-key 認証、thinking_level 制御）は Gemini Native Format Guide で説明しています。このページはレスポンス側のみを扱います。例では軽量モデル gemini-3.1-flash-lite を使用します。

非ストリーミング応答

エンドポイント …:generateContent。答えは candidates[0].content.parts[] にあります:

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [
        { "text": "1+1 equals 2.", "thoughtSignature": "EjQKMgEM…" }
      ]
    },
    "finishReason": "STOP",
    "index": 0
  }],
  "usageMetadata": {
    "promptTokenCount": 15,
    "candidatesTokenCount": 6,
    "totalTokenCount": 21
  },
  "modelVersion": "gemini-3.1-flash-lite",
  "responseId": "Il0taoSYJ5Cez7…"
}

答えを取得するには、parts を反復処理し、各 text を連結します:

import requests

resp = requests.post(
    "https://api.apiyi.com/v1beta/models/gemini-3.1-flash-lite:generateContent",
    headers={"Content-Type": "application/json", "x-goog-api-key": "YOUR_API_KEY"},
    json={"contents": [{"parts": [{"text": "What is 1+1?"}]}]},
    timeout=60,
)
data = resp.json()
parts = data["candidates"][0]["content"]["parts"]
text = "".join(p["text"] for p in parts if "text" in p)
print(text)
print(data["usageMetadata"])

curl "https://api.apiyi.com/v1beta/models/gemini-3.1-flash-lite:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -d '{"contents":[{"parts":[{"text":"What is 1+1?"}]}]}'

finishReason は 大文字の STOP です（OpenAI の小文字の stop ではありません）。他の値には MAX_TOKENS と SAFETY があります。part には thoughtSignature のみが含まれ、text は含まれない場合があるため、反復処理する際は if "text" in p でフィルターしてください。そうしないと KeyError が発生します。

thoughtSignature

Gemini 3シリーズのモデルは、部分に thoughtSignature（暗号化された推論状態）を付与します — テストでは、軽量版の gemini-3.1-flash-lite でもこれが返ります。

シングルターン: 不要です。無視してください。
マルチターン / 関数呼び出し: 前回レスポンスの thoughtSignature を次のターンの contents にそのまま返し、モデルが推論チェーンを継続できるようにします。公式の google-genai SDK はこれを自動的に処理します。REST を手書きする場合は、フィールドを落とさないでください。Gemini の関数呼び出しを参照してください。

これは OpenAI compatible mode との重要な違いです。互換モードでは推論モデルはステートレスで、シグネチャを公開しません。thoughtSignature を持つのはネイティブ形式だけで、これをターンをまたいで返す必要があります。

ストリーミング応答 (SSE)

エンドポイント …:streamGenerateContent。各行は data: {...} で、各チャンクの増分は candidates[0].content.parts[0].text です:

data: {"candidates":[{"content":{"parts":[{"text":"1"}]},"finishReason":"","index":0}],"usageMetadata":{...}}
data: {"candidates":[{"content":{"parts":[{"text":"+1 equals 2."}]},"finishReason":"","index":0}],"usageMetadata":{...}}
data: {"candidates":[{"content":{"parts":[{"thoughtSignature":"EjQK…"}]},"finishReason":"STOP","index":0}],"usageMetadata":{...}}

APIYI ゲートウェイ経由では、ストリーミングは常に SSE data: 行を返します（?alt=sse の有無にかかわらず）、また [DONE] の終端子はありません — finishReason == "STOP" を持つチャンクで終了します。その最後のチャンクには通常、thoughtSignature のみが含まれ、text は含まれません。

import json, requests

resp = requests.post(
    "https://api.apiyi.com/v1beta/models/gemini-3.1-flash-lite:streamGenerateContent?alt=sse",
    headers={"Content-Type": "application/json", "x-goog-api-key": "YOUR_API_KEY"},
    json={"contents": [{"parts": [{"text": "Write a short poem"}]}]},
    stream=True, timeout=120,
)

text, usage = "", None
for line in resp.iter_lines(decode_unicode=True):
    if not line or not line.startswith("data: "):
        continue
    chunk = json.loads(line[6:])
    usage = chunk.get("usageMetadata", usage)        # cumulative; later overrides
    for cand in chunk.get("candidates", []):
        for p in cand.get("content", {}).get("parts", []):
            if "text" in p:                          # skip signature-only chunks
                text += p["text"]
                print(p["text"], end="", flush=True)
print("\n", usage)

usageMetadata は 各チャンクに含まれ、累積されます（candidatesTokenCount は出力とともに増えます）— 最後の チャンクの値だけを使えばよく、手動で合計する必要はありません。

OpenAI互換モードとの主な違い

項目	Geminiネイティブ (`/v1beta`)	OpenAI互換 (`/v1/chat/completions`)
base_url	`https://api.apiyi.com`（`/v1`なし）	`https://api.apiyi.com/v1`
認証ヘッダー	`x-goog-api-key`	`Authorization: Bearer`
回答の場所	`candidates[0].content.parts[].text`	`choices[0].message.content`
ストリーム増分	各チャンクの`parts[].text`	`choices[0].delta.content`
ストリーム終端	`finishReason == "STOP"`、`[DONE]`なし	`data: [DONE]`
終了理由	大文字の`STOP` / `MAX_TOKENS`	小文字の`stop`
思考シグネチャ	✅ `thoughtSignature`（ターンをまたいで返却）	❌ 非公開
usage	`usageMetadata`（各ストリームチャンクで累積）	`usage`（ストリーム末尾で1回）

使用量と課金

u = data["usageMetadata"]
# promptTokenCount  input / candidatesTokenCount output / thoughtsTokenCount thinking / totalTokenCount total

thoughtsTokenCount（推論用 token）は出力レートで課金されます。コストを抑えるには、thinking_levelを使って上限を設定してください。
キャッシュヒット項目（cachedContentTokenCount）の割引については、Gemini キャッシュ課金をご覧ください。
完全なフィールドリファレンスは、Gemini ネイティブ形式ガイドの「使用量フィールド」セクションにあります。

基本

基本API

画像API（公式）

動画API（公式）

マルチモーダル理解API

テキストAPI

Gemini ネイティブ形式: ストリーミングと非ストリーミング応答

非ストリーミング応答

thoughtSignature

ストリーミング応答 (SSE)

OpenAI互換モードとの主な違い

使用量と課金

関連リンク

​非ストリーミング応答

​thoughtSignature

​ストリーミング応答 (SSE)

​OpenAI互換モードとの主な違い

​使用量と課金

​関連リンク

非ストリーミング応答

thoughtSignature

ストリーミング応答 (SSE)

OpenAI互換モードとの主な違い

使用量と課金

関連リンク