Три необязательных заголовка. Первые два разделяют ваш трафик по приложениям и, если вы захотите, показывают приложение в публичном рейтинге. Третий делает разбор инцидента вопросом минут.
| Заголовок | Что делает |
|---|---|
| X-Title | Название приложения. Колонка в логе активности, разрез в отчётах, подпись в рейтинге |
| X-Site-Url | Ссылка на приложение. Показывается в рейтинге рядом с названием |
| X-Request-Id | Ваш идентификатор запроса. Возвращается в ответе и попадает в лог |
curl https://zerno.one/api/v1/chat/completions \
-H "Authorization: Bearer $ZERNO_API_KEY" \
-H "X-Title: Поддержка Ромашки" \
-H "X-Site-Url: https://romashka.ru" \
-H "X-Request-Id: ticket-48213-retry-1" \
-H "Content-Type: application/json" \
-d '{"model":"deepseek/deepseek-v3","messages":[…]}'В официальных SDK это default_headers — задаётся один раз при создании клиента:
client = OpenAI(
base_url="https://zerno.one/api/v1",
api_key=os.environ["ZERNO_API_KEY"],
default_headers={
"X-Title": "Поддержка Ромашки",
"X-Site-Url": "https://romashka.ru",
},
)Ключи разделяют доступ, заголовки — назначение. Одним ключом обычно ходят несколько частей системы: чат поддержки, ночная разметка, внутренний бот. Когда счёт вырос вдвое, вопрос «кто именно» без атрибуции решается перебором, а с ней — одной группировкой в логе активности.
Разделять ли трафик ключами или заголовками — вопрос того, что вы хотите ограничивать. Ключ несёт лимиты и отзывается отдельно; заголовок — только метка. Обычно правильный ответ — и то и другое.
X-Title мы используем только для того, чтобы вы сами разделяли расход по приложениям в активности. Наружу оно не выходит: публичного рейтинга приложений у нас нет, и в агрегированной статистике название не появляется. Это ваши коммерческие данные, а не наш контент.Если X-Request-Id не передан, мы генерируем свой и возвращаем его в том же заголовке и в теле ошибки. Свой удобнее: в него можно зашить номер тикета, попытку и стенд — и в обращении в поддержку достаточно назвать его, не пересказывая контекст.
Значение должно быть короче 128 символов и состоять из букв, цифр, дефисов и подчёркиваний. Персональные данные в него класть не надо: он живёт в логах дольше, чем сам запрос. Подробнее — в разделе «Данные и логи».