Flatkey API Quickstart: Сделайте свой первый запрос через router.flatkey.ai

Если вы уже используете OpenAI SDK, самый короткий путь к первому запросу к Flatkey API прост: создайте ключ Flatkey, укажите в клиенте https://router.flatkey.ai/v1, отправьте один запрос chat-completions и проверьте вызов в консоли.

Это краткое руководство проведет вас через весь этот цикл. Оно также показывает, как добавить базовую последовательность fallback после того, как заработает первая модель, не скрывая ошибки и не создавая бесконечную цепочку повторных попыток.

Что вы выполните

К концу этого руководства у вас будет:

1. Аккаунт Flatkey и API-ключ.
2. Клиент, совместимый с OpenAI, использующий роутер Flatkey.
3. Один успешный запрос и читаемый ответ.
4. Контрольная точка в консоли для использования, стоимости и устранения неполадок запроса.
5. Небольшой шаблон fallback, который можно протестировать перед продакшеном.

Для этого smoke-теста вам не нужно перестраивать приложение вокруг нового SDK. В публичной документации Flatkey описан endpoint, совместимый с OpenAI, по адресу https://router.flatkey.ai/v1, поэтому распространенные сценарии chat, tool, streaming и structured-output могут сохранять привычный вид клиента.

Перед началом

Вам потребуется:

• Аккаунт Flatkey.
• API-ключ Flatkey, начинающийся с sk-fk-.
• Python 3.9+ или Node.js 18+, если вы хотите использовать пример SDK.
• Имя модели, которое в настоящее время доступно для вашего аккаунта.

Каталоги моделей и доступность могут меняться. Используйте текущий каталог моделей или консоль, а не копируйте старое имя модели в продакшен.

Шаг 1: Создайте аккаунт Flatkey

Откройте процесс регистрации Flatkey и создайте аккаунт. После входа используйте консоль, чтобы создать учетные данные, которые ваше приложение будет отправлять с каждым запросом.

Справка по консоли

Перейдите в Console → API Keys.

Создайте ключ для этого quickstart и сразу же скопируйте его. Относитесь к ключу как к паролю: не вставляйте его в клиентский код, не коммитьте в Git, не включайте в скриншоты и не отправляйте в обращениях в поддержку.

Для командной среды создавайте отдельные ключи для разных разработчиков или сервисов. В документации Flatkey также описаны настройки на уровне ключа, такие как месячный лимит и необязательный allowlist моделей. Эти настройки упрощают изоляцию теста, ротацию одних учетных данных или остановку одной рабочей нагрузки без влияния на все приложения.

Установите ключ в своей оболочке:

export FLATKEY_API_KEY="sk-fk-your-key-here"

Если вы используете файл .env, держите его вне системы контроля версий:

FLATKEY_API_KEY=sk-fk-your-key-here

Шаг 2: Измените базовый URL

Базовый URL Flatkey, совместимый с OpenAI, такой:

https://router.flatkey.ai/v1

Это самое важное изменение конфигурации в quickstart. Ваш API-ключ аутентифицирует запрос, а базовый URL направляет его через роутер Flatkey вместо прямой отправки к endpoint другого провайдера.

Сохраняйте оба значения в конфигурации окружения, чтобы можно было менять их без правки логики приложения:

export OPENAI_API_KEY="$FLATKEY_API_KEY"
export OPENAI_BASE_URL="https://router.flatkey.ai/v1"

Используйте имена переменных, ожидаемые вашим фреймворком. Некоторые библиотеки читают OPENAI_BASE_URL; другим при создании клиента требуется опция base_url или baseURL.

Шаг 3: Отправьте свой первый запрос

Начните с одного короткого детерминированного запроса. Цель — убедиться в аутентификации, подключении, доступе к модели и разборе ответа, прежде чем добавлять потоковую передачу, инструменты, структурированный вывод или поведение fallback.

Вариант A: cURL

Замените YOUR_CURRENT_MODEL на модель, доступную в текущем каталоге Flatkey:

curl https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CURRENT_MODEL",
    "messages": [
      {
        "role": "user",
        "content": "Reply with exactly: flatkey quickstart connected"
      }
    ],
    "temperature": 0
  }'

Вариант B: Python

Установите клиент OpenAI:

pip install openai

Создайте quickstart.py:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

response = client.chat.completions.create(
    model="YOUR_CURRENT_MODEL",
    messages=[
        {
            "role": "user",
            "content": "Reply with exactly: flatkey quickstart connected",
        }
    ],
    temperature=0,
)

print(response.choices[0].message.content)
print(response.usage)

Запустите его:

python quickstart.py

Вариант C: JavaScript

Установите клиент:

npm install openai

Создайте quickstart.mjs:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: "https://router.flatkey.ai/v1",
});

const response = await client.chat.completions.create({
  model: "YOUR_CURRENT_MODEL",
  messages: [
    {
      role: "user",
      content: "Reply with exactly: flatkey quickstart connected",
    },
  ],
  temperature: 0,
});

console.log(response.choices[0].message.content);
console.log(response.usage);

Запустите его:

node quickstart.mjs

Шаг 4: Прочитайте ответ

Для стандартного запроса chat-completions начните с четырёх полей:

Упрощённый ответ выглядит так:

{
  "id": "chatcmpl-example",
  "model": "YOUR_CURRENT_MODEL",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "flatkey quickstart connected"
      },
      "finish_reason": "stop",
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 5,
    "total_tokens": 17
  }
}

Точные идентификаторы и количество токенов будут отличаться. Условие успешного первого запроса — это не побайтовое совпадение; это корректный HTTP-ответ, сообщение assistant, которое можно разобрать, и информация об использовании, которую ваше приложение может записать.

Шаг 5: Проверьте использование после вызова

Не останавливайтесь на 200 OK. Полезный quickstart также доказывает, что запрос виден людям, которые будут обслуживать интеграцию.

Справка по консоли

Откройте Console → Usage & Logs после запроса.

Найдите новый вызов и подтвердите доступные вашему аккаунту детали, такие как:

• Время запроса.
• Модель или маршрут.
• Статус.
• Использование токенов.
• Стоимость или влияние на баланс.
• Сведения об ошибке, когда запрос завершается неудачей.

Если приложение получило ответ, но ожидаемая запись в журнале отсутствует, сначала проверьте, что вы просматриваете тот же аккаунт, рабочее пространство и API-ключ, которые использовались в запросе. Также сохраните идентификатор ответа и время запроса перед повторной попыткой; эти две детали значительно упрощают диагностику.

Изучите текущую страницу цен Flatkey перед переходом от smoke test к устойчивой нагрузке. Сравнивайте модель, объём запросов, набор токенов и ожидаемое поведение fallback, которое вы планируете использовать, — не только стоимость одного успешного вызова.

Шаг 6: Добавьте безопасную последовательность fallback

Маршрутизация fallback должна появляться после того, как первая модель заработает. Иначе резервный маршрут может скрыть настоящую проблему: неверный ключ, неправильный базовый URL, недоступную модель, некорректный запрос или ограничение аккаунта.

Начните с короткого упорядоченного списка моделей, которые вы протестировали для одной и той же задачи:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

models = [
    "PRIMARY_CURRENT_MODEL",
    "FALLBACK_CURRENT_MODEL",
]

last_error = None

for model in models:
    try:
        response = client.chat.completions.create(
            model=model,
            messages=[
                {
                    "role": "user",
                    "content": "Return JSON with one key named status and value ok",
                }
            ],
            temperature=0,
        )
        print(model, response.choices[0].message.content)
        break
    except Exception as error:
        last_error = error
        print(f"Route failed: {model}")
else:
    raise RuntimeError("All approved model routes failed") from last_error

Этот пример намеренно небольшой. Перед использованием в production добавьте:

• Небольшой список ошибок, подлежащих повторной попытке.
• Тайм-аут для каждой попытки и общий дедлайн запроса.
• Экспоненциальная задержка при временных сбоях.
• Структурированные логи, содержащие использованную модель и идентификатор ответа.
• Проверка выходных данных для JSON, вызовов инструментов или других требуемых схем.
• Предел стоимости, чтобы резервный маршрут не выбирался молча и не приводил к неподходящему пути.

Не повторяйте ошибки аутентификации через несколько моделей. Не повторяйте некорректно сформированные запросы, пока запрос не будет исправлен. Не считайте все модели взаимозаменяемыми только потому, что они принимают payload chat-completions.

Практическая политика резервного выбора

Используйте эту таблицу решений как отправную точку:

Основное правило простое: повторно пытайтесь при временных сбоях транспортного уровня; исправляйте ошибки конфигурации и схемы; используйте fallback только если он одобрен для той же производственной задачи.

Типичные ошибки при первом запросе

401 или ошибка аутентификации

Убедитесь, что в запросе используется Authorization: Bearer <key>, ключ активен и не было случайно скопировано лишних пробелов. Проверьте, что приложение читает ожидаемую переменную окружения.

404 или неверная конечная точка

Используйте совместимый с OpenAI базовый URL https://router.flatkey.ai/v1 и путь chat /chat/completions. Не добавляйте /v1 дважды по ошибке.

Модель не найдена или недоступна

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

Успешный HTTP-ответ, но ошибка приложения

Один раз зафиксируйте raw-ответ в безопасной среде разработки. Убедитесь, что код читает choices[0].message.content для chat completions и не ожидает схему ответа другого endpoint.

Неожиданные расходы во время fallback

Записывайте использованную модель при каждом вызове, ограничивайте список маршрутов и проверяйте Usage & Logs. Политика fallback без дедлайна и ограничения стоимости может превратить одно действие пользователя в несколько платных запросов.

Чек-лист для production

Перед отправкой реального трафика через интеграцию убедитесь в следующем:

• [ ] API-ключ хранится в менеджере секретов или в серверной среде выполнения.
• [ ] Для разработки, staging и production используются отдельные ключи.
• [ ] Базовый URL задаётся в конфигурации, а не захардкожен по всему кодовой базе.
• [ ] Выбранная модель доступна и протестирована для фактической рабочей нагрузки.
• [ ] Тайм-ауты, ошибки, подлежащие повторной попытке, и общие дедлайны явно определены.
• [ ] Резервные модели используют тот же обязательный контракт на выходные данные.
• [ ] Журналы использования и ошибок доступны операционной команде.
• [ ] Ожидания по затратам были проверены с учётом актуальных цен.
• [ ] При необходимости настроены ограничения по ключам или allowlist.
• [ ] Путь отката позволяет быстро восстановить предыдущий маршрут.

Сделайте первый запрос, затем оптимизируйте

Самый быстрый способ оценить Flatkey — сделать первую проверку как можно более узкой. Создайте один ключ, измените один базовый URL, отправьте один запрос, прочитайте один ответ и найдите этот же вызов в Usage & Logs.

После того как этот путь подтверждён, добавьте резервную маршрутизацию как наблюдаемую политику, а не скрытый цикл повторных попыток. Сохраняйте короткий список одобренных моделей, сохраняйте доказательства ошибок, проверяйте выходные данные и изучайте актуальные цены перед увеличением трафика.

Когда будете готовы, создайте аккаунт Flatkey, выполните первый запрос через router.flatkey.ai и используйте запись в консоли как приёмочный тест для вашей интеграции.