# SpeechCore · транскрибация аудио/видео — neuraldeep.ru API

> Раздел машиночитаемой справки. Все разделы: https://neuraldeep.ru/llms.txt · всё одним файлом: https://neuraldeep.ru/llms-full.txt

Base URL: `https://speechcore.neuraldeep.ru/api`
Auth: `Authorization: Bearer $YOUR_KEY`

Отдельный сервис [speechcore.neuraldeep.ru](https://speechcore.neuraldeep.ru) — транскрибация длинных аудио и видео (файл до 2 ГБ): диаризация спикеров, тайм-коды по словам, экспорт SRT/VTT/TSV/DOCX/PDF. В вебе — вход через тот же Hub-аккаунт; **по API — тем же `sk-*` ключом**, что и для `/v1/*`. Для коротких аудио и OpenAI-совместимости есть также синхронный `whisper-1` (раздел «Транскрибация» выше) — SpeechCore же заточен под длинные записи и диаризацию.

База API — `https://speechcore.neuraldeep.ru/api` (НЕ `api.neuraldeep.ru`). Лимит считается в **транскрипциях в день**, свой остаток ключ видит в `GET /usage` (поля `used_today`, `daily_limit`, `remaining`). Сверх лимита загрузка проходит с оплатой по минутам, если на кошельке есть деньги. Иначе придёт `429` с текстом про сброс («Сброс в 00:00 UTC (03:00 МСК).») и заголовком `Retry-After` до полуночи UTC. Работает **асинхронно**: `POST /upload` → `{task_id}` → опрашиваешь `GET /transcriptions/{id}/status` пока `status=completed` → забираешь результат: `GET /transcriptions/{id}` (JSON с сегментами, спикерами, `detected_language`, `duration`) или `GET /transcriptions/{id}/markdown` (текст с тайм-кодами).

**Опции транскрибации** — query-параметры к `POST /upload` (файл — в multipart-теле, опции — в URL):

- `diarize=true` — **разделение по спикерам**: в сегментах появляется поле `speaker` (`SPEAKER_00`, `SPEAKER_01`…), а в саммари — % времени говорения каждого. `diarize_speakers_num=N` (1–20) — подсказать точное число голосов, если оно известно (точнее, чем автоопределение).
- `language=ru` — зафиксировать язык (по умолчанию — автоопределение).
- **Спец-слова / терминология:** `hotwords` — ключевые слова через пробел или запятую (≤500 симв.), которые модель будет распознавать точнее: имена, бренды, аббревиатуры, продукты (`NeuralDeep, Kimi, RAG, ФЗ-152`).
- `initial_prompt` — контекст-промпт (≤2000 симв.): задаёт тематику/стиль и повышает точность на специфической лексике (`«Технический созвон про LLM-инфраструктуру»`).

**Ошибки `POST /upload`.** `task_id` приходит только в ответе 200, поэтому сначала проверяй статус. При ошибке тело — `{"detail": "..."}` с причиной: **400** — неподдерживаемый формат файла (принимаются wav, flac, aiff, mp3, m4a, aac, ogg, oga, opus, wma, amr, mp4, m4v, mov, avi, mkv, webm, wmv, flv, 3gp, mpg, mpeg, ts), **401** — ключ неверный или отозван, **422** — параметр вне допустимых значений (например, `diarize_speakers_num` не в 1–20), **429** — исчерпан дневной лимит и на кошельке нет денег, **503** — сервис временно недоступен, повтори запрос позже.

```bash
# опции — в query-строке URL, файл — в multipart-теле (-F)
curl -s "https://speechcore.neuraldeep.ru/api/upload?diarize=true&diarize_speakers_num=3&language=ru&hotwords=NeuralDeep,Kimi,RAG&initial_prompt=Технический%20созвон%20про%20LLM" \
  -H "Authorization: Bearer $YOUR_KEY" \
  -F "file=@meeting.mp3"
```

```bash
# 1. загрузить (тот же sk-ключ, что и для /v1/*)
tid=$(curl -s https://speechcore.neuraldeep.ru/api/upload \
  -H "Authorization: Bearer $YOUR_KEY" \
  -F "file=@meeting.mp3" | jq -r .task_id)

# 2. статус
curl "https://speechcore.neuraldeep.ru/api/transcriptions/$tid/status" \
  -H "Authorization: Bearer $YOUR_KEY"

# 3. результат текстом (markdown с тайм-кодами)
curl "https://speechcore.neuraldeep.ru/api/transcriptions/$tid/markdown" \
  -H "Authorization: Bearer $YOUR_KEY"

# свои транскрипции списком
curl "https://speechcore.neuraldeep.ru/api/transcriptions?limit=20" \
  -H "Authorization: Bearer $YOUR_KEY"
```

```python
import time, httpx

BASE = "https://speechcore.neuraldeep.ru/api"
H = {"Authorization": "Bearer $YOUR_KEY"}

# 1. загрузка файла (аудио/видео, до 2 ГБ) + опции в params
params = {
    "diarize": "true",            # разделение по спикерам
    "diarize_speakers_num": 3,    # если число голосов известно
    "language": "ru",
    "hotwords": "NeuralDeep, Kimi, RAG",          # спец-слова/термины
    "initial_prompt": "Технический созвон про LLM",
}
with open("meeting.mp3", "rb") as f:
    r = httpx.post(f"{BASE}/upload", headers=H, params=params, files={"file": f}, timeout=300)
# task_id есть только в ответе 200; при ошибке тело — {"detail": "..."} с причиной
if r.status_code != 200:
    raise RuntimeError(f"upload {r.status_code}: {r.text}")
tid = r.json()["task_id"]

# 2. поллинг (раз в пару секунд)
while True:
    st = httpx.get(f"{BASE}/transcriptions/{tid}/status", headers=H)
    st.raise_for_status()
    st = st.json()
    if st["status"] in ("completed", "failed"):
        break
    time.sleep(2)

# 3. результат: сегменты + тайм-коды, или готовый markdown
data = httpx.get(f"{BASE}/transcriptions/{tid}", headers=H).json()
print("язык:", data["detected_language"], "длительность:", data["duration"])
print(httpx.get(f"{BASE}/transcriptions/{tid}/markdown", headers=H).text)
```

**Возможности в веб-интерфейсе** ([speechcore.neuraldeep.ru](https://speechcore.neuraldeep.ru)), помимо API:

- **Диаризация спикеров** — реплики размечены по говорящим (SPEAKER_00…), видно кто сколько говорил (% времени).
- **Саммари встречи** — структурированное LLM-резюме (темы, решения, задачи) с учётом спикеров. Тем же sk-ключом.
- **Чат по транскрипту** — вопросы к расшифровке («что решили по X?», «какие дедлайны?») с ответами по тайм-кодам.
- **Экспорт** — SRT · VTT · TSV · DOCX · PDF · TXT, плюс markdown с тайм-кодами.
- **Спец-слова и контекст** — поля hotwords / контекст-промпт прямо в форме загрузки (то же, что `hotwords`/`initial_prompt` в API).
- **Публичная ссылка** — поделиться транскриптом на чтение без входа.
- **Realtime** — потоковая транскрибация с микрофона/вкладки (через расширение «Meeting Recorder»).

> Поллинг и выдача результата лимит не списывают — он тратится только при загрузке (1 файл = 1 транскрипция). Файл до 2 ГБ, загрузка должна уложиться в 30 минут; крупные файлы грузи целиком — обработка идёт в фоне на GPU, поэтому держи разумный таймаут на поллинге. Диаризация и спец-слова работают и в вебе, и по API одинаково.