Чек-лист продукції API OpenRouter

Перевірити сумісність API та кінцеві точки

Використовуйте стандартні OpenAI-сумісні ендпоінти для надійної інтеграції.

Головна кінцева точка POST /v1/chat/completions. Це обробляє генерацію тексту для історій чату. Додаткова кінцева точка, GET /v1/models, перелічує доступні моделі. Вам не потрібні ендпоінти для вбудовування або генерації зображень для задач лише з текстом. Багато розробників вважають, що їм потрібен складний шар маршрутизації. OpenRouter спрощує це, надаючи єдину точку входу. Ви надсилаєте JSON-пакет із ID моделі та системними промптами. Сервіс повертає структурований JSON із вмістом та даними про використання. Ця архітектура відповідає очікуванням офіційного SDK OpenAI. Ви можете міняти моделі без зміни коду клієнта. Просто оновіть ID моделі у конфігурації. Переконайтеся, що ваш клієнт підтримує останню схему JSON. Старіші версії можуть відхиляти нові параметри. Протестуйте з’єднання перед розгортанням у продакшн. Переконайтеся, що формат відповіді відповідає вашому парсеру.

Налаштуйте автентифікацію та ключі

Негайно збережіть свій API-ключ у змінних середовища одразу після генерації.

Згенеруйте ключ через панель постачальника. Збережіть його в безпечному місці. Ніколи не жорстко закодуйте його в репозиторії коду. Передавайте його через Authorization: Bearer <key> header. Кожен ключ прив’язаний до конкретного облікового запису. Ви можете обертати ключі, якщо підозрюєте витік. Деякі постачальники дозволяють кілька ключів на обліковий запис. Це дозволяє вам розділити трафік розробки та виробництва. Відстежуйте використання на ключі, щоб виявляти аномалії. Регулярно анулюйте невикористовувані ключі. Використовуйте короткочасні ключі для тимчасових скриптів. Це зменшує масштаб ураження при компрометації. Переконайтеся, що ваша версія SDK підтримує автентифікацію за маркером Bearer. Старіші бібліотеки можуть вимагати інший формат заголовка. Перевірте документацію для вашого конкретного SDK. Переконайтеся, що ключ має достатній баланс. Прострочений ключ повертає помилку 401. Ключ з нульовим балансом повертає помилку 402. Розрізняйте ці два стани у своїй логіці.

Обробка потокової передачі та використання токенів

Увімкніть потокову передачу для нижчої затримки та зворотного зв’язку з користувачем у реальному часі.

Встановити stream: true у тілі запиту. Сервер надсилає серію подій Server-Sent Events (SSE). Кожна подія містить частковий фрагмент тексту. Ви повинні зібрати ці фрагменти, щоб сформувати повну відповідь. Останній фрагмент часто містить статистику використання токенів. Це дозволяє відстежувати витрати в реальному часі. Без потокової передачі ви чекаєте на всю відповідь. Це значно збільшує сприйняту затримку. Потокова передача є необхідною для чат-інтерфейсів. Вона створює ефект друку, який відчувається як реактивний. Будьте обережні з обробкою помилок під час потокової передачі. Якщо з'єднання розривається, ви втрачаєте поточний фрагмент. Логіка перепідключення повинна зберігати стан розмови. Деякі SDK обробляють потокову передачу автоматично. Іншим потрібні ручні слухачі подій. Оберіть підхід, який відповідає вашій архітектурі. Переконайтеся, що ваш парсер обробляє неповні фрагменти JSON. Не припускайте, що кожна подія є повним об'єктом. Буферизуйте дані, доки не отримаєте валідну структуру.

Моніторинг лімітів швидкості та паралелізму

Відстежуйте кількість запитів за хвилину, щоб уникнути перерв у роботі сервісу.

OpenRouter встановлює суворі ліміти швидкості для кожного API-ключа. Перевищення цих лімітів викликає помилку 429 Too Many Requests. Вам потрібно реалізувати експоненційне сповільнення у логіці повторних спроб. Одночасні запити також враховуються в ваших лімітах. Перевірте заголовки відповіді на наявність залишкової квоти. Деякі постачальники відкривають ці заголовки напряму. Іншим потрібно виводити ліміти з помилок. Висока конкурентність може вичерпати ваш пул з’єднань. Переконайтеся, що ваш клієнт ефективно керує з’єднаннями. Використовуйте пул з’єднань для зменшення накладних витрат. Слідкуйте за глибиною черги під час пікових навантажень. Якщо ви досягли ліміту, зачекайте перед повторною спробою. Рандомізуйте час очікування, щоб уникнути проблем «стада». Логуйте всі події лімітів швидкості для налагодження. Це допомагає виявити закономірності у вашому використанні. Налаштуйте параметри конкурентності на основі цих журналів. Не припускайте, що один ключ може обслуговувати необмежений трафік. Розподіляйте навантаження між кількома ключами, якщо це необхідно. Це вимагає ретельного керування станом. Переконайтеся, що кожен ключ підтримує власний контекст, якщо це необхідно.

Керування крипто-платежами та поповненням

Використовуйте попередній кредит для покриття використання токенів без щомісячних зборів.

Поповніть свій рахунок криптовалютою. Підтримувані мережі включають USDT на TRC20 та USDC на Base. Мінімальні поповнення починаються від $20. Бонуси застосовуються до більших сум. Ви отримуєте 5% додатково за $50, 10% за $100 та 15% за $200. Кошти ніколи не згорають. Це ідеально для довгострокових проектів. Ви платите лише за фактично використані токени. Помилки та відмови — безкоштовні. Це захищає ваш бюджет від несподіваних витрат. Новим акаунтам надається $0.50 для тестування. Повернення коштів за стандартні покупки не здійснюється. Подвійні списання виправляються через підтримку. Переконайтеся, що ваш гаманець підтримує необхідні мережі. Перевірте адресу контракту перед надсиланням. Неправильна мережа може призвести до втрати коштів. Регулярно перевіряйте баланс. Низький баланс може несподівано перервати службу. Автоматизуйте поповнення, якщо можливо. Це забезпечує безперервну доступність для критичних завдань.

Перевірте фільтри контенту та відмови

Переконайтеся, що модель поводиться належним чином з uncensored промптами.

Необмежені моделі все ще можуть застосовувати жорсткі обмеження. Перевірте обмеження на певні типи контенту. Протестуйте з відомими тригерними фразами. Переконайтеся, що модель реагує відповідним чином. Деякі постачальники зберігають фільтри з юридичних причин. Перевірте це перед тим, як покладатися на модель для чутливих даних. Протестуйте крайні випадки у вашій доменній області. Надішліть запити, які зазвичай викликають відмови. Спостерігайте за форматом відповіді. Чи повертає вона причину відмови? Чи генерує вона контент мовчки? Задокументуйте цю поведінку у ваших інтеграційних тестах. Це запобігає несподіванкам у продакшні. Якщо модель змінить свою поведінку, оновіть тести. Повідомте вашу команду про будь-які суттєві зміни. Стабільність є ключовою для довіри користувачів. Переконайтеся, що ваш додаток коректно обробляє відмови. Не припускайте, що кожна відповідь є валідною. Перевірте структуру виводу. Перевірте на галюцинації або помилки форматування. Це забезпечує надійний користувацький досвід.

Впровадити обробку помилок для безкоштовних запитів

Гарно обробляйте помилки, щоб підтримувати плавний користувацький досвід.

Мережеві помилки, тайм-аути та помилки сервера можуть виникати. Реалізуйте логіку повторних спроб із експоненційним сповільненням. Розрізняйте тимчасові та постійні помилки. Помилка 429 є тимчасовою. Зачекайте та повторіть спробу. Помилка 400 є постійною. Перевірте свої вхідні дані. Помилка 500 є серверною. Повторіть спробу з обережністю. Логуйте всі помилки для налагодження. Включайте корисне навантаження запиту та тіло відповіді. Це допомагає швидко відтворити проблеми. Не показуйте користувачам необроблені помилки. Форматуйте їх у зрозумілі повідомлення. Обережно обробляйте помилки потокової передачі. Відключіться від потоку подій. Очистіть ресурси. Переконайтеся, що ваша програма не втрачає пам'ять. Ретельно протестуйте сценарії помилок. Симулюйте втрату мережі. Симулюйте тайм-аути сервера. Переконайтеся, що ваша логіка відновлення працює. Це забезпечує надійність за несприятливих умов.

Масштабуйте з режимом JSON та викликом інструментів

Використовуйте структурований вивід для надійного виділення даних та виконання функцій.

Увімкніть режим JSON, встановивши response_format: {type: "json_object"}. Це змушує модель виводити дійсний JSON. Використовуйте це для парсингу даних або генерації конфігурацій. Виклик інструментів (tool calling) дозволяє моделі виконувати функції. Визначте свої інструменти в тілі запиту. Модель вирішує, коли їх викликати. Передавайте результати назад моделі. Вона може згенерувати фінальну відповідь на основі виводу. Це створює цикл для складних завдань. Переконайтеся, що ваші визначення інструментів чіткі. Нечіткі інструменти призводять до неправильних викликів. Перевіряйте вивід JSON перед парсингом. Це запобігає помилкам часу виконання у вашому коді. Використовуйте виклик інструментів для завдань з вилучення даних. Це значно підвищує точність. Тестуйте з різними форматами вхідних даних. Переконайтеся, що модель обробляє крайні випадки. Документуйте доступні інструменти для вашої команди. Це забезпечує узгоджене використання в усіх проектах.

Огляд Політики конфіденційності та використання даних

Розуміння того, як постачальник зберігає та використовує ваші дані.

Перевірте політику конфіденційності щодо умов зберігання даних. Деякі постачальники використовують ваші дані для навчання. Інші зберігають їх приватно. Переконайтеся, що ваші дані не використовуються для покращення моделі, якщо це для вас важливо. Перевірте стандарти шифрування. Дані мають бути зашифровані під час передачі та зберігання. Перевірте, чи зберігаються логи. Логи можуть містити ваші промпти. Переконайтеся, що ці логи захищені. Ознайомтеся з умовами надання послуг щодо клаузул відповідальності. Зрозумійте, кому належить згенерований контент. Деякі постачальники претендують на права до ваших результатів. Переконайтеся, що це відповідає вашим потребам. Видаліть обліковий запис, якщо більше не користуєтеся сервісом. Переконайтеся, що ваші дані видалено. Зверніться до підтримки, якщо у вас є запитання. Задокументуйте налаштування конфіденційності для цілей аудиту. Це забезпечує відповідність внутрішнім політикам.