# neuraldeep.ru — LLM API reference (для coding-агентов)

> Полная машиночитаемая справка. Curl-friendly: `curl https://neuraldeep.ru/llms-full.txt`.
> Индекс с указателями: `https://neuraldeep.ru/llms.txt`. Человеческая версия: `https://neuraldeep.ru/docs`.
> Пагинация: документ один (~умещается в контекст). Секции разделены заголовками `## <name>` —
> грепай по ним для выборочного чтения (`## Chat`, `## Embeddings`, `## Search API`, `## OCR API`, ...).

Base URL: `https://api.neuraldeep.ru/v1` (OpenAI-совместимый)
Auth: `Authorization: Bearer $YOUR_KEY`

Available models:
- `gpt-oss-120b` — chat · tools · reasoning · 131k ctx · MXFP4 на 2×RTX 4090 48 GB
- `qwen3.6-35b-a3b` — chat · qwen3 tools · reasoning · 256k ctx · MoE 35B/3B-active · BF16 на 2× RTX 4090 48GB · vision (1 image/prompt)
- `gemma-4-31b` — chat · tools · multimodal (image/video) · 262k ctx · Google Gemma 4 · на наших серверах в РФ
- `e5-large` — multilingual embedding · 1024-dim · 3 replicas
- `bge-m3` — multilingual embedding · 1024-dim · 8k ctx
- `bge-reranker` — cross-encoder rerank
- `whisper-1` — WhisperX large-v3-turbo · multilingual · word timestamps · RTF ~16×

## Chat
```
POST /v1/chat/completions
{
  "model": "gpt-oss-120b",
  "messages": [{"role":"user","content":"..."}],
  "max_tokens": 500,
  "temperature": 0.3
}
```
Note: у gpt-oss reasoning-токены — ставь max_tokens >= 300, иначе content пустой.
Session sticky: шли `user: <session_id>` → роутер закрепит сессию на одном upstream (prefix cache warm, до 10× экономия).

## Embeddings
```
POST /v1/embeddings
{"model": "e5-large", "input": ["text1","text2"]}
```
Response: `{"data": [{"embedding": [...], "index": 0}], ...}`. dim=1024 для обеих моделей. Кешируется (deterministic).

## Rerank
```
POST /v1/rerank
{"model":"bge-reranker","query":"...","documents":["doc1","doc2"]}
```
Response: `{"results": [{"index": 0, "relevance_score": 0.87}, ...]}` — отсортировано по релевантности.

## Transcription
```
POST /v1/audio/transcriptions   (multipart)
file=@audio.wav
model=whisper-1
```
Response: `{"text": "...", "language": "ru", "duration": 12.3, "segments": [...]}`.

## Vision
Картинку шлёшь инлайн в сообщение (OpenAI-формат `image_url`, поддержаны `data:`-base64 и https-URL). VL-модели: `qwen3.6-35b-a3b` (1 изображение/промпт) и `gemma-4-31b` (multimodal). `gpt-oss-120b` картинки НЕ принимает.
```
POST /v1/chat/completions
{
  "model": "qwen3.6-35b-a3b",
  "messages": [{"role":"user","content":[
    {"type":"text","text":"Что на картинке?"},
    {"type":"image_url","image_url":{"url":"data:image/png;base64,..."}}
  ]}],
  "max_tokens": 500
}
```

## Structured output
```
POST /v1/chat/completions
{
  "model": "gpt-oss-120b",
  "messages": [...],
  "response_format": {"type":"json_schema","json_schema":{"name":"...","schema":{...},"strict":true}}
}
```
vLLM гарантирует strict JSON при strict:true.

## Tools (agents)
Стандартный OpenAI tool-calling с `tools` + `tool_choice`.
```
{
  "model": "gpt-oss-120b",
  "messages": [...],
  "tools": [{"type":"function","function":{"name":"...","parameters":{...}}}],
  "tool_choice": "auto"
}
```
Ответ: `choices[0].message.tool_calls`.

## Streaming
Добавь `"stream": true` → SSE поток с `data: {...}` чанками, последний `data: [DONE]`.

## Search API
Тот же `sk-` ключ, доступен всем тарифам (вкл. free). Отдельная two-pool квота (search/crawl) — НЕ тратит LLM-лимиты. Ответ — passthrough + `{"quota":{...}}`; исчерпание → 429 + `X-Quota-Pool/Scope/Limit/Reset` + `Retry-After`.
```
GET  /v1/search/tg?q=&sources=vector,fts&channels=&limit=   # поиск по базе ТГ-каналов (пул search)
POST /v1/search/web   {query,limit,provider?,region?}        # поиск по интернету (пул search)
POST /v1/search/read  {url}                                  # чтение одной страницы (пул crawl)
POST /v1/search/crawl {url,limit}                            # краулинг сайта (пул crawl)
GET  /v1/search/quota                                        # снапшот квоты без инкремента
```
```bash
curl -H "Authorization: Bearer $YOUR_KEY" "https://api.neuraldeep.ru/v1/search/tg?q=нейросети&limit=5"
curl -X POST -H "Authorization: Bearer $YOUR_KEY" -H "Content-Type: application/json" \
  https://api.neuraldeep.ru/v1/search/web -d '{"query":"openai news","limit":3}'
```

## OCR API
Тот же `sk-` ключ, квота в scan-страницах (НЕ тратит LLM-лимиты). Асинхронный flow: загрузил → поллишь статус (не чаще 1/сек) → забрал результат. Профили `fast` (1 стр/стр, дефолт) / `pro` (2 стр/стр). `job_id` привязан к юзеру (чужой → 404).
```
POST /v1/ocr/extract  (multipart: file, page_ranges?, model_profile?)  # → {id, page_count, status, scan_pages_charged}
GET  /v1/ocr/jobs/{id}                                                 # статус pending→running→completed
GET  /v1/ocr/jobs/{id}/result?format=markdown|json|text                # результат (202 если не готов)
GET  /v1/ocr/jobs/{id}/pages/{n}/preview                               # PNG страницы (та же СК что bbox)
GET  /v1/ocr/balance                                                   # остаток страниц
```
```bash
curl -X POST -H "Authorization: Bearer $YOUR_KEY" -F "file=@invoice.pdf" https://api.neuraldeep.ru/v1/ocr/extract
curl -H "Authorization: Bearer $YOUR_KEY" "https://api.neuraldeep.ru/v1/ocr/jobs/job_123/result?format=markdown"
```

## Image API
Тот же `sk-` ключ, квота в операциях (НЕ тратит LLM-лимиты). Генерация/обработка картинок (FLUX и др.): generate / upscale / background-remove / enhance / avatar. Async: submit → poll → result. Промпт можно на русском (авто RU→EN перевод).
```
POST /v1/images/generations  {prompt, ...}     # → {id, status}
GET  /v1/images/jobs/{id}                       # статус
GET  /v1/images/jobs/{id}/result                # результат (URL/base64)
GET  /v1/images/quota                           # остаток операций
```
Подробнее по операциям/параметрам — `https://neuraldeep.ru/docs#images`.

## Drift API (персональный агент)
Отдельный продукт: AI-агент с памятью/скиллами/sandbox. Своя авторизация — токен `dft_*` (НЕ `sk-`). Полная справка: `https://neuraldeep.ru/docs#drift-api` (чат, файлы+sandbox, свои tools/skills/MCP, задачи/proactive, память, изоляция).

## Лимиты
Два окна счёта запросов: `session` (текущее 3-часовое окно UTC) и `week` (ISO-неделя). Конкретные цифры абстрагированы — программируй ретраи по headers ответа.
При исчерпании `session` — cooldown 2h (`Retry-After: 7200`, `X-Window: session`). При исчерпании `week` — ждёшь до понедельника 00:00 UTC (`X-Window: week`). На каждый ответ — `X-Tier`, `Retry-After`, `X-Window`.

## Pricing (для расчёта бюджета)
- gpt-oss-120b / qwen3.6: $0.05 input · $0.20 output per 1M tokens
- gemma-4-31b: $0.12 input · $0.36 output per 1M tokens
- e5-large / bge-m3: $0.03 input per 1M
- whisper: $0.003 per min

## Python SDK
```python
from openai import OpenAI
client = OpenAI(api_key="$YOUR_KEY", base_url="https://api.neuraldeep.ru/v1")
r = client.chat.completions.create(model="gpt-oss-120b", messages=[...], max_tokens=500)
```

## JS SDK
```typescript
import OpenAI from "openai";
const client = new OpenAI({ apiKey: "$YOUR_KEY", baseURL: "https://api.neuraldeep.ru/v1" });
```

## Errors
- 401 auth_error → bad / revoked key
- 401 key_model_access_denied → key не подписан на эту модель (см свой dashboard)
- 429 rate_limit → headers `X-Window: session|week` + `Retry-After: <sec>`
- 429 quota_exceeded → Search/OCR/Image квота, `X-Quota-Pool/Scope` + `Retry-After`
- 502 bad_gateway → upstream временно недоступен (LiteLLM делает retry × 2 — обычно само проходит)
- 400 context_window_exceeded → укоротить messages

## Privacy
По умолчанию prompts/responses не хранятся. В Dashboard два независимых toggle:
- Хранение истории запросов (default OFF) — если включить, тело запроса/ответа остаётся в БД и видно тебе в логах. Если выключено — тело удаляется сразу после обработки, в БД только метрики (модель, токены, статус, latency).
- Разрешить аналитику запросов — если включено, мы LLM-классифицируем тип запроса (код/ресёрч/агент) для развития сервиса; тело используется только для классификации и сразу удаляется. Если выключено — тело не читается, категоризация только по типу endpoint'а.
На моделях не обучаемся, данные не продаём. Метрики (latency, токены, статус) собираются всегда обезличенно через Prometheus.