API Key для OCR: регистрация, создание и безопасная настройка (2026)

Ключ OCR-интерфейса — это прежде всего учётные данные, но у OCR есть своя специфика: пакетная обработка счетов, документов и сканов часто идёт в фоне, и при утечке ключа другие расходуют ваш лимит, а утечь могут данные клиентов. Многие команды к тому же переносят тестовый ключ прямо в production.

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

Примечание: OpenAI, Google, Microsoft, Alibaba Cloud, Tencent Cloud, Baidu и другие упомянутые бренды — товарные знаки их правообладателей. Статья носит технический характер и не означает аффилированности с производителями; интерфейсы, права и правила тарификации смотрите в официальной документации платформ и на страницах сайта.

1. Сначала разделите три способа аутентификации OCR

Единого стандарта для ключей OCR нет. До подключения определите тип платформы, иначе легко получить ситуацию «ключ верный, но 401»:

Bearer Key: самый распространённый в OpenAI-совместимых интерфейсах; заголовок Authorization: Bearer sk-..., чат, визуальные задачи и OCR обычно используют одну схему.
Access Key + Secret Key: используется частью облачных провайдеров; запрос нужно подписывать по документации, Secret нельзя писать во фронтенд или логи.
API Key + Secret Key с обменом на токен: сначала ключ и секрет обмениваются на краткосрочный access_token, затем с ним вызывается OCR; по истечении токен получают заново.

На одной платформе OCR может использовать тот же ключ, что и чат-модели. Возможность вызова зависит от прав аккаунта, авторизации модели и баланса, а не от типа ключа. До создания проверьте, поддерживает ли консоль белый список моделей или права субаккаунта.

2. Регистрация и создание ключа

На примере ZSQH AI Gateway процесс такой:

Откройте https://ai.zhongshangqihang.com или сразу ссылку регистрации, зарегистрируйтесь по email и пройдите проверку.
После входа откройте консоль и раздел «API-ключи», посмотрите существующие ключи.
В разделе «Кошелёк» проверьте баланс; на этапе тестов пополните небольшую сумму.
Нажмите «Создать ключ», укажите имя, лимит и срок действия; если платформа позволяет, ограничьте список моделей.
Сразу скопируйте полный ключ. Большинство платформ показывают его один раз, после закрытия страницы остаётся только маска.
Проверьте запрос на тестовом изображении, затем в «Логах расхода» убедитесь, что модель, число вызовов и стоимость записываются корректно.

Если вы используете нативный OCR облачного провайдера, создайте субаккаунт и дайте только права, связанные с OCR; не применяйте Access Key основного аккаунта для тестов и production.

3. Что указать при создании: имя, лимит и срок действия

Имя ключа должно помогать разобраться в счёте через полгода. Используйте сочетание «назначение + среда», например ocr-prod-batch, ocr-staging, ocr-dev-zhang, а не «тест1».

Лимит сначала ставьте небольшим и повышайте после проверки расхода на реальной партии изображений. Срок действия зависит от назначения: временным скриптам — 7 или 30 дней, production-ключам — фиксированный цикл ротации. Рабочая схема распределения:

Сценарий	Имя ключа	Лимит	Где хранить	Цикл ротации
Локальная разработка	`ocr-dev-имя`	Минимальный	Локальный `.env`	30 дней
Тестовая среда	`ocr-staging`	Низкий	CI/CD Secret	60 дней
Production, пакеты	`ocr-prod-batch`	По бюджету	Менеджер секретов	90 дней
Production, реальное время	`ocr-prod-realtime`	По бюджету	Менеджер секретов	90 дней

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

4. Четыре принципа проектирования прав

Одно назначение — один ключ: пакетное распознавание, реальное время и административные скрипты раздельно. При сбое одного класса задач можно отключить соответствующий ключ, не затрагивая остальное.
Минимальные права: если можно открыть только OCR, не открывайте все модели; если можно использовать субаккаунт, не выдавайте ключ основного; если можно ограничить проект, не давайте права уровня аккаунта.
Ключ не во фронтенде: ключ в браузере, приложении или мини-программе легко извлечь. Загрузка изображений и OCR-запросы должны идти через ваш бэкенд, который хранит ключ.
Разделение production и тестов: утечка тестового ключа не влияет на production-счёт и не загрязняет production-статистику.

OCR часто связан со счетами, договорами и документами. Права ключа близки к правам доступа к данным: помимо контроля вызовов, уточните, сохраняет ли платформа оригиналы, как долго и использует ли их для обучения. Если в production поддерживается белый список IP, включите его и сохраняйте аудит.

5. Поместите ключ в переменные окружения

Не вшивайте ключ в код и не коммитьте в Git. В Python-проекте можно читать так:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

resp = client.chat.completions.create(
    model=os.environ["OCR_MODEL"],  # имя модели с поддержкой изображений со страницы тарифов
    messages=[{"role": "user", "content": "Ответь только OK"}],
)
print(resp.choices[0].message.content)

Код проверяет только совпадение ключа, Base URL и имени модели; после подтверждения связи замените запрос на реальное изображение.

При локальном использовании .env добавьте файл в .gitignore и коммитьте только .env.example. В production предпочитайте контейнерные секреты, менеджер ключей облака или Vault; не пишите ключ в Dockerfile, слои образа, артефакты фронтенд-сборки и логи CI. После изменения переменных перезапустите процесс: часто «в production 401, локально всё работает» из-за того, что сервис читает старые переменные или платформа развёртывания не передала их в среду выполнения.

6. Порядок разбора 401

При 401 Unauthorized проверяйте по порядку — обычно удаётся найти причину за несколько минут:

Проверьте заголовок: Authorization: Bearer sk-..., между Bearer и ключом один пробел.
Скопируйте ключ заново, убедитесь в отсутствии пробелов, переводов строк, кавычек и невидимых символов.
Убедитесь, что ключ не удалён, не отключён и не просрочен.
Проверьте, что ключ и Base URL принадлежат одной платформе; не отправляйте ключ платформы A на платформу B.
Выведите в процессе длину переменной окружения (не содержимое), чтобы убедиться, что там значение, а не пустая строка.
Проверьте, не переписывает ли Authorization обратный прокси, шлюз или SDK; при multipart-загрузке заголовок теряется особенно часто.
Если падает только часть запросов, проверьте, не раскрыт ли ключ во фронтенде и не отключён ли он риск-контролем.

Различайте типы ошибок: 401 — проблема идентичности, 403 — чаще права или регион, 413 — слишком большое изображение, 429 — частота или квота. OCR-ошибка 400 часто связана с форматом изображения, кодированием Base64 или повреждённым файлом; не приписывайте всё ключу.

7. Официальный ключ или ключ шлюза

Оба пути рабочие; различия в закупке, сети и сопровождении:

Прямое официальное подключение: аккаунт, счёт и модели управляются производителем; подходит командам с платёжными возможностями и собственной сетевой и комплаенс-экспертизой. При использовании одного OCR путь короче; минус — разные схемы аутентификации, при нескольких провайдерах нужно вести несколько ключей и счетов.
Подключение через шлюз: один Base URL и один ключ для нескольких моделей, проще доступ и расчёты в юанях, логи и лимиты централизованы. Цена — дополнительный уровень зависимости; уточните политику данных, доступность, порядок уведомлений о сбоях и поддержку счетов.

При выборе не смотрите только на цену. Как минимум уточните: сохраняются ли изображения и результаты, поддерживаются ли счета, объявляется ли о выводе моделей, можно ли экспортировать расход, как связаться при сбое. Конкретные модели и цены — на странице тарифов; цены меняются, не планируйте бюджет по цифрам из старых статей.

8. Ротация и действия при утечке

Сделайте ротацию регулярным действием, а не реакцией на инцидент:

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

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

Частые вопросы

Ключ OCR и ключ чат-модели — один и тот же?

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

Можно ли увидеть полный ключ после создания?

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

Почему локально работает, а сервер возвращает 401?

Проверьте три вещи: переданы ли переменные окружения, сохраняет ли обратный прокси заголовок Authorization, не используется ли в production удалённый или просроченный ключ. Затем убедитесь, что Base URL указывает на нужную платформу.

OCR тарифицируется за изображение или за токены?

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

Достаточно ли удалить ключ после утечки?

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

Что дальше

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