АПИ транскрипции

Эндпоинты защищены HMAC‑аутентификацией (см. Аутентификация). Все пути ниже начинаются с /v2.

Общий поток

1. (Опционально) Рассчитать стоимость: POST /transcriptions/calculate — [Контракт: calculateTranscriptionCost]
2. Создать транскрипцию и поставить задание в очередь: POST /transcriptions — [Контракт: createTranscription]
3. Проверять статус и забирать ссылки на результаты: GET /transcriptions/{id} где {id} - идентификатор транскрипции — [Контракт: getTranscription]. Либо получать уведомления по вебхукам (события transcription.completed, transcription.failed).
4. (Опционально) После завершения транскрипции — запросы к ИИ по тексту: POST /transcriptions/{id}/chat/completions (см. раздел ниже). Список моделей и общий чат — LLM.

Примеры

Все защищённые запросы требуют заголовков X-Public-Key, X-Timestamp, X-Signature.

1) Рассчитать стоимость — POST /v2/transcriptions/calculate

[Контракт: calculateTranscriptionCost]

TS=$(date +%s)
BODY='{"priority":"queue","duration":"00:05"}'
SIG=$(printf "%s\n%s" "$API_PUBLIC" "$TS" | openssl dgst -sha256 -hmac "$API_SECRET" -hex | sed 's/^.* //')

curl -sS -X POST "https://api.transcription.aiesa.ru/api/v2/transcriptions/calculate" \
  -H "Content-Type: application/json" \
  -H "X-Public-Key: $API_PUBLIC" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -d "$BODY"

Пример ответа 200 (сокращено):

{
  "durationSeconds": 120.5,
  "durationMinutes": 2.01,
  "minutesBilled": 3,
  "cost": 0.05,
  "balance": {
    "balance": 15000.5,
    "currency": "RUB",
    "credit_limit": 50000,
    "overdraft_enabled": true,
    "overdraft_used": 0,
    "available_credit": 65000.5,
    "tariff_plan": "regional_plus",
    "usage_current_month": {
      "minutes_lightning": 1250,
      "minutes_queue": 8500,
      "total_cost": 3125.5
    }
  }
}

2) Создать транскрипцию — POST /v2/transcriptions

[Контракт: createTranscription]

• Вариант А: загрузка файла (multipart/form-data, поле file)

TS=$(date +%s)
SIG=$(printf "%s\n%s" "$API_PUBLIC" "$TS" | openssl dgst -sha256 -hmac "$API_SECRET" -hex | sed 's/^.* //')

curl -sS -X POST "https://api.transcription.aiesa.ru/api/v2/transcriptions" \
  -H "X-Public-Key: $API_PUBLIC" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -F "file=@/path/to/meeting_record.mp3" \
  -F "language=ru" \
  -F "priority=queue" \
  -F "terms=AIESA, SLA, Whisper" \
  -F "prompt='Сделай саммари встречи'"

• Вариант Б: загрузка по URL (source_url)

TS=$(date +%s)
SIG=$(printf "%s\n%s" "$API_PUBLIC" "$TS" | openssl dgst -sha256 -hmac "$API_SECRET" -hex | sed 's/^.* //')

curl -sS -X POST "https://api.transcription.aiesa.ru/api/v2/transcriptions" \
  -H "X-Public-Key: $API_PUBLIC" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -F "source_url=https://example.com/audio.mp3" \
  -F "language=en" \
  -F "priority=lightning" \
  -F "terms=AIESA, roadmap, KPI"

Пример ответа 201 (сокращено):

{
  "transcription_id": "2f0b2f2a-5b07-4c3e-8a42-5c8a3f2b1e9d"
}

3) Получить транскрипцию — GET /v2/transcriptions/{id}

[Контракт: getTranscription]

TS=$(date +%s)
SIG=$(printf "%s\n%s" "$API_PUBLIC" "$TS" | openssl dgst -sha256 -hmac "$API_SECRET" -hex | sed 's/^.* //')

curl -sS "https://api.transcription.aiesa.ru/api/v2/transcriptions/2f0b2f2a-5b07-4c3e-8a42-5c8a3f2b1e9d" \
  -H "X-Public-Key: $API_PUBLIC" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG"

Пример ответа — статус «В процессе»:

{
  "data": {
    "id": "2f0b2f2a-5b07-4c3e-8a42-5c8a3f2b1e9d",
    "status": "processing",
    "progress": 65,
    "duration_seconds": 125.5,
    "duration_minutes": 2.09,
    "minutes_billed": 3,
    "priority_type": "queue",
    "filename": "meeting_record.mp3",
    "file_size": 15728640,
    "source_type": "upload",
    "language": "ru",
    "results": null,
    "ai_analysis": null,
    "error_message": null,
    "created_at": "2025-10-29T11:22:33Z",
    "started_at": "2025-10-29T11:23:01Z",
    "completed_at": null,
    "billed_at": null
  }
}

Пример ответа — статус «Готово» (с результатами):

{
  "data": {
    "id": "2f0b2f2a-5b07-4c3e-8a42-5c8a3f2b1e9d",
    "status": "completed",
    "progress": 100,
    "duration_seconds": 125.5,
    "duration_minutes": 2.09,
    "minutes_billed": 3,
    "cost": 2.1,
    "priority_type": "queue",
    "filename": "meeting_record.mp3",
    "file_size": 15728640,
    "source_type": "upload",
    "language": "ru",
    "results": {
      "text": "https://cdn.aiesa.ru/transcriptions/2f0b2f2a/text.txt",
      "json": "https://cdn.aiesa.ru/transcriptions/2f0b2f2a/result.json",
      "pdf": "https://cdn.aiesa.ru/transcriptions/2f0b2f2a/report.pdf"
    },
    "ai_analysis": {
      "model": "aiesa-mini",
      "prompt": "Ключевые моменты разговора",
      "text": "... краткое резюме ..."
    },
    "error_message": null,
    "created_at": "2025-10-29T11:22:33Z",
    "started_at": "2025-10-29T11:23:01Z",
    "completed_at": "2025-10-29T11:24:15Z",
    "billed_at": "2025-10-29T11:24:30Z"
  }
}

Чат по тексту транскрипции

После того как транскрипция завершена (status: completed и есть текст), можно отправлять запросы к ИИ по её тексту с сохранением контекста диалога.

Эндпоинт: POST /v2/transcriptions/{id}/chat/completions

[Контракт: transcriptionChatCompletion]

Тело запроса (JSON):

Поле	Тип	Обязательное	Описание
messages	array of string	да	Сообщения пользователя
model	string	нет	aiesa-mini (по умолчанию) или aiesa-pro
temperature	number	нет	0–2, по умолчанию 0.1
maxTokens / max_tokens	integer	нет	1–32000, по умолчанию из конфигурации API

Поведение: текст транскрипции подставляется в контекст LLM; история диалога хранится по транскрипции. Для aiesa-mini — 5 бесплатных запросов на транскрипцию; для aiesa-pro — платные. Если при создании была передана ai_prompt, она учитывается как один из пяти бесплатных запросов.

Формат ответа: как у POST /v2/chat/completions (стриминг, OpenAI-совместимые поля: id, object, created, model, choices, usage).

TS=$(date +%s)
BODY='{"messages":["Кратко перечисли ключевые решения из встречи"],"model":"aiesa-mini"}'
SIG=$(printf "%s\n%s" "$API_PUBLIC" "$TS" | openssl dgst -sha256 -hmac "$API_SECRET" -hex | sed 's/^.* //')

curl -sS -X POST "https://api.transcription.aiesa.ru/api/v2/transcriptions/2f0b2f2a-5b07-4c3e-8a42-5c8a3f2b1e9d/chat/completions" \
  -H "Content-Type: application/json" \
  -H "X-Public-Key: $API_PUBLIC" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -d "$BODY"

Коды ошибок: 400 — транскрипция не готова к чату; 402 — недостаточно средств; 403 — нет доступа; 404 — не найдена.