Партнерский и реселлерский API для доступа к ИИ: ключи, использование, выставление счетов и средства управления клиентами

Перепродажа или внедрение доступа к AI API — это не просто вопрос пересылки запросов поставщику модели. Настоящая оперативная работа начинается, когда каждому нижестоящему клиенту требуются собственные учетные данные, лимиты, записи об использовании, события выставления счетов, средства управления поддержкой и журнал аудита. Для управления этой плоскостью управления существует партнерский или реселлерский API.

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

Это важно, поскольку с общим ключом поставщика легко начать, но с ним трудно выжить. Когда несколько клиентов используют одни и те же учетные данные, атрибуция становится хрупкой. Реакция на насилие затрагивает каждого. Лимиты ставок и балансы объединяются. Споры о счетах трудно расследовать. Устойчивая настройка реселлера требует доступа на уровне клиента и реестра, в котором можно объяснить, что произошло, кто это вызвал, сколько это стоило и какие меры контроля были применены.

Что должен делать партнерский API

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

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

Model Gate — пример этого шаблона. Его партнерский API документирован как межсерверный интерфейс для ботов, панелей реселлеров, внутренних систем обеспечения и доверенных интеграций. Он использует аутентификацию носителя с помощью ключа партнерского API и предоставляет операции для ключей API, групп, использования ключей и групп, записей последних запросов, транзакций баланса и асинхронного опроса результатов. Это возможности уровня управления, а не конечные точки вывода модели.

Это различие важно. Клиенты могут увидеть простую поверхность продукта, такую ​​​​как портал реселлера AI API, пакет AI API с белой этикеткой или интеграцию AI, управляемую агентством. За этой поверхностью партнерской системе необходима достаточная структура для создания учетных данных, соблюдения правил плана, измерения потребления и обработки событий поддержки, не требуя от каждого клиента создавать учетные записи прямых поставщиков.

Когда он нужен агентствам и командам SaaS

Партнерский API становится необходимым, когда доступ к ИИ является частью продукта или управляемой услуги, а не разовой интеграцией. Агентствам может потребоваться AI API для агентств, чтобы у каждого клиента был отдельный бюджет, отдельный отчет об использовании и отдельный переключатель отключения. SaaS-компаниям могут потребоваться ключи для каждого арендатора, даже если конечные пользователи их никогда не увидят, чтобы платформа могла отнести стоимость модели к нужной учетной записи. Командам внутренней платформы могут потребоваться границы на уровне проекта для отделов, сред или приложений.

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

Учетные записи прямых поставщиков по-прежнему могут быть правильным выбором для некоторых клиентов. Они дают покупателю прямой контроль над поставщиками и позволяют четко выставлять счета поставщикам. Но они усложняют унифицированное выставление счетов реселлерам, жесткие ограничения на уровне клиентов, сортировку поддержки и переносимость моделей. API-интерфейсы администратора поставщика могут предоставлять проекты, рабочие области, ключи API, бюджеты или отчеты, но эти объекты не всегда эквивалентны у разных поставщиков. Партнерский API над многомодельным шлюзом предоставляет вам нормализованный уровень для контракта, ориентированного на клиента.

Основная модель данных

Надежная партнерская интеграция начинается с четкой локальной модели данных. Как минимум, определите учетную запись клиента, внешний идентификатор клиента, план, режим выставления счетов, ключи API, группы ключей, ограничения на использование, разрешения модели, текущее состояние и метаданные поддержки. Не предполагайте, что владелец учетной записи, владелец выставления счетов, субъект учетных данных, арендатор клиента и конечный пользователь — это одно и то же лицо.В средах реселлеров и SaaS они часто различаются.

Практическая модель часто включает в себя следующие объекты:

• Клиент или арендатор: граница коммерческого объекта или приложения, используемая для атрибуции и выставления счетов.
• Ключ API: учетные данные, используемые клиентом, приложением, средой или внутренней службой для вызова API вывода.
• Граница группы или плана: контейнер для общих ограничений, разрешений модели, правил ценообразования или отчетов.
• Запись использования: нормализованное событие, описывающее идентификатор запроса, клиента, ключ, группу, модель, конечную точку, количество токенов, статус, метку времени и компоненты затрат.
• Транзакция баланса: запись в финансовой книге для кредитов, дебетов, корректировок, возмещений или расчетов.
• Асинхронное задание: отправленная модель задача, которая может завершиться позже и требует опроса, обработки обратного вызова и окончательного состояния выставления счета.
• Событие аудита: внутренняя запись о предоставлении, ограничении изменений, ротации ключей, приостановке, действиях поддержки и результатах сверки.

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

Рабочий процесс подготовки

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

Полезные состояния включают pending, key_created, limits_applied, доставлен, активен, приостановлен, rotation_required и удален. Эти состояния делают повторные попытки и действия поддержки понятными. Если создание ключа прошло успешно, но время назначения ограничено, система должна знать, с чего возобновить работу. Если клиент переходит с предоплаченных кредитов на постоплату, система должна фиксировать, какие элементы управления были изменены и когда.

Обработка учетных данных заслуживает особого внимания. Доставка секретного ключа API должна быть одноразовым безопасным событием. Не регистрируйте секреты. Не отправляйте учетные данные поставщика в браузеры или мобильные приложения клиентов. Храните только то, что необходимо для поддержки клиента, и предоставляйте пути ротации, которые позволяют запускать как старые, так и новые ключи во время запланированного переключения, когда от них зависят производственные рабочие нагрузки.

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

Идемпотентность — это функция биллинга

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

Мутация партнерских операций должна требовать стабильных ключей идемпотентности. Model Gate документирует это ожидание изменения запросов POST, PATCH и DELETE Partner API и инструктирует разработчиков повторить ту же логическую операцию с тем же ключом идемпотентности после таймаутов. Он также документирует семидневный период хранения записей идемпотентности.

Ключ должен быть получен на основании бизнес-намерения, а не случайной повторной попытки. Например, create-key:customer_123:prod:plan_pro — это стабильная логическая операция. Новая повторная попытка той же операции должна использовать ее повторно. Более поздняя операция по созданию второго ключа для другой среды должна использовать другой ключ идемпотентности.

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

Использование, измерение и выставление счетов

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

Деньги, кредиты, балансы, множители и объемы использования должны анализироваться как точные десятичные дроби. Model Gate документирует финансовые поля и поля использования в своем Partner API как десятичные строки JSON и инструктирует разработчиков использовать десятичную арифметику произвольной точности, а не двоичную плавающую запятую. Такая конструкция позволяет избежать небольших ошибок округления, которые становятся заметными в счетах, отображении остатка баланса и расчетах маржи реселлера.

Измеренное выставление счетов в стиле Stripe предъявляет аналогичные требования: явные идентификаторы клиентов, значения использования, временные метки, измерения и идентификаторы идемпотентности. Если вы экспортируете данные об использовании шлюза во внешнего поставщика услуг по выставлению счетов, не сворачивайте слишком много подробностей слишком рано. Вы можете выставлять счета за упрощенную единицу, но вам все равно потребуется достаточно средств для сверки записей запросов, балансовых транзакций, счетов, возмещений и обращений в службу поддержки клиентов.

Для команд, разрабатывающих планы и прибыль, учет партнеров напрямую связан с выставлением счетов через AI API. Шлюз может нормализовать доступ к модели и аналитику использования, но реселлеру по-прежнему нужен каталог цен, даты вступления в силу, политика округления, правила налогообложения и выставления счетов, а также задание по сверке, которое сравнивает локальное использование, состояние шлюза, транзакции баланса, события обратного вызова и записи поставщика счетов.

Лимиты расходов, квоты и ограничения ставок

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

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

Ограничения ставок также требуют четкого контроля. Клиент может достичь лимита на уровне реселлера, лимита на уровне шлюза или лимита вышестоящего поставщика. В документации для клиентов должно быть объяснено, как обрабатывать ответы HTTP 429, особенно поведение Retry-After. Модель Gate документирует ответы об ограничении скорости с помощью заголовков HTTP 429, Retry-After и X-RateLimit. Клиентам следует отступать в соответствии с этими заголовками, а не немедленно повторять попытку, вызывая скачки нагрузки или чрезмерные расходы.

История запросов, разбиение на страницы и хранение

Записи последних запросов полезны для поддержки, отладки и краткосрочной сверки. Они не заменяют постоянную финансовую базу данных, если шлюз явно не обещает такую ​​модель хранения. Считайте API истории запросов операционными окнами. Экспортируйте и сохраняйте записи, необходимые для выставления счетов, аудита, поддержки и аналитики.

Партнерские API обычно используют разбивку курсора на страницы для конечных точек сбора данных. Ограничение на документы Model Gate, а также непрозрачное разбиение курсора на страницы и временные метки UTC RFC3339. Курсоры следует рассматривать как непрозрачные токены. Не создавайте их вручную, не храните внутри них бизнес-смысл и не создавайте логику выставления счетов, принимающую форму курсора. Ваш экспортер должен помнить последнюю успешную контрольную точку, безопасно обрабатывать повторяющиеся записи и выполнять сверку по идентификатору запроса, а не только по положению страницы.

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

Обратные вызовы, опрос и асинхронный вывод

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

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

Model Gate документирует результаты асинхронного опроса в Partner API и поведение обратного вызова в документации по API. В реселлерском продукте эти возможности должны быть реализованы в устойчивой модели доставки. Клиенты должны видеть четкое состояние задания и конечный результат, в то время как серверная часть партнера сохраняет операционную информацию, необходимую для поддержки и выставления счетов.

Абстракция поставщика без потери происхождения

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

Это особенно важно, когда поставщики меняют цены, объявляют устаревшими модели, изменяют ограничения скорости или предоставляют другую семантику администрирования. Проекты OpenAI, рабочие пространства Anthropic, ключи шлюзов облачных API и виртуальные ключи сторонних шлюзов AI — все они решают связанные проблемы, но они не предоставляют идентичные элементы управления. Плоскость управления реселлера нуждается в собственной нормализованной модели и должна рассматривать поля, специфичные для поставщика, как источник, который поддерживает отладку, реагирование на инциденты, доверие клиентов и планирование миграции.

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

Контроль поддержки и злоупотреблений

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

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

Контроль за злоупотреблениями должен быть точным. Замораживание одного ключа не должно приостанавливать работу несвязанных клиентов. Шумный клиент не должен исчерпывать баланс общего счета или возможности поставщика для всех остальных клиентов. Элементы управления на уровне группы и ключа делают реагирование более быстрым и менее разрушительным.

Белая этикетка, совместный бренд или прозрачный доступ

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

Единого правильного ответа не существует. Сокрытие деталей может сделать продукт для клиента проще. Раскрытие подробностей может улучшить доверие, закупки, проверку соответствия и обработку инцидентов. Что важно, так это последовательность. Счет, процесс поддержки, политика допустимого использования, язык ограничения скорости и обязательства по обработке данных должны соответствовать способу предоставления доступа.

Распространенные ошибки

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

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

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

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

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

Контрольный список реализации

Начните с жизненного цикла клиента. Определите, как создается, обновляется, приостанавливается, повторно активируется, ротируется и удаляется клиент. Сопоставьте каждое состояние с операциями партнерского API и событиями локального аудита.

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

Затем создайте экспорт и сверку использования. Экспорт запросов и записей транзакций по расписанию. Используйте точные десятичные дроби. Проверьте наличие отсутствующих событий, дублирующихся отчетов по счетам, невыполненных асинхронных заданий, сбоев обратного вызова и несоответствий счетов.

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

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

Заключение

API для партнеров и реселлеров — это плоскость управления, которая превращает доступ к модели ИИ в надежный продукт. Он должен создавать учетные данные на уровне клиента, организовывать их в группы или планы, обеспечивать контроль над расходами и ставками, предоставлять записи об использовании и транзакциях, поддерживать асинхронные рабочие процессы и обеспечивать вспомогательные операции, такие как ротация, замораживание и сверка.

Основной принцип прост: каждое обещание, ориентированное на клиента, требует надежного внутреннего объекта и журнала аудита. Если вы обещаете отдельное выставление счетов, создайте отдельную атрибуцию. Если вы обещаете бюджет, соблюдайте и согласовывайте его. Если вы повторяете операции, сделайте их идемпотентными. Если вы выставляете счета за использование, сохраняйте точные десятичные записи и происхождение на уровне запроса.

Возможности Partner API Model Gate актуальны, поскольку они касаются работы плоскости управления вокруг многомодельного шлюза, совместимого с OpenAI: аутентификация между серверами, автоматизация ключей API и групп, десятичное использование и финансовые поля, история запросов, транзакции баланса, асинхронный опрос результатов, требования к идемпотентности, ответы на ограничение скорости, обратные вызовы, унифицированное выставление счетов, управление ключами API, аналитика использования и командный контроль. При осторожном использовании эти примитивы позволяют агентствам, командам SaaS и реселлерам пакетировать доступ к AI API, не отказываясь от контроля над выставлением счетов или операционной ответственности.