Нативный формат Gemini: потоковые и непотоковые ответы

Когда вы вызываете нативный формат Gemini (/v1beta generateContent), ответ использует структуру Google candidates / parts, отличную от режима совместимости с OpenAI. На этой странице показано, как разбирать как ответ без потоковой передачи (generateContent), так и ответ с потоковой передачей (streamGenerateContent).

Сторона запроса (base_url — https://api.apiyi.com без /v1, x-goog-api-key аутентификации, thinking_level управления) описана в Руководстве по нативному формату Gemini. Эта страница посвящена только стороне ответа. В примерах используется облегченная модель 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 (а не строчный stop в OpenAI); другие значения включают MAX_TOKENS и SAFETY. part может содержать только thoughtSignature и не содержать text, поэтому при итерации фильтруйте по if "text" in p, иначе возникнет KeyError.

Сигнатура мысли

Модели серии Gemini 3 прикрепляют thoughtSignature (зашифрованное состояние рассуждения) к фрагментам — в тестировании даже облегчённый gemini-3.1-flash-lite возвращает его.

Один ход: не нужно; игнорируйте это.
Многоходовый / вызов функций: передавайте thoughtSignature предыдущего ответа обратно дословно в contents следующего хода, чтобы модель могла продолжить цепочку рассуждения. Официальный google-genai SDK делает это автоматически; при ручной записи REST не пропускайте это поле. См. Вызов функций Gemini.

Это ключевое отличие от режима совместимости с OpenAI: в режиме совместимости модели рассуждения без состояния и не предоставляют сигнатуру; только нативный формат содержит 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`
Заголовок Auth	`x-goog-api-key`	`Authorization: Bearer`
Расположение ответа	`candidates[0].content.parts[].text`	`choices[0].message.content`
Инкремент stream	каждого фрагмента `parts[].text`	`choices[0].delta.content`
Завершающий маркер stream	`finishReason == "STOP"`, без `[DONE]`	`data: [DONE]`
Причина завершения	верхний регистр `STOP` / `MAX_TOKENS`	нижний регистр `stop`
Сигнатура мысли	✅ `thoughtSignature` (передавайте обратно между ходами)	❌ не отображается
usage	`usageMetadata` (накапливается в каждом фрагменте stream)	`usage` (один раз, в конце stream)

Использование и тарификация

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

thoughtsTokenCount (thinking tokens) тарифицируется по тарифу вывода; используйте thinking_level, чтобы ограничить его и снизить стоимость.
Скидку для поля cache-hit (cachedContentTokenCount) см. в Тарификация кэша Gemini.
Полный справочник полей находится в разделе «Поля использования» в Руководстве по нативному формату Gemini.

Связанные ссылки

Та же группа: Gemini Native Format Guide · Multimodal & Code Execution · Function Calling
Соответствующий вариант в совместимом формате: OpenAI Compatible Mode: Handling Responses
Получение / управление token: https://api.apiyi.com/token

Основы

Базовый API

Image API (официальный)

Video API (официальный)

API мультимодального понимания

Текстовый API

Нативный формат Gemini: потоковые и непотоковые ответы

Ответ без потоковой передачи

Сигнатура мысли

Потоковый ответ (SSE)

Ключевые отличия от режима, совместимого с OpenAI

Использование и тарификация

Связанные ссылки

​Ответ без потоковой передачи

​Сигнатура мысли

​Потоковый ответ (SSE)

​Ключевые отличия от режима, совместимого с OpenAI

​Использование и тарификация

​Связанные ссылки

Ответ без потоковой передачи

Сигнатура мысли

Потоковый ответ (SSE)

Ключевые отличия от режима, совместимого с OpenAI

Использование и тарификация

Связанные ссылки