О шлюзе для ИИ можно узнать больше из одной команды в терминале, чем из длинного списка возможностей. Если шлюз действительно совместим с OpenAI, одна и та же команда curl должна работать для поддерживаемых семейств моделей, при этом базовый URL, заголовок авторизации, формат сообщений и разбор ответа остаются неизменными.
В этом руководстве показан практический подход с Flatkey: начните с одного запроса chat-completions, вынесите имя модели в переменную и протестируйте несколько актуальных семейств моделей, не переписывая интеграцию. Материал предназначен для разработчиков, которые хотят проверить API из терминала, прежде чем подключать SDK или вносить код в приложение.
Примечание о выборе модели: Каталоги моделей меняются. Идентификаторы моделей ниже соответствуют общедоступной документации Flatkey, проверенной 24 июля 2026 года. Перед использованием ID в production подтвердите актуальную строку модели и доступность.
Кратчайший рабочий запрос cURL для chat-completions
Создайте API-ключ Flatkey, экспортируйте его в оболочку и отправьте запрос к совместимому с OpenAI endpoint для chat-completions:
export FLATKEY_API_KEY="your-flatkey-api-key"
curl https://router.flatkey.ai/v1/chat/completions \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [
{
"role": "user",
"content": "Write a one-sentence product description for a waterproof daypack."
}
]
}'
Важны четыре части:
| Часть запроса | Что остается неизменным |
|---|---|
| Базовый URL | https://router.flatkey.ai/v1 |
| Endpoint | /chat/completions |
| Аутентификация | Authorization: Bearer $FLATKEY_API_KEY |
| Формат сообщений | Массив объектов с полями role и content |
Для совместимых chat-моделей основной параметр, который вы меняете, — model.
Используйте одинаковую структуру cURL для разных семейств моделей
Поместите идентификатор модели в переменную оболочки, чтобы не нужно было менять тело запроса:
export FLATKEY_API_KEY="your-flatkey-api-key"
export MODEL="gpt-4o-mini"
curl -sS https://router.flatkey.ai/v1/chat/completions \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"model\": \"$MODEL\",
\"messages\": [
{
\"role\": \"system\",
\"content\": \"Return concise ecommerce copy.\"
},
{
\"role\": \"user\",
\"content\": \"Write a product title for a lightweight waterproof daypack.\"
}
],
\"temperature\": 0.2
}" | jq -r '.choices[0].message.content'
Теперь повторно запустите команду с другим задокументированным ID модели:
export MODEL="claude-sonnet-4-6"
export MODEL="gemini-2.5-flash"
export MODEL="deepseek-v3.1"
Запрос по-прежнему использует тот же endpoint, те же заголовки, сообщения и парсер jq. Именно эта стабильная форма вызова и дает операционное преимущество: вы можете сравнивать поддерживаемые семейства моделей, не поддерживая отдельный терминальный скрипт для каждого провайдера.
Примечание о выборе модели: Общая форма запроса не означает, что каждая модель ведет себя одинаково. Поддерживаемые параметры, ограничения контекста, поведение инструментов, поведение в части безопасности, задержка и стиль вывода могут различаться. Рассматривайте совместимость как более простую поверхность интеграции, а не как доказательство того, что модели взаимозаменяемы.
Запустите небольшой цикл тестирования нескольких моделей
Для быстрого сравнения в терминале задайте короткий список и отправьте каждой модели один и тот же запрос:
#!/usr/bin/env bash
set -euo pipefail
: "${FLATKEY_API_KEY:?Сначала задайте FLATKEY_API_KEY}"
MODELS=(
"gpt-4o-mini"
"claude-sonnet-4-6"
"gemini-2.5-flash"
"deepseek-v3.1"
)
PROMPT="Write three benefit-led bullet points for a waterproof commuter backpack."
for MODEL in "${MODELS[@]}"; do
echo
echo "=== $MODEL ==="
jq -n \
--arg model "$MODEL" \
--arg prompt "$PROMPT" \
'{
model: $model,
messages: [
{role: "system", content: "You write concise ecommerce copy."},
{role: "user", content: $prompt}
],
temperature: 0.2
}' |
curl -sS https://router.flatkey.ai/v1/chat/completions \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @- |
jq -r '.choices[0].message.content // .error.message'
done
Использование jq -n для построения JSON безопаснее, чем ручное экранирование длинной shell-строки. Это также упрощает расширение скрипта переменными, дополнительными сообщениями или необязательными параметрами.
Сохраните скрипт как compare-models.sh, сделайте его исполняемым и запустите:
chmod +x compare-models.sh
./compare-models.sh
Что сравнивать в выводе
Тестирование нескольких моделей полезно только тогда, когда запрос и метод оценки остаются неизменными. Для задачи написания ecommerce-копирайта сравнивайте:
| Dimension | Terminal-friendly check |
|---|---|
| Instruction following | Вывод вернул ровно три пункта? |
| Format stability | Можно ли разобрать ответ без особых случаев? |
| Brand fit | Тон специфичен, убедителен и не содержит неподтвержденных утверждений? |
| Latency | Сколько времени занял запрос? |
| Token usage | Что ответ сообщил в своем объекте usage? |
| Error behavior | Возвращает ли неудачный запрос полезное сообщение об ошибке? |
Добавьте поля тайминга cURL, когда важна задержка:
curl -sS -o response.json \
-w 'status=%{http_code} total=%{time_total}s\n' \
https://router.flatkey.ai/v1/chat/completions \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-2.5-flash",
"messages": [
{"role": "user", "content": "Напишите продуктовый слоган из пяти слов."}
]
}'
jq . response.json
Это разделяет измерения транспортного уровня и вывод модели. Терминал выводит HTTP-статус и общее время запроса, а JSON-ответ остаётся доступным для просмотра.
Примечание по выбору модели: Не выбирайте production-модель по одному ответу. Запустите репрезентативный набор запросов, повторите обращения и оцените результаты по требованиям, важным для вашего приложения.
Сделайте запрос сопоставимым
Небольшие изменения промпта или параметров могут сделать тест модели вводящим в заблуждение. Используйте следующие настройки:
- Оставляйте сообщения идентичными. Не улучшайте промпт для одной модели и не оставляйте его без изменений для остальных.
- Используйте одинаковую temperature. Более низкие значения обычно упрощают анализ сравнительных запусков.
- Сохраняйте сырой JSON. Храните полный ответ, а не только отрендеренный текст.
- Записывайте ID модели. Отображаемого имени недостаточно для воспроизводимых тестов.
- Отделяйте ошибки от плохих ответов. Ошибка транспорта или доступности не является оценкой качества вывода.
- Проверяйте текущую доступность. Указанная в документации модель всё равно может менять операционный статус.
Добавьте базовую обработку сбоев
Используйте --fail-with-body, чтобы cURL завершался при HTTP-ошибках, сохраняя тело ответа:
HTTP_BODY=$(mktemp)
if ! curl --fail-with-body -sS \
-o "$HTTP_BODY" \
https://router.flatkey.ai/v1/chat/completions \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [
{"role": "user", "content": "Верните слово ready."}
]
}'; then
jq -r '.error.message // "Request failed"' "$HTTP_BODY" >&2
rm -f "$HTTP_BODY"
exit 1
fi
jq -r '.choices[0].message.content' "$HTTP_BODY"
rm -f "$HTTP_BODY"
В прикладном коде также добавьте явные таймауты, ограниченные повторы для ошибок, допускающих повторную попытку, и логирование, которое не раскрывает секретные ключи или чувствительное содержимое промпта.
Практическая политика выбора модели
Самая простая политика — выбирать по типу нагрузки, а не по имени провайдера:
| Нагрузка | Первый тест | Что проверить перед внедрением |
|---|---|---|
| Большие объемы простого копирайта | Быстрая и экономичная модель | Соответствие формату и приемлемый уровень ошибок |
| Тонкий брендовый текст | Более сильная универсальная модель | Тон, фактическая сдержанность и частота правок |
| Синтез длинного контекста | Модель с подходящей поддержкой контекста | Качество извлечения и поведение при усечении |
| Интерфейс, чувствительный к задержке | Модель с низкой задержкой | Хвостовая задержка, а не только один быстрый запрос |
| Путь резервного перехода | Модель из другой семейства | Совместимость параметров и контракт вывода |
Начните с самой маленькой модели, которая надежно проходит ваш порог качества. Переходите к более сильной модели, когда задача этого требует. Если вы добавляете резервную маршрутизацию, тестируйте резервный вариант с тем же контрактом ответа, а не исходите из того, что он может заменить основную модель без изменений в приложении.
Перед выбором ID для производственного теста вы можете ознакомиться с текущим доступом к моделям и ценами на странице цен Flatkey.
Когда переходить от cURL к SDK
cURL идеально подходит, чтобы быстро проверить четыре вещи:
- API-ключ работает
- базовый URL указан верно
- выбранная модель принимает запрос
- форма ответа соответствует вашему парсеру
Переходите к SDK, когда вам нужны помощники для потоковой передачи, структурированная логика повторных попыток, типизированные ответы, переиспользуемые клиенты или наблюдаемость на уровне приложения. Сохраните успешный cURL-запрос в вашем рабочем регламенте: это по-прежнему самый быстрый способ отделить проблемы доступа через шлюз от проблем конфигурации SDK.
Итоговый чек-лист реализации
- Экспортируйте API-ключ, а не помещайте его напрямую в скрипты.
- Используйте
https://router.flatkey.ai/v1в качестве базового URL. - Отправляйте совместимые chat-запросы на
/chat/completions. - Перенесите ID модели в конфигурацию.
- Создавайте JSON с помощью
jq, когда экранирование в shell становится сложным. - Сохраняйте HTTP-статус, задержку, содержимое ответа и данные об использовании.
- Сравнивайте модели с идентичными промптами и параметрами.
- Перед запуском в продакшн проверяйте актуальную доступность каталога.
- Добавьте таймауты, ограниченные повторные попытки и безопасное для секретов логирование в коде приложения.
Один стабильный cURL-запрос дает вам чистую отправную точку. Когда он работает, изменение поля model превращает этот запрос в практический тестовый стенд для нескольких семейств AI-моделей — без необходимости каждый раз менять аутентификацию, базовый URL или парсер ответа.
Часто задаваемые вопросы
Могу ли я использовать один и тот же cURL-запрос chat-completions для каждой AI-модели?
Используйте его для моделей, которые Flatkey предоставляет через совместимый маршрут chat-completions. Для других модальностей или особенностей, зависящих от протокола, могут потребоваться другие конечные точки или поля запроса.
Каков минимальный набор полей для запроса chat-completions?
Для базового запроса укажите поддерживаемый model и массив messages. Также нужны заголовок авторизации bearer и тип содержимого JSON.
Зачем помещать имя модели в переменную окружения?
Это сохраняет стабильную структуру запроса, уменьшает количество ошибок при редактировании и упрощает запуск скриптов в средах staging, evaluation и production.
Стоит ли использовать cURL в production?
cURL отлично подходит для проверки, скриптов и runbooks. Для большинства production-приложений больше подходит SDK или HTTP-клиент с явной поддержкой тайм-аутов, повторных попыток, телеметрии и обработки типов.
Как выбрать между моделями GPT, Claude, Gemini и DeepSeek?
Выбирайте на основе репрезентативного набора для оценки. Сравнивайте следование инструкциям, качество вывода, задержку, расход токенов, поведение при ошибках и конкретные возможности, которые требуются вашей рабочей нагрузке. Перед развёртыванием подтвердите текущую доступность.
