Heli
Создать аккаунт

Отладка Heli API через curl: ключ, модель, ошибки и стриминг

Когда интеграция с Heli не работает, сначала уберите из уравнения SDK, фреймворк и IDE. curl показывает сырой HTTP-ответ: статус, заголовки и JSON ошибки. Если запрос через curl проходит, проблема в настройках вашего инструмента, а не в ключе или модели. Ключ передавайте через переменную окружения, чтобы он не остался в истории команд.

1. Проверка ключа

Статус 200 и JSON со списком моделей — ключ рабочий. Флаг -i показывает статус и заголовки ответа. Статус 401 — ключ неверный, отозван или передан не полностью.

javascript
export HELI_API_KEY="sk-heli-…"

curl -sS -i https://getheli.ru/v1/models \
  -H "Authorization: Bearer $HELI_API_KEY"

2. Тестовый запрос к модели

curl
curl -sS https://getheli.ru/v1/chat/completions \
  -H "Authorization: Bearer $HELI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-5.4-mini","messages":[{"role":"user","content":"ping"}],"max_tokens":20}'

# стриминг: -N отключает буферизацию curl
curl -sS -N https://getheli.ru/v1/chat/completions \
  -H "Authorization: Bearer $HELI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-5.4-mini","stream":true,"messages":[{"role":"user","content":"Сосчитай до пяти"}]}'

# время до первого байта и общее время
curl -sS -o /dev/null -w "%{http_code} ttfb=%{time_starttransfer}s total=%{time_total}s\n" ...

Как читать ответ

  • 401 authentication_error — ключ. Проверьте его во вкладке «Ключи».
  • 402 insufficient_balance — закончился баланс.
  • 429 — лимит запросов или бюджет; смотрите code и заголовок Retry-After.
  • 400 model_denied — модель запрещена политикой ключа.
  • 502 — ошибка на стороне модели, в том числе неверный слаг model; читайте message.
  • 504 — модель не ответила вовремя; попробуйте stream или меньший max_tokens.

Ошибка 401

Ошибка 429

Ошибка invalid model

Ошибки 500, 502 и 504

Windows и частые ловушки

  • В PowerShell curl может оказаться псевдонимом Invoke-WebRequest. Вызывайте curl.exe явно.
  • Одинарные кавычки вокруг JSON не работают в cmd.exe. Сохраните тело в файл body.json и передайте его как -d @body.json.
  • Адрес без /v1 возвращает 404 — в base URL всегда нужен /v1.
  • Не вставляйте полный ключ в чаты и тикеты поддержки: достаточно времени запроса, модели, статуса и текста ошибки.

Документация API

Проверяйте из того же окружения

Запускайте curl на том же сервере или в том же контейнере, где работает приложение. Так видны сетевые проблемы, которых нет на вашем ноутбуке: исходящий трафик закрыт файрволом, запросы идут через корпоративный прокси из переменной HTTPS_PROXY, в минимальном Docker-образе нет корневых сертификатов и TLS-соединение не устанавливается. Флаг -v покажет, на каком шаге всё ломается: DNS, подключение, TLS-рукопожатие или уже HTTP-ответ.

Если curl из контейнера работает, а SDK в том же контейнере — нет, сравните адрес, заголовок Authorization и тело запроса: обычно отличается base URL или имя модели.

Попробуйте Heli

Ключ sk-heli- появляется после подтверждения почты. Через Google и Яндекс — сразу в кабинете.

Создать аккаунтВойти

Документация API · Модели и цены

Читайте также