Как подключить API GPTunnel: ключ, base_url и первый запрос

Как подключить API GPTunnel: ключ, base_url и первый запрос — это три шага. Ключ генерируется во вкладке API личного кабинета, в персональном и бизнес-профиле. Запрос уходит методом POST на https://gptunnel.ru/v1/chat/completions с заголовком Authorization. В теле передаются model и messages. Ниже — порядок действий, три готовых примера и разбор ответа.

Где взять ключ и что он умеет

Ключ создаётся во вкладке API личного кабинета. Документация GPTunnel в разделе «С чего начать?» описывает это одинаково для персонального и бизнес-профиля: отдельной процедуры для бизнес-аккаунта нет, отличается только счёт, с которого списываются средства.

При создании или редактировании ключа задаётся список доступных ему моделей. Это главный рычаг контроля: ключ для бэкенда можно сузить до одной-двух моделей, а ключ для экспериментов оставить открытым. Если список пуст, ключу доступны все модели. Ограничение действует на всё публичное API, включая озвучку (tts2), замену лица (faceswap) и транскрибацию (whisper) — эти модели тоже выбираются в списке.

Практический порядок:

1. Откройте личный кабинет и перейдите во вкладку API.
2. Сгенерируйте ключ, дайте ему понятное имя по задаче.
3. Отметьте модели, которые этому ключу разрешены.
4. Скопируйте значение ключа и сохраните его в переменную окружения проекта.
5. Отправьте тестовый запрос на chat/completions.

Шаг 4 стоит делать сразу: ключ в коде создаёт риск утечки. Держите его в переменной окружения или в секрете CI, а в репозиторий кладите только имя переменной.

Ограничение по моделям работает и как защита от ошибки в коде. Если в конфиге остался идентификатор модели от другого проекта, запрос к ней отклонится, и вы увидите это на тесте.

Ограничение ключа по моделям и ошибка 403

Запрос к модели, которой нет в списке ключа, отклоняется с HTTP 403 и кодом model_not_allowed. Это ответ на уровне авторизации: ключ валиден, но конкретная модель ему не разрешена. В каталогах такой ключ видит только разрешённые модели, поэтому список в интерфейсе и список в ответе на запрос совпадают.

Различайте два случая. Первый — ключ не разрешает модель, ответ 403 с model_not_allowed. Второй — модель разрешена, но в запросе опечатка в идентификаторе; тогда проверяйте написание по списку моделей в документации. Оба случая лечатся правкой списка разрешений или идентификатора.

Ограничение распространяется на всё публичное API. Если ключ используется и для чата, и для транскрибации, отмечайте обе модели сразу — иначе второй сценарий отвалится с 403 уже после запуска.

Диагностику входа в аккаунт и связанные с ней коды разбирает отдельная инструкция по входу; к chat/completions эти коды не относятся, и переносить их в разбор ответа модели не нужно.

Адрес, заголовок и обязательные поля

Полный адрес HTTP-метода — https://gptunnel.ru/v1/chat/completions, метод POST. В заголовках обязателен Authorization со значением ключа. Второй заголовок, Content-Type: application/json, нужен, чтобы тело запроса разобралось как JSON.

В теле два обязательных поля:

messages — массив объектов с ролями. Роль system задаёт вводную, роль user — реплику пользователя. Порядок ролей в массиве задаёт контекст диалога, поэтому system ставят первой.

В учебном запросе используем system и user. Так вы сразу увидите, что модель учитывает вводную: в примере ниже system сообщает имя, а user спрашивает, как зовут собеседника.

Первый запрос через curl

Здесь приведён полный URL HTTP-метода для прямого запроса. Параметр base_url сторонней библиотеки настраивается по её собственному контракту: если она добавляет путь метода сама, полный адрес из curl нельзя переносить туда без проверки.

Самый быстрый способ проверить ключ — curl из терминала. Он не требует установки библиотек и показывает сырой ответ.

curl -X POST https://gptunnel.ru/v1/chat/completions \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "My name is Robert."},
      {"role": "user", "content": "Как тебя зовут?"}
    ]
  }'

Замените YOUR_API_KEY на значение из вкладки API. Если ответ пришёл с HTTP 403 и кодом model_not_allowed, вернитесь к списку моделей ключа и добавьте gpt-4o. Если ответ 200, ключ, адрес и тело запроса собраны верно.

Для теста на персональном счёте добавьте в тело параметр useWalletBalance — документация GPTunnel описывает его как способ списывать средства с персонального счёта при тестировании API. Для production рекомендуется бизнес-счёт.

Первый запрос через Python (requests)

Тот же запрос на Python занимает несколько строк. Библиотека requests уже стоит в большинстве окружений; если нет, установите её в виртуальное окружение проекта.

import requests

response = requests.post(
    'https://gptunnel.ru/v1/chat/completions',
    headers={'Authorization': 'YOUR_API_KEY'},
    json={
        'model': 'gpt-4o',
        'messages': [
            {'role': 'system', 'content': 'My name is Robert.'},
            {'role': 'user', 'content': 'Как тебя зовут?'},
        ],
    },
)
print(response.json())

Ключ держите в переменной окружения и подставляйте её в заголовок: os.environ['GPTUNNEL_API_KEY']. Так значение хранится вне исходного кода; отдельно следите за тем, какие данные записывает ваше приложение. Для теста на персональном счёте добавьте в json-тело 'useWalletBalance': True.

Проверка результата: в ответе должно быть поле choices с непустым message.content. Если content пуст, посмотрите finish_reason — он объясняет, почему генерация остановилась.

Первый запрос через Node.js (axios)

В Node.js удобен axios: он сам сериализует тело в JSON и разбирает ответ.

import axios from 'axios'

const response = await axios({
  method: 'POST',
  url: 'https://gptunnel.ru/v1/chat/completions',
  headers: {
    Authorization: 'YOUR_API_KEY',
  },
  data: {
    model: 'gpt-4o',
    messages: [
      { role: 'system', content: 'My name is Robert.' },
      { role: 'user', content: 'Как тебя зовут?' },
    ],
  },
})
console.log(response.data)

Ключ берите из process.env. Обработку ошибок стройте по HTTP-статусу: 403 с model_not_allowed — это список моделей ключа, остальные коды смотрите в справочнике ошибок документации.

Все три примера отправляют одно и то же тело. Разница только в среде выполнения, поэтому переносите между ними модель и messages без изменений.

Разбор ответа: choices и usage

Ответ приходит в OpenAI-совместимом формате. Текст модели лежит в choices[].message.content: это массив, потому что запрос может вернуть несколько вариантов. В базовом случае вариант один, с index 0 и finish_reason stop.

Второй блок — usage. В нём prompt_tokens, completion_tokens и total_tokens: токены запроса, токены ответа и их сумма. Рядом идут prompt_cost, completion_cost и total_cost — стоимость частей запроса и итоговая. Эти поля дают точный расход по каждому вызову, поэтому логируйте usage вместе с запросом: по нему видно, какие промпты съедают бюджет.

Сверяйте total_tokens с ожиданием: если число растёт от запроса к запросу, в messages накапливается история, и её пора обрезать или суммировать.

Тестовый и рабочий счёт

Документация GPTunnel разводит два режима. Для тестирования API используется персональный счёт: в запрос передаётся параметр useWalletBalance. Для production рекомендуется бизнес-счёт.

Практический смысл разделения — в учёте. Тестовые прогоны на персональном счёте не смешиваются с рабочим бюджетом, а расход по production виден отдельно. Переход на бизнес-счёт не меняет ни адрес, ни заголовки, ни тело запроса: меняется счёт, с которого списываются средства.

Порядок для нового проекта: сначала прогоните первый запрос на персональном счёте с useWalletBalance, убедитесь, что ответ и usage приходят, затем перенесите тот же код на бизнес-счёт и уберите параметр.

Частые вопросы

Где сгенерировать API-ключ GPTunnel?
Во вкладке API личного кабинета. Документация GPTunnel в разделе «С чего начать?» описывает генерацию одинаково для персонального и бизнес-профиля. Там же при создании или редактировании ключа задаётся список разрешённых моделей.

Какой base_url использовать для запросов?
Адрес метода — https://gptunnel.ru/v1/chat/completions, запрос отправляется методом POST. В заголовках обязателен Authorization со значением ключа. Тело запроса содержит model и messages.

Что означает ошибка model_not_allowed?
Это ответ HTTP 403 на запрос к модели, которой нет в списке ключа. Такой ключ видит в каталогах только разрешённые модели. Добавьте нужную модель в список ключа или используйте другую.

Как протестировать API на персональном счёте?
Передайте в запросе параметр useWalletBalance — документация GPTunnel описывает его для тестирования на персональном счёте. Для production рекомендуется бизнес-счёт. Адрес, заголовки и тело запроса при этом не меняются.

Что смотреть в ответе модели?
Текст лежит в choices[].message.content, причина остановки — в finish_reason. Блок usage содержит prompt_tokens, completion_tokens, total_tokens и стоимость запроса. Эти поля логируйте вместе с запросом, чтобы видеть расход.

Первоисточник по всем шагам — документация GPTunnel, раздел «С чего начать?»: https://docs.gptunnel.ru/