← Все разделы

API

Все запросы идут в шлюз с заголовком x-api-key. Адрес шлюза зависит от сети; актуальный для вашего нейронета показан на вкладке «Endpoint».

Эндпоинт

Инференс: POST /n/:neuronetId/v1/:taskId/infer. Потоковый вариант — тот же путь с суффиксом /stream, ответ приходит серверными событиями (SSE) по мере генерации; учтите, что на стриме отказ приходит уже внутри потока, а не HTTP-статусом. Статус верификации запроса: GET /n/:neuronetId/v1/requests/:requestId.

curl -X POST "https://gateway-testnet.aetron.ai/n/<neuronetId>/v1/<taskId>/infer" \
  -H "x-api-key: ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"input": "Explain Contour 2 briefly."}'

Запрос и ответ

Минимальное тело — JSON с единственным полем input (пример ниже). Диалог и параметры генерации передаются внутри того же поля input конвертом с полями aetron, messages и params — так вход целиком попадает под input_hash, и верификатор пересчитывает ровно тот же запрос.

Ответ: id запроса (64 hex без префикса), output (текст) и verification. Двоичный результат приходит парой output_b64 + content_type вместо output, а тяжёлый (видео, крупные картинки) — полем output_url: подписанной ссылкой на файл, которая живёт сутки; content_type при этом заполнен.

// request: dialogue + params travel INSIDE the input field (one JSON-encoded string)
{
  "input": "{\"aetron\":1,\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}],\"params\":{\"max_tokens\":256}}"
}

// response (id: 64 hex digits, no prefix)
{
  "id": "9f3c1a…",
  "output": "…",
  "verification": { "status": "pending", "receipt": "vrc_…" }
}

OpenAI- и Anthropic-совместимые маршруты

У LLM-задач эндпоинт доступен и в синтаксисе OpenAI и Anthropic — SDK подключается сменой base_url: …/n/:neuronetId/v1/:taskId/openai/v1 (SDK допишет /chat/completions; ключ принимается и как Authorization: Bearer) и …/n/:neuronetId/v1/:taskId/anthropic (SDK допишет /v1/messages; ключ — в привычном x-api-key). Это чистый переводчик: тело транслируется в тот же конверт messages/params, который хэшируется и пересчитывается при проверке, — все гейты и квоты действуют как обычно, а в ответе едет дополнительное поле aetron с id запроса и ссылкой на квитанцию верификации. Стриминг поддержан в формате обоих провайдеров. Что не поддержано — отклоняется явной ошибкой 422, а не проглатывается: tools, response_format со схемой, n>1, картинки в сообщениях. Поле usage — оценка (байты/4): точных счётчиков токенов контур не возвращает. Маршруты отвечают только задачам типа inference; диффузии и обучению — отказ.

Ключи

Секрет ключа показывается один раз при выпуске и хранится на платформе только хешем. Ключ можно ограничить одной задачей — без задачи он работает со всеми задачами нейронета. Дневной бюджет запросов по умолчанию — 10 000 на ключ, если тариф не задал свой (0 = без лимита); при исчерпании шлюз отвечает 429 quota_exceeded с полем reset_at, бюджет возвращается в полночь UTC. Ротация выпускает новый секрет с теми же настройками. Отзыв и правка ключа доезжают до шлюза за время его кэша вердиктов — не дольше минуты.

Ограничение по IP

До 32 записей на ключ — отдельные адреса или CIDR-подсети (IPv4 и IPv6). Пустой список — без ограничений. Проверку выполняет шлюз и на чужой адрес отвечает 403 ip_not_allowed; адрес клиента используется только в момент проверки и нигде не сохраняется. Список правится без смены секрета; ротация его наследует.

Потолки

Четыре независимых потолка, каждый со своим кодом: частота запросов (429 rate_limited, с Retry-After), дневной бюджет ключа (429 quota_exceeded, сброс в полночь UTC), пакет запросов тарифа нейронета на хостинге за период (429 plan_quota_exhausted, обновляется со следующим периодом тарифа — повтор до этого получит тот же ответ) и ончейн-бюджет AWU нейронета на день цепи, который растёт со стейком и начинается заново каждый день цепи (429 capacity_exceeded, в ответе capacity/used/reset_epoch). Ещё два 429 — короткое ожидание, а не потолок: miner_busy и duplicate_in_flight.

Коды ошибок

Ошибки самого шлюза несут машинный код в поле error — полный список в таблице ниже. Отказы разбора запроса (нечитаемый JSON, отсутствующее поле input, неверный Content-Type, слишком большое тело) приходят статусами 400/413/415/422 с текстовым телом, без этого поля.

HTTPerror
401unauthorizedнет или неверный x-api-key
402tenant_suspendedmanaged-размещение приостановлено (подписка не оплачена)
403ip_not_allowedадрес клиента не входит в IP-список ключа
403not_ownerдействие доступно только владельцу нейронета
404not_foundтого, что назван путь, нет: на инференсе — у нейронета нет такой задачи; в остальных путях — нет такого прогона, роя или загруженного файла
409neuronet_frozenтакого нейронета нет или он снят с регистрации (замороженный нейронет обслуживается — см. раздел «Жизненный цикл»)
409neuronet_dissolvingнейронет распускается и новую работу не принимает
409task_stoppingзадача останавливается (запрошено её удаление) и новых запросов не принимает
409conflictсостояние не позволяет выполнить действие (например, повторный запуск уже идущего прогона)
422bad_inputтело разобрано, но содержимое не годится
422input_refusedни один майнер задачи не принимает такой вход (например, файл формата, который модель не читает); причина — в ответе
429rate_limitedслишком часто; повторите после Retry-After
429quota_exceededдневной бюджет ключа исчерпан; сброс в полночь UTC (reset_at в ответе)
429plan_quota_exhaustedпакет запросов тарифа на хостинге за период исчерпан; он обновится со следующим периодом тарифа
429capacity_exceededбюджет AWU нейронета на этот день цепи исчерпан; он растёт со стейком и начинается заново со следующим днём цепи
429miner_busyмайнеры задачи сейчас заняты; повторите после Retry-After
429duplicate_in_flightтот же запрос уже исполняется; спросите снова после Retry-After, а не отправляйте второй
500internalвнутренний сбой шлюза — не читается конфигурация задачи или состояние запроса
502miner_errorмайнер ответил ошибкой исполнения; текст причины — в ответе
503no_miner_availableнет доступного майнера под задачу
503overloadedшлюз перегружен; быстрый честный отказ вместо деградации
503chain_unavailableнода цепи недоступна; состояние нейронета не прочитано
503storage_unavailableхранилище артефактов шлюза не ответило; повторите позже
504miner_timeoutмайнер не ответил в срок