API-ключи
API-ключ авторизует внешние запросы к MashaGPT API и связывает эти запросы с балансом вашего аккаунта. Всё, что отправлено с ключом, считается запросом от владельца ключа.
Где создать и что сохранить
Создание
Создайте ключ в разделе API-ключи. Раздел требует авторизацию, потому что ключ привязан к аккаунту и балансу.
Secret
Полный secret показывается только один раз сразу после создания. MashaGPT не хранит восстановимую копию secret и не сможет показать его позже.
Mask
Mask нужен только для узнавания ключа в интерфейсе. По mask нельзя выполнить внешний API-запрос.
Hash
Hash используется внутри панели для выбора ключа, расхода и удаления. Это не замена secret для внешней интеграции.
Secret нельзя восстановить
Единственный момент, когда можно увидеть secret, — экран сразу после создания API-ключа. Если вы закрыли окно и не сохранили secret, восстановить его нельзя: создайте новый ключ, обновите переменные окружения на сервере и удалите старый ключ.
Как передавать ключ в запросе
Рекомендуемый header
x-api-key: YOUR_API_KEYАльтернатива
Authorization: Bearer YOUR_API_KEYЧто не передавать
Не передавайте browser cookies, user access token из веб-приложения, hash или mask ключа вместо secret.
curl -X POST "https://api.mashagpt.ru/v1/chat/completions" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"model": "gpt-5.5",
"messages": [
{"role": "user", "content": "Привет!"}
]
}'Где хранить ключ
Backend
Храните secret в переменных окружения сервера или secret manager. Telegram-бот, сайт и cron-задачи должны обращаться к MashaGPT API только с backend-сервера.
Frontend
Не вставляйте ключ в frontend, мобильное приложение, браузерный extension или публичный JavaScript bundle.
Логи
Не пишите полный ключ в логи, error tracking, аналитику, историю команд и скриншоты. Если нужно логировать, оставляйте только mask.
Окружения
Используйте разные ключи для production, staging, локальной разработки и разных проектов. Так проще отключить один контур без остановки остальных.
// .env на backend-сервере
MASHAGPT_API_KEY="YOUR_API_KEY"
// Node.js: ключ остается на сервере
const res = await fetch("https://api.mashagpt.ru/v1/chat/completions", {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-api-key": process.env.MASHAGPT_API_KEY
},
body: JSON.stringify({
model: "gpt-5.5",
messages: [{ role: "user", content: "Привет!" }]
})
});Какие endpoint работают с ключом
OpenAI-compatible
Полный URL
https://api.mashagpt.ru/v1/chat/completions. Используйте только для моделей, где на странице модели явно указан OpenAI-compatible endpoint.Anthropic Messages
Полный URL
https://api.mashagpt.ru/v1/messages. Для SDK, которые сами добавляют /v1/messages, base URL указывайте как https://api.mashagpt.ru.Tasks API
Генерация изображений, видео, аудио и файлов:
POST /v1/tasks/{model}, проверка результата: GET /v1/tasks/{id}.Storage
Загрузка файлов для API:
POST /v1/storage/upload. В ответе вернется URL, который передается в параметры модели.Файлы и референсы через API
В JSON-запрос модели не отправляется локальный файл с компьютера. Сначала загрузите файл в MashaGPT storage или используйте уже доступный публичный URL. Затем передайте URL в параметр конкретной модели: например imageUrls, imageUrl, audioUrl, videoUrl или fileUrls. Подробный контракт загрузки описан в разделе Загрузка файлов.
curl -X POST "https://api.mashagpt.ru/v1/storage/upload" \
-H "x-api-key: YOUR_API_KEY" \
-F "file=@./reference.png"curl -X POST "https://api.mashagpt.ru/v1/tasks/nano-banana-2" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"prompt": "Сделай рекламный баннер в стиле референса",
"imageUrls": ["https://static.mashagpt.ru/.../reference.png"],
"resolution": "2K",
"aspectRatio": "16:9"
}'Storage upload — это multipart, не JSON
Не отправляйте в модель или в storage строки
blob:http://..., file:///..., data:image/png;base64,... и сырые байты внутри JSON. Загрузка делается запросом multipart/form-data с одним полем file, а в модель передается только URL из ответа storage.Для chat-моделей не придумывайте параметры файлов
Если на странице конкретной chat-модели нет примера передачи файлов, не добавляйте в запрос произвольный
fileUrl. Для документов можно извлечь текст на своем backend и отправить его в messages. Нативную передачу файлов используйте только там, где она явно описана в документации модели.Списания и контроль
Баланс
Запросы с API-ключом списывают стоимость с API-баланса аккаунта, которому принадлежит ключ.
Тестирование
Playground выполняет реальные запросы через выбранный ключ. Если ключей несколько, выбирайте нужный ключ перед запуском.
Расход
Проверяйте расход по ключам в разделе «Расход». Для изоляции проектов создавайте отдельные ключи.
Оповещения
Используйте раздел «Оповещения», чтобы заранее видеть аномальный или слишком высокий расход.
Если ключ утек
1. Удалите ключ
Удалите скомпрометированный ключ в разделе «API-ключи». Запросы с ним должны перестать работать.
2. Создайте новый
Создайте новый ключ. Новый secret будет показан только один раз: сразу сохраните его в переменные окружения ваших backend-сервисов.
3. Проверьте расход
Проверьте историю расхода и платежей, чтобы понять, были ли несанкционированные запросы.