Служебные API

Когда использовать служебные API

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

Во всех примерах используйте серверную переменную ELYSIUM_API_KEY со значением sk-… и заголовок Authorization: Bearer sk-…. Для JSON POST добавьте Content-Type: application/json. Пути /api/... идут от корня сайта, а не от Base URL с /v1.

Ниже показаны форматы ответов из обработчиков API; некоторые ответы сокращены до значимых полей. ID, суммы, тарифы и числа токенов в примерах иллюстративные: текущие значения берите из ответа.

Оценка скрытого промпта провайдера

В обычных текстовых ответах Chat Completions, Responses, Anthropic Messages и Gemini generateContent заголовок X-Elysium-Provider-Prompt-Tokens содержит оценку дополнительных входных токенов: вход, сообщённый провайдером с учётом cache read/write, минус наш локальный подсчёт запроса. Заголовок появляется только для запроса без медиа, когда локальная оценка больше нуля, а разница строго больше 200 токенов и 30% сообщённого входа; иначе его нет.

В поддерживаемых OpenAI, Anthropic и Responses SSE-потоках перед data: [DONE], message_stop или response.completed приходит строка комментария : x-elysium-provider-prompt-tokens=<N>. SSE-парсеры игнорируют комментарии; JSON-схема ответа не меняется. Нативный Gemini SSE этот комментарий не передаёт.

В GET /api/log/token те же данные доступны внутри JSON-строки other: provider_prompt_overhead_tokens — оценка дополнительных токенов, estimated_prompt_tokens — наш подсчёт запроса. При разборе other используйте JSON.parse. Заголовок доступен браузерным клиентам через Access-Control-Expose-Headers.

1X-Elysium-Provider-Prompt-Tokens: 6002 3: x-elysium-provider-prompt-tokens=600

GET /v1/balance — баланс аккаунта

Authorization: Bearer sk-…. Параметров нет. Бесплатно; возвращает кошелёк владельца ключа, независимо от индивидуального бюджета ключа.

1curl "https://elysiumai.garden/v1/balance"   -H "Authorization: Bearer $ELYSIUM_API_KEY"

GET /v1/models и /v1/models/{model} — модели

Authorization: Bearer sk-…. Список не требует параметров; для одной модели передайте её точный ID без / в пути. Для ID с / найдите запись в полном списке. Оба вызова бесплатны. Список учитывает доступ пользователя и ограничения ключа; общий ID семейства позволяет автоматический выбор варианта.

1curl "https://elysiumai.garden/v1/models"   -H "Authorization: Bearer $ELYSIUM_API_KEY"

GET /v1/model-options — варианты и тарифы

Authorization: Bearer sk-…. Параметров нет, вызов бесплатный. Возвращает доступные для ключа варианты с розничными ценами; полный options[].id можно передать в поле model для выбора конкретного варианта.

1curl "https://elysiumai.garden/v1/model-options"   -H "Authorization: Bearer $ELYSIUM_API_KEY"

POST /v1/media/quote — цена медиаоперации

Authorization: Bearer sk-… и Content-Type: application/json. Тело содержит model, operation, prompt и input с параметрами выбранной операции. Вызов бесплатный: задача не создаётся и баланс не списывается. JSON ограничен 1 MiB.

Используйте публичные HTTPS URL для входных файлов. Предварительный расчёт не загружает локальные файлы и не раскрывает ссылки на предыдущие task ID. Разрешение, длительность и другие поля input зависят от схемы модели.

1curl "https://elysiumai.garden/v1/media/quote"   -H "Authorization: Bearer $ELYSIUM_API_KEY"   -H "Content-Type: application/json"   -d '{"model":"openai/gpt-image-2","operation":"text-to-image","prompt":"A garden","input":{"resolution":"1K"}}'

POST /v1/messages/count_tokens — оценка входа

Authorization: Bearer sk-… и Content-Type: application/json. Передайте Anthropic Messages JSON: обязательный model, сообщения messages, при необходимости system и tools. Бесплатный локальный расчёт: провайдер не вызывается.

1curl "https://elysiumai.garden/v1/messages/count_tokens"   -H "Authorization: Bearer $ELYSIUM_API_KEY"   -H "Content-Type: application/json"   -d '{"model":"your-claude-model-id","messages":[{"role":"user","content":"Hello!"}]}'

GET /api/usage/token/ — бюджет ключа

Authorization: Bearer sk-…. Параметров нет. Бесплатно; возвращает сведения только о переданном ключе. Read-only авторизация допускает существующий выключенный, истёкший или исчерпанный ключ, если аккаунт активен. Удалённый ключ не работает.

1curl "https://elysiumai.garden/api/usage/token/"   -H "Authorization: Bearer $ELYSIUM_API_KEY"

GET /api/usage/self/requests — история аккаунта

Authorization: Bearer sk-…. Бесплатно; история всего аккаунта, а не только текущего ключа. Необязательные start_timestamp и end_timestamp — Unix seconds, начало включительно, конец исключительно. По умолчанию последние 30 дней; период не более 90 дней, конец не далее чем на сутки в будущем.

1curl "https://elysiumai.garden/api/usage/self/requests?limit=50"   -H "Authorization: Bearer $ELYSIUM_API_KEY"

GET /api/usage/self/summary — расход за период

Authorization: Bearer sk-…. Бесплатно; история всего аккаунта, а не только текущего ключа. Необязательные start_timestamp и end_timestamp — Unix seconds, начало включительно, конец исключительно. По умолчанию последние 30 дней; период не более 90 дней, конец не далее чем на сутки в будущем.

1curl "https://elysiumai.garden/api/usage/self/summary"   -H "Authorization: Bearer $ELYSIUM_API_KEY"

GET /api/log/token — последние записи ключа

Authorization: Bearer sk-…. Параметров нет, вызов бесплатный. Возвращает последние записи только данного ключа, без пагинации. Для новой интеграции с историей всего аккаунта удобнее /api/usage/self/requests.

1curl "https://elysiumai.garden/api/log/token"   -H "Authorization: Bearer $ELYSIUM_API_KEY"

GET /v1/dashboard/billing/subscription — legacy-лимит

Authorization: Bearer sk-…. Параметров нет, вызов бесплатный. Алиас: /dashboard/billing/subscription. Формат совместимости старых OpenAI-клиентов; это не перечень подписок и не создание подписки.

1curl "https://elysiumai.garden/v1/dashboard/billing/subscription"   -H "Authorization: Bearer $ELYSIUM_API_KEY"

GET /v1/dashboard/billing/usage — legacy-расход

Authorization: Bearer sk-…. Параметров нет, вызов бесплатный. Алиас: /dashboard/billing/usage. start_date и end_date не обрабатываются: возвращается весь накопленный расход.

1curl "https://elysiumai.garden/v1/dashboard/billing/usage"   -H "Authorization: Bearer $ELYSIUM_API_KEY"

Статус медиа-задач и скачивание видео

Authorization: Bearer sk-…. Бесплатные GET для уже созданной задачи: /v1/videos/{task_id}, /v1/video/generations/{task_id}, /v1/audio/generations/{task_id} и /v1/videos/{task_id}/content. Единственный параметр — публичный task_id вашей задачи в пути.

Для видео /v1/videos/{task_id} возвращает OpenAI video JSON; /v1/video/generations/{task_id} — оболочку code/message/data с task_id, status, progress и result_url в data. Для аудио возвращаются object=audio.generation, id, task_id, model, status, created_at и tracks; у готового трека есть id и url, иногда duration. Ошибки аудио находятся в error, расчёт — в billing.

content возвращает бинарный файл готового видео, а не JSON. Сохраняйте его через curl -o. Сам GET не создаёт новую платную задачу; оплата исходной генерации происходит при её завершении. Проверяйте статус раз в 3–5 секунд, останавливайтесь на completed / failed.

1curl "https://elysiumai.garden/v1/videos/$TASK_ID"   -H "Authorization: Bearer $ELYSIUM_API_KEY"

Каталог для Anthropic и Gemini

Authorization: Bearer sk-…. Все перечисленные GET бесплатны. Параметров у списков нет, {model} — точный ID без / в пути. Для ID с / используйте полный список. Anthropic: /anthropic/v1/models и /anthropic/v1/models/{model}; также GET /v1/models с x-api-key: sk-… и anthropic-version: 2023-06-01 возвращает Anthropic-список.

Gemini-список: /v1beta/models и /compatible/v1beta/models. Ответ содержит models и nextPageToken; name / baseModelId — ID модели, supportedGenerationMethods — поддерживаемые методы. /compatible/v1beta/models/{model} возвращает одиночный OpenAI model JSON из раздела выше.

OpenAI-формат списка также доступен по /v1beta/openai/models, /compatible/v1beta/openai/models, /compatible/v1/models и /compatible/models. Формат ответа такой же, как у /v1/models.

1curl "https://elysiumai.garden/anthropic/v1/models"   -H "Authorization: Bearer $ELYSIUM_API_KEY"

Совместимое чтение задач Suno и Midjourney

Authorization: Bearer sk-…. Вызовы читают только задачи владельца ключа, не запускают генерацию и не списывают баланс. Они полезны для существующих интеграций; наличие пути не означает доступность модели для новой генерации.

GET /suno/fetch/{id} принимает ID задачи в пути и возвращает code=success, message и data с task_id, status, progress. POST /suno/fetch принимает JSON {"ids":["task-id"]}; data — массив таких задач, [] при пустом ids. Поле action принимается, но не фильтрует ответ.

GET /mj/task/{id}/fetch возвращает объект задачи: id, status, progress, imageUrl, failReason и другие поля Midjourney. POST /mj/task/list-by-condition принимает JSON {"ids":["task-id"]} и возвращает массив таких объектов; пустой ids даёт []. GET /mj/task/{id}/image-seed возвращает code, description, properties и result с seed; для него нужен доступный канал исходной задачи. Поддерживаются те же пути с префиксом /{mode}/mj.

1curl "https://elysiumai.garden/suno/fetch/$TASK_ID"   -H "Authorization: Bearer $ELYSIUM_API_KEY"

Лимиты и ошибки служебных вызовов

Лимиты настраиваются сервером: не фиксируйте в клиенте число запросов из примера. /v1/models, одиночная модель и /v1/model-options делят окно models по IP; /v1/balance имеет отдельное окно balance. Превышение любого из этих окон может временно заблокировать IP на обоих endpoint.

Для защищённых моделей и баланса смотрите X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset (Unix seconds). При блокировке ответ 429 содержит Retry-After в секундах; администратор может закрыть endpoint с ответом 503. Общий API-лимит и critical-лимит тоже считаются по IP, когда включены.

Кэшируйте каталог, ограничивайте частоту мониторинга и повторяйте 429 с задержкой. При 401 проверьте ключ; при 403 — доступ и IP-ограничения. Бесплатность служебного вызова не отменяет авторизацию и лимиты.