Interactions API против generateContent

​

Что собой представляют два подхода

​

Основные различия вкратце

​

Структуры запроса и ответа (один текстовый ход)

curl -X POST "https://api.apiyi.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Authorization: Bearer $APIYI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{ "text": "Tell me a joke." }]
    }]
  }'

curl -X POST "https://generativelanguage.googleapis.com/v1beta2/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-flash",
    "input": "Tell me a joke."
  }'

{
  "candidates": [
    {
      "content": {
        "parts": [{ "text": "Why did the chicken cross the road? ..." }],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 4,
    "candidatesTokenCount": 12,
    "totalTokenCount": 16
  }
}

{
  "id": "int_123",
  "status": "completed",
  "steps": [
    {
      "type": "user_input",
      "status": "done",
      "content": [{ "type": "text", "text": "Tell me a joke." }]
    },
    {
      "type": "model_output",
      "status": "done",
      "content": [{ "type": "text", "text": "Why did the chicken cross the road?" }]
    }
  ]
}

​

Сравнение многоходовых диалогов

curl -X POST "https://api.apiyi.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Authorization: Bearer $APIYI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      { "role": "user",  "parts": [{ "text": "Hi, my name is Phil." }] },
      { "role": "model", "parts": [{ "text": "Hello Phil! How can I help?" }] },
      { "role": "user",  "parts": [{ "text": "What is my name?" }] }
    ]
  }'

curl -X POST "https://generativelanguage.googleapis.com/v1beta2/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-flash",
    "previous_interaction_id": "int_123",
    "input": "What is my name?"
  }'

​

Различия для моделей изображений

• generateContent (текущий формат шлюза APIYI): промежуточные черновики рассуждения возвращаются как обычные image parts внутри candidates[0].content.parts (с thoughtSignature, без флага thought). В тестах один ответ может содержать 2–10 изображений, каждое тарифицируется по 1120/2000 tokens в выходных данных — всегда проходите по всем parts и берете последнее как финальную версию. Полные измерения и правила сверки: Usage Fields & Output Explained.
• Interactions API: рассуждение явно представлено как шаги type: "thought" (текст мысли и промежуточные изображения), а финальное изображение находится в шаге model_output; SDK также предоставляют удобные свойства .output_image / .output_text. Для чередующегося текстово-изображенческого вывода (например, иллюстрированных историй) по-прежнему требуется вручную проходить по шагам.

​

Тест совместимости шлюза APIYI

​

Рекомендации

1. Через APIYI: продолжайте использовать generateContent. Он обладает самым полным набором функций (Batch, явное кэширование и video_metadata доступны только в generateContent), и Google взял на себя обязательство полностью поддерживать его — в ближайшей перспективе риска вывода из эксплуатации нет.
2. Многоходовые диалоги с generateContent: собирайте историю на стороне клиента; см. Нативный формат Gemini и Многоходовые диалоги.
3. Если вы вызываете Google напрямую и рассматриваете миграцию на Interactions API, обратите внимание на четыре вещи: tools / system_instruction / generation_config нужно пересылать на каждом ходе; store по умолчанию включён и хранится 55 дней на платном тарифе; Batch API и явное кэширование пока недоступны; обновите google-genai / @google/genai до версии 2.3.0+.
4. Когда Interactions API стоит начинать отслеживать: когда вам нужны официальные агенты (Deep Research, Antigravity), background: true длительно выполняющиеся задачи или серверное состояние, чтобы снизить расходы на token в многоходовых диалогах. Мы обновим эту страницу, как только APIYI добавит поддержку.

​

Связанные документы