> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Gemini Chat Completion API 申请及使用
> Gemini AI 集成指南 - XHuoAPI
Google Gemini — это очень мощная AI система диалогов, которая может генерировать плавные и естественные ответы всего за несколько секунд, просто вводя подсказки. Gemini предоставляет удивительную интеллектуальную помощь, значительно повышая эффективность и креативность работы человека.
Этот документ в основном описывает процесс использования Gemini Chat Completion API, с помощью которого мы можем легко использовать функции диалога официального Gemini.
## 申请流程
Чтобы использовать Gemini Chat Completion API, сначала перейдите на страницу [Gemini Chat Completion API](https://api.xhuoapi.ai/documents/ae54bf9b-af41-4072-b969-3756b6d66834) и нажмите кнопку «Acquire», чтобы получить необходимые для запроса учетные данные:
Если вы еще не вошли в систему или не зарегистрированы, вас автоматически перенаправят на страницу входа, пригласив зарегистрироваться и войти. После входа или регистрации вы автоматически вернетесь на текущую страницу.
При первом запросе будет предоставлен бесплатный лимит, который позволяет бесплатно использовать этот API.
## 基本使用
Далее вы можете заполнить соответствующие поля на интерфейсе, как показано на рисунке:
При первом использовании этого интерфейса нам необходимо заполнить как минимум три поля: одно из них — это `authorization`, которое можно выбрать прямо из выпадающего списка. Другой параметр — это `model`, `model` — это категория модели, которую мы выбираем для использования с официального сайта Gemini, здесь у нас в основном есть 6 моделей, подробности можно посмотреть в предоставленных моделях. Последний параметр — это `messages`, `messages` — это массив наших вопросов, который представляет собой массив, позволяющий одновременно загружать несколько вопросов, каждый из которых содержит `role` и `content`, где `role` обозначает роль задающего вопрос, мы предоставили три идентичности: `user`, `assistant`, `system`. Другой `content` — это конкретное содержание нашего вопроса.
Также вы можете заметить, что справа есть соответствующий код вызова, который вы можете скопировать и запустить, или просто нажать кнопку «Try» для тестирования.
После вызова мы получаем следующий результат:
```json theme={null}
{
"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:
```python theme={null}
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)
```
Вывод будет следующим:
```json theme={null}
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]
```
Можно увидеть, что в ответе много `data`, `data` внутри `choices` является последним ответом, который соответствует ранее представленному содержимому. `choices` - это новая информация ответа, которую вы можете интегрировать в вашу систему. Также окончание потокового ответа определяется по содержимому `data`, если содержимое равно `[DONE]`, это означает, что потоковый ответ завершен. Возвращаемый результат `data` содержит несколько полей, описание которых приведено ниже:
* `id` - уникальный идентификатор для этой задачи диалога.
* `model` - выбранная модель Gemini.
* `choices` - информация о ответах Gemini на заданные вопросы.
JavaScript также поддерживается, например, код для потокового вызова Node.js приведен ниже:
```javascript theme={null}
const options = {
method: "post",
headers: {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
},
body: JSON.stringify({
"model": "gemini-2.5-pro",
"messages": [{"role":"user","content":"Привет, какая ты модель?"}],
"stream": true
})
};
fetch("https://api.xhuoapi.ai/v1/gemini/chat/completions", options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
Пример кода на Java:
```java theme={null}
JSONObject jsonObject = new JSONObject();
jsonObject.put("model", "gemini-2.5-pro");
jsonObject.put("messages", [{"role":"user","content":"Привет, какая ты модель?"}]);
jsonObject.put("stream", true);
MediaType mediaType = "application/json; charset=utf-8".toMediaType();
RequestBody body = jsonObject.toString().toRequestBody(mediaType);
Request request = new Request.Builder()
.url("https://api.xhuoapi.ai/v1/gemini/chat/completions")
.post(body)
.addHeader("accept", "application/json")
.addHeader("authorization", "Bearer {token}")
.addHeader("content-type", "application/json")
.build();
OkHttpClient client = new OkHttpClient();
Response response = client.newCall(request).execute();
System.out.print(response.body!!.string())
```
Другие языки можно адаптировать самостоятельно, принцип остается тем же.
## Многоуровневый диалог
Если вы хотите интегрировать функцию многоуровневого диалога, вам нужно загрузить несколько вопросов в поле `messages`, примеры нескольких вопросов приведены на изображении ниже:
Пример кода на Python:
```python theme={null}
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":"Привет"},{"role":"assistant","content":"Здравствуйте! Как я могу помочь вам сегодня?"},{"role":"user","content":"Какая ты модель?"}]
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
Загрузив несколько вопросов, вы можете легко реализовать многоуровневый диалог и получить следующий ответ:
```json theme={null}
{
"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 Мультимодальная модель
Пример запроса:
```json theme={null}
{
"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
}
```
Пример результата:
```json theme={null}
{
"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
}
}
```
Конечно, вы также можете передать ссылку на видео, конкретный ввод выглядит следующим образом:
```json theme={null}
{
"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
}
```
Пример результата:
```json theme={null}
{
"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`.
Пример запроса:
```json theme={null}
{
"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 также поддерживает понимание видео:
```json theme={null}
{
"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"
}
```
## Заключение
С помощью этого документа вы узнали, как использовать Gemini Chat Completion API для легкой реализации функций диалога официального Gemini. Надеемся, что этот документ поможет вам лучше интегрировать и использовать этот API. Если у вас есть какие-либо вопросы, пожалуйста, не стесняйтесь обращаться в нашу техническую поддержку.