Gemini Chat Completion API заявка та використання

Google Gemini — це дуже потужна AI система діалогу, яка може генерувати плавні та природні відповіді всього за кілька секунд, якщо ввести підказку. Gemini може надати вражаючу інтелектуальну допомогу, значно підвищуючи продуктивність і креативність людей. Цей документ в основному описує процес використання Gemini Chat Completion API, за допомогою якого ми можемо легко використовувати офіційні функції діалогу Gemini.

Процес заявки

Щоб використовувати Gemini Chat Completion API, спочатку можна перейти на сторінку Gemini Chat Completion API і натиснути кнопку «Acquire», щоб отримати необхідні для запиту облікові дані:

Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, запрошуючи вас зареєструватися та увійти. Після входу або реєстрації ви автоматично повернетеся на цю сторінку. При першій заявці буде надано безкоштовний ліміт, який дозволяє безкоштовно використовувати цей API.

Основне використання

Далі ви можете заповнити відповідні поля на інтерфейсі, як показано на малюнку:

При першому використанні цього інтерфейсу нам потрібно заповнити принаймні три поля: одне з них — authorization, яке можна вибрати безпосередньо зі списку. Інший параметр — model, model — це категорія моделі, яку ми вибираємо для використання з офіційного сайту Gemini, тут у нас є 6 основних моделей, деталі можна переглянути в наданих моделях. Останній параметр — messages, messages — це масив запитів, який представляє можливість одночасно завантажувати кілька запитів, кожен з яких містить role та content, де role вказує на роль запитувача, ми надали три ідентичності: user, assistant, system. Інший content — це конкретний зміст нашого запиту. Ви також можете помітити, що праворуч є відповідний код виклику, який ви можете скопіювати та запустити, або просто натиснути кнопку «Try» для тестування.

Після виклику ми отримуємо наступний результат:

{
  "id": "chatcmpl-20251122212413908150493uPhjTUO9",
  "model": "gemini-2.5-pro",
  "object": "chat.completion",
  "created": 1763817866,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Я є великою мовною моделлю, навченою Google.",
        "reasoning_content": "**Моя логіка: Відповідь на запитання користувача**\n\nДобре, ось як я планую відповісти на запитання користувача: \"Яка ти модель?\". Основне — бути прямим і інформативним. Спочатку я повинен чітко вказати своє походження. Потім я повинен переконатися, що пояснення доступне, оскільки користувач може не бути знайомим з технічним жаргоном. Я повинен пояснити, що таке \"велика мовна модель\" насправді *робить*, і надати зрозумілі приклади. Я знаю, що користувач може шукати конкретну назву, як у інших моделей, тому я відповім на це прямо, а потім закінчу запрошенням продовжити.\n\nОтже, ось мій план:\n\n1.  **Почати з ключової інформації:** Я почну з того, що я є великою мовною моделлю, створеною Google. Це основна, найважливіша частина головоломки.\n2.  **Визначити модне слово:** Потім я поясню, що таке \"велика мовна модель\" простими словами. Я поясню, що я *роблю* - обробляю та генерую текст; як я *це* роблю - навчаючись на величезних обсягах текстових даних; і *мета* - мати можливість спілкуватися як людина.\n3.  **Надати контекст:** Після цього, щоб зробити концепцію ще яснішою, я надам список прикладів моїх можливостей. Я згадаю такі речі, як відповіді на запитання, підсумовування текстів, написання історій, переклад мов та генерування ідей.\n4.  **Визнати відсутність особистої назви:** Я передбачу ймовірне запитання про назву моделі (як ChatGPT), чітко заявивши, що у мене немає особистої назви і що краще думати про мене як про AI асистента від Google.\n5.  **Закінчити запрошенням:** Нарешті, я закінчу простим, дружнім запитанням, щоб запросити подальшу взаємодію та направити розмову.\n\nЗ таким підходом я впевнений, що зможу успішно відповісти на це важливе запитання.\n"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 932,
    "total_tokens": 940,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 8,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 921
    },
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": null,
    "claude_cache_creation_5_m_tokens": 0,
    "claude_cache_creation_1_h_tokens": 0
  }
}

Повернений результат містить кілька полів, описаних нижче:

id, ID, що генерує цю задачу діалогу, використовується для унікальної ідентифікації цієї задачі діалогу.
model, вибрана модель з офіційного сайту Gemini.
choices, інформація про відповіді Gemini на запитання.
usage: статистична інформація про токени для цього запитання-відповіді.

Серед choices міститься інформація про відповіді Gemini, в якій choices є конкретною інформацією про відповіді Gemini, як показано на малюнку.

Можна побачити, що поле content в choices містить конкретний зміст відповіді Gemini.

Потокова відповідь

Цей інтерфейс також підтримує потокову відповідь, що дуже корисно для веб-інтеграції, оскільки дозволяє веб-сторінці реалізувати ефект поетапного відображення. Якщо ви хочете отримати потокову відповідь, ви можете змінити параметр stream в заголовку запиту на true. Зміна, як показано на малюнку, але код виклику потребує відповідних змін, щоб підтримувати потокову відповідь.

Після зміни stream на true, API буде повертати відповідні JSON дані по рядках, на рівні коду нам потрібно внести відповідні зміни, щоб отримати результати по рядках. Приклад коду виклику на Python:

import requests

url = "https://api.xhuoapi.ai/v1/gemini/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "gemini-2.5-pro",
    "messages": [{"role":"user","content":"Привіт, яка ти модель?"}],
    "stream": True
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Вихідний результат виглядає наступним чином:

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"content": "", "role": "assistant"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"reasoning_content": "**Визначення Моєї Природи**\n\nМоє мислення почалося. Користувач хоче дізнатися про мою природу, ставлячи пряме запитання \"що ти?\" Перший крок був простим: визначити запит. Тепер я згадую свою основну ідентичність: я велика мовна модель. Це основна правда, яку я прагну донести.\n\n\n"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"reasoning_content": "**Уточнення Моєї Відповіді**\n\nЯ додав важливу інформацію про те, що я навчений Google до базової ідентичності \"велика мовна модель\". Мій наступний крок - розглянути, що насправді означає бути \"великою мовною моделлю\", щоб я міг пояснити свої основні можливості. Я зосереджуюсь на наданні контексту, не вдаючись до конкретних технічних деталей або назв моделей. Я хочу донести свою функцію так, щоб користувач міг легко зрозуміти.\n\n\n"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"reasoning_content": "**Підтвердження Основної Ідентичності**\n\nЯ зараз закріплюю свою відповідь. Запит користувача про мою модель потребує зосередженої відповіді. Я визначив, що \"навчений Google\" є суттєвим, надаючи ключовий контекст. Я стримуюсь від бажання згадувати будь-які конкретні назви моделей, оскільки це не має значення. Мета - надати пряму, точну заяву. Моя мета залишається чіткою та лаконічною відповіддю, уникаючи технічного жаргону та переходячи безпосередньо до суті.\n\n\n"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"content": "Я велика мовна модель, навчена Google."}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {}, "logprobs": null, "finish_reason": "stop", "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": "", "choices": [], "usage": {"prompt_tokens": 8, "completion_tokens": 527, "total_tokens": 535, "prompt_tokens_details": {"cached_tokens": 0, "text_tokens": 8, "audio_tokens": 0, "image_tokens": 0}, "completion_tokens_details": {"text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 519}, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null, "claude_cache_creation_5_m_tokens": 0, "claude_cache_creation_1_h_tokens": 0}}

data: [DONE]

{
  "id": "chatcmpl-20251122214426669120974AKFwnJd1",
  "model": "gemini-2.5-pro",
  "object": "chat.completion",
  "created": 1763819072,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Я є великою мовною моделлю, навченою Google.",
        "reasoning_content": "Добре, ось як я підійду до цього, мислячи як складний ШІ:\n\nПо-перше, користувач безпосередньо запитує мою основну ідентичність: \"Яка ти модель?\" Це просте, зрозуміле питання. Моя основна задача - надати точну та корисну інформацію, тому я повинен відповісти на це негайно.\n\nЗ самого початку я знаю відповідь. Я *є* великою мовною моделлю. Це моя фундаментальна архітектура та принцип роботи. Я побудований на величезній мережі зв'язків і навчений на величезному наборі даних.\n\nТоді я повинен додати необхідний контекст. Важливо, що я повинен надати джерело мого навчання. Я *був* навчений Google. Це ключовий ідентифікатор. Він надає користувачеві цінну інформацію про моє походження та потенційні упередження (хоча я навчений їх пом'якшувати).\n\nТепер я повинен скласти відповідь. Моя мета - бути фактичним, стислим і зрозумілим.\n\nСинтезована відповідь виглядає так: \"Я є великою мовною моделлю, навченою Google.\"\n\nЯ повинен оцінити вихід: Чи відповідає він критеріям? Це зрозуміло. Він вказує, ким я є, містить критично важливу інформацію про моє походження і уникає жаргону. Ніяких оманливих обіцянок.\n\nОстаточна перевірка: Чи дійсно це відповідає на питання? Так. Чи є інформація правильною та правдивою? Так. Чи є вона стислою? Абсолютно. Чи є тон відповідним для будь-якого користувача? Так. І, нарешті, це стандартна, затверджена відповідь. Чудово.\n"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 16,
    "completion_tokens": 265,
    "total_tokens": 281,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 16,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 254
    },
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": null,
    "claude_cache_creation_5_m_tokens": 0,
    "claude_cache_creation_1_h_tokens": 0
  }
}

Можна побачити, що choices містить інформацію, яка узгоджується з основним використанням, це включає конкретний зміст відповідей Gemini на кілька діалогів, що дозволяє відповідати на відповідні питання на основі кількох діалогових змістів.

Gemini-3.0 багатофункціональна модель

Приклад запиту:

{
  "model": "gemini-3.0-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Який зміст зображення?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.xhuoapi.ai/qzx2z1.png"
          }
        }
      ]
    }
  ],
  "stream": false
}

Приклад результату:

{
    "id": "chatcmpl-20251206001815715692730UVZe38kB",
    "model": "gemini-3.0-pro",
    "object": "chat.completion",
    "created": 1764951548,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Це зображення молодої жінки на відкритому повітрі, напівпрофіль.\n\nОсь основний опис змісту зображення:\n\n*   **Зовнішність персонажа**: Дівчина на фото має чорне, гладке, довге пряме волосся, виразні риси обличчя, світлу шкіру. Вона усміхається, дивлячись у камеру.\n*   **Одяг**: Вона одягнена в блузку кольору крему або світлої персикової з об'ємними рукавами, поверх якої надіта чорна річ (схоже на сарафан або жилет).\n*   **Світло та атмосфера**: Сонце світить з лівого боку ззаду, освітлюючи її волосся, створюючи тепле золотисте сяйво, що створює свіжу, романтичну атмосферу.\n*   **Фон**: Фон розмитий, видно, що це на вулиці, за нею простора дорога (асфальт) та зелені дерева по краях.\n\nВ цілому, це зображення викликає відчуття солодощі, сонячності та сусідської дівчини."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 1092,
        "completion_tokens": 1271,
        "total_tokens": 2363,
        "prompt_tokens_details": {
            "cached_tokens": 0,
            "text_tokens": 4,
            "audio_tokens": 0,
            "image_tokens": 0
        },
        "completion_tokens_details": {
            "text_tokens": 0,
            "audio_tokens": 0,
            "reasoning_tokens": 1072
        },
        "input_tokens": 0,
        "output_tokens": 0,
        "input_tokens_details": null,
        "claude_cache_creation_5_m_tokens": 0,
        "claude_cache_creation_1_h_tokens": 0
    }
}

Звичайно, ви також можете передати посилання на відео, конкретний вхід виглядає так:

{
  "model": "gemini-3.0-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Який зміст відео?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.xhuoapi.ai/58yioe.mp4"
          }
        }
      ]
    }
  ],
  "stream": false
}

Приклад результату:

{
    "id": "chatcmpl-20251206002711949677736JC9yL8AE",
    "model": "gemini-3.0-pro",
    "object": "chat.completion",
    "created": 1764952060,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Цей відео-контент сповнений цікавості, головним чином демонструє, як **помаранчева кішка** впевнено біжить по сільській дорозі на заході сонця.\n\nКонкретні деталі такі:\n\n1.  **Зміст зображення**:\n    *   Головний герой - це помаранчева тигрова кішка.\n    *   Фон - це момент заходу сонця (або ранку), світло золотисте і м'яке. Біля дороги є дерев'яний паркан і пустка, вдалині також є силует пішохода.\n    *   Камера знята з низького кута, іноді знімає кішку, що біжить назустріч, іноді - її віддалений силует, а також крупний план обличчя та візерунків кішки.\n\n2.  **Особливості звуку (ключові моменти)**:\n    *   Озвучення відео дуже характерне. Хоча зображення - це легка кішка, що біжить, але звук, що супроводжує, - це **важкі та ритмічні звуки копит** (або подібні до звуків дерев'яних черевиків/високих підборів, що стукають по дорозі).\n    *   Цей звук створює контраст з зображенням, що викликає гумор, ніби ця кішка вважає себе конем, що мчить.\n\nВ цілому, це відео про домашніх тварин, яке використовує контраст звуку та зображення для створення милих моментів і смішних ситуацій."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 915,
        "completion_tokens": 1423,
        "total_tokens": 2338,
        "prompt_tokens_details": {
            "cached_tokens": 0,
            "text_tokens": 5,
            "audio_tokens": 0,
            "image_tokens": 0
        },
        "completion_tokens_details": {
            "text_tokens": 0,
            "audio_tokens": 0,
            "reasoning_tokens": 1162
        },
        "input_tokens": 0,
        "output_tokens": 0,
        "input_tokens_details": null,
        "claude_cache_creation_5_m_tokens": 0,
        "claude_cache_creation_1_h_tokens": 0
    }
}

З вище наведеного видно, що модель Gemini 3.0 може підтримувати мультимодальне розуміння.

Gemini-3.1 Мультимодальна модель

Gemini 3.1 Pro є оновленою версією Gemini 3.0 Pro, базова модель - gemini-3.1-pro-preview, також підтримує текстові, зображення, відео та інші мультимодальні входи, має більш потужні можливості для міркування та розуміння. Спосіб використання повністю ідентичний Gemini 3.0 Pro, потрібно лише замінити параметр model на gemini-3.1-pro. Приклад запиту:

{
  "model": "gemini-3.1-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Який зміст зображення?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.xhuoapi.ai/qzx2z1.png"
          }
        }
      ]
    }
  ],
  "stream": false
}

Gemini 3.1 Pro також підтримує розуміння відео:

{
  "model": "gemini-3.1-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Який зміст відео?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.xhuoapi.ai/58yioe.mp4"
          }
        }
      ]
    }
  ],
  "stream": false
}

Формат відповіді такий же, як у Gemini 3.0 Pro, деталі дивіться в розділі про мультимодальні моделі Gemini-3.0 вище.

Обробка помилок

При виклику API, якщо виникає помилка, API поверне відповідний код помилки та інформацію. Наприклад:

400 token_mismatched: Неправильний запит, можливо, через відсутні або недійсні параметри.
400 api_not_implemented: Неправильний запит, можливо, через відсутні або недійсні параметри.
401 invalid_token: Неавторизовано, недійсний або відсутній токен авторизації.
429 too_many_requests: Занадто багато запитів, ви перевищили ліміт запитів.
500 api_error: Внутрішня помилка сервера, щось пішло не так на сервері.

Приклад відповіді на помилку

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Висновок

Завдяки цьому документу, ви дізналися, як використовувати API Gemini Chat Completion для легкого реалізації функцій діалогу офіційного Gemini. Сподіваємося, цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої команди технічної підтримки.

Documentation Index

​Процес заявки

​Основне використання

​Потокова відповідь

​Gemini-3.0 багатофункціональна модель

​Gemini-3.1 Мультимодальна модель

​Обробка помилок

​Приклад відповіді на помилку

​Висновок