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