API

API Спичи для разработчиков

Расшифровка аудио и видео, резюме встреч и шаблоны резюме — через простой HTTP API. Базовый URL: https://external-api.sp-summary.org/api/v1

Аутентификация

Каждый запрос подписывается API-ключом. Передайте ключ в заголовке Authorization: Bearer <ключ> или X-API-Key: <ключ>.

Ключ имеет формат sp_summary_ + 32 символа и выдаётся самостоятельно в настройках кабинета (app.sp-summary.org, раздел «API-ключи»). Полный ключ показывается один раз при создании — сохраните его. До 5 активных ключей на аккаунт; отозванный ключ сразу перестаёт работать (401).

Держите ключ в секрете: он даёт полный доступ к задачам вашего аккаунта. В интерактивных примерах на этой странице ключ хранится только в вашем браузере и отправляется напрямую в API Спичи.

Эндпоинты

GET/task

Список задач

Возвращает задачи на транскрибацию вашего аккаунта с пагинацией, от новых к старым.

Query-параметры

Параметр	Тип	Описание
`page`	number	Номер страницы, по умолчанию 1

Пример ответа

{
  "tasks": [
    {
      "id": 101,
      "duration": 1830,
      "status": "SUCCESS",
      "createdAt": "2026-09-20T10:15:00.000Z"
    }
  ],
  "total": 42,
  "page": 1,
  "perPage": 50
}

Коды ошибок

HTTP	Ошибка	Описание
401	`unauthorized`	Ключ не передан, недействителен или отозван

Примеры кода

curl -X GET "https://external-api.sp-summary.org/api/v1/task?page=1" \
  -H "X-API-Key: sp_summary_ВАШ_КЛЮЧ"

POST/task

Создать задачу на транскрибацию

Создаёт задачу на расшифровку аудио или видео. Файл передаётся либо ссылкой fileUrl, либо multipart-загрузкой в поле file — всегда что-то одно.

Тело запроса

Параметр	Тип	Описание
`fileUrl`	string	Публичная ссылка на файл. Альтернатива multipart-полю file
`file`	multipart	Файл до 7 ГБ при загрузке multipart/form-data. Альтернатива fileUrl
`lang`	string	Подсказка языка (например, ru или en), по умолчанию auto
`numSpeakers`	number	Ожидаемое количество спикеров для разделения речи

Перед созданием задачи проверяется лимит минут: при нехватке минут вернётся 402.
Длительность ролика тарифицируется в минутах с округлением вверх.

Пример ответа

{
  "status": true,
  "taskId": 101
}

Коды ошибок

HTTP	Ошибка	Описание
401	`unauthorized`	Ключ не передан, недействителен или отозван
400	`bad_request`	Не передан ни file, ни fileUrl, либо переданы оба
402	`payment_required`	Недостаточно минут на балансе для транскрибации
500	`internal_error`	Не удалось скачать или обработать файл

Примеры кода

curl -X POST "https://external-api.sp-summary.org/api/v1/task" \
  -H "X-API-Key: sp_summary_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"fileUrl":"https://example.com/records/call.mp3"}'

GET/task/:taskId

Статус и результат задачи

Возвращает состояние задачи. Когда статус SUCCESS, в ответе появляются text (полный текст), words и segments (таймкоды). Флаг hasSummary показывает, готово ли резюме.

Параметры пути

Параметр	Тип	Описание
`taskId`обязательный	number	ID задачи

Пример ответа

{
  "task": {
    "id": 101,
    "duration": 1830,
    "status": "SUCCESS",
    "createdAt": "2026-09-20T10:15:00.000Z",
    "hasSummary": true,
    "text": "Полный текст расшифровки…",
    "words": [ { "word": "Полный", "start": 0.12, "end": 0.48 } ],
    "segments": [ { "start": 0, "end": 12.4, "speaker": "SPEAKER_00", "text": "…" } ]
  }
}

Коды ошибок

HTTP	Ошибка	Описание
401	`unauthorized`	Ключ не передан, недействителен или отозван
403	`forbidden`	Задача принадлежит другому аккаунту
404	`not_found`	Задача не найдена

Примеры кода

curl -X GET "https://external-api.sp-summary.org/api/v1/task/101" \
  -H "X-API-Key: sp_summary_ВАШ_КЛЮЧ"

GET/summary-templates

Шаблоны резюме

Список доступных шаблонов резюме: встроенные (builtin) и ваши собственные (custom). Идентификатор builtin — slug (general, sales, interview, daily, one-on-one, lecture, client-call, retro, podcast), идентификатор custom — вида custom-123.

Query-параметры

Параметр	Тип	Описание
`lang`	string	Язык названий и описаний: ru или en, по умолчанию ru

Пример ответа

{
  "builtin": [
    { "id": "general", "name": "Стандартный", "description": "Краткое резюме встречи" },
    { "id": "sales", "name": "Продажи", "description": "Итоги переговоров и следующие шаги" }
  ],
  "custom": [
    { "id": "custom-12", "name": "Мой шаблон" }
  ]
}

Коды ошибок

HTTP	Ошибка	Описание
401	`unauthorized`	Ключ не передан, недействителен или отозван

Примеры кода

curl -X GET "https://external-api.sp-summary.org/api/v1/summary-templates?lang=ru" \
  -H "X-API-Key: sp_summary_ВАШ_КЛЮЧ"

POST/task/:taskId/summary

Сгенерировать резюме

Запускает генерацию резюме по задаче с готовой расшифровкой и возвращает готовый текст. Резюме — платная функция: без оплаченного доступа вернётся 402.

Параметры пути

Параметр	Тип	Описание
`taskId`обязательный	number	ID задачи со статусом SUCCESS

Тело запроса

Параметр	Тип	Описание
`templateId`	string	ID шаблона из GET /summary-templates, по умолчанию general

Пример ответа

{
  "status": true,
  "summary": "На встрече обсудили…",
  "templateId": "general",
  "templateName": "Стандартный"
}

Коды ошибок

HTTP	Ошибка	Описание
401	`unauthorized`	Ключ не передан, недействителен или отозван
400	`template_not_found`	Шаблон с таким ID не найден
402	`payment_required`	Резюме — платная функция, доступ не оплачен
404	`not_found`	Задача не найдена или чужая
409	`no_transcript`	Задача ещё не расшифрована
409	`generation_in_progress`	Генерация резюме уже идёт
429	`rebuild_limit`	Исчерпан лимит пересборок резюме для задачи

Примеры кода

curl -X POST "https://external-api.sp-summary.org/api/v1/task/101/summary" \
  -H "X-API-Key: sp_summary_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"templateId":"general"}'

GET/task/:taskId/summary

Получить резюме

Возвращает готовое резюме задачи. Если резюме ещё не генерировали, поля summary, templateId и templateName равны null (это не ошибка).

Параметры пути

Параметр	Тип	Описание
`taskId`обязательный	number	ID задачи

Пример ответа

{
  "status": true,
  "summary": "На встрече обсудили…",
  "templateId": "general",
  "templateName": "Стандартный"
}

Коды ошибок

HTTP	Ошибка	Описание
401	`unauthorized`	Ключ не передан, недействителен или отозван
404	`not_found`	Задача не найдена или чужая

Примеры кода

curl -X GET "https://external-api.sp-summary.org/api/v1/task/101/summary" \
  -H "X-API-Key: sp_summary_ВАШ_КЛЮЧ"

Статусы задач

Статус	Значение
`NEW`	Задача создана и стоит в очереди
`PROCESSING`	Файл скачивается или расшифровывается
`AWAITING_PAYMENT`	Обработка приостановлена: требуется оплата
`SUCCESS`	Расшифровка готова, доступны text, words и segments
`FAILED`	Обработка завершилась с ошибкой

Коды ошибок

Ошибки возвращаются в формате { "status": false, "error": "код_ошибки" } с соответствующим HTTP-статусом.

HTTP	Значение
`400`	Неверные параметры запроса или неизвестный шаблон (template_not_found)
`401`	Ключ не передан, недействителен или отозван
`402`	Требуется оплата: недостаточно минут или резюме не оплачено (payment_required)
`403`	Доступ к чужой задаче запрещён
`404`	Задача не найдена (not_found)
`409`	Конфликт состояния: нет расшифровки (no_transcript) или генерация уже идёт (generation_in_progress)
`429`	Исчерпан лимит пересборок резюме (rebuild_limit)
`500`	Внутренняя ошибка сервера

Лимиты

Размер файла — до 7 ГБ (7000 МБ)
Пагинация списка задач — 50 задач на страницу
До 5 активных API-ключей на аккаунт
До 5 пересборок резюме на одну задачу

Тарификация

Транскрибация тарифицируется в минутах, длительность округляется вверх до целой минуты.
Резюме — платная функция: без оплаченного доступа генерация вернёт 402 payment_required.
Проверка лимита происходит до создания задачи, поэтому неоплаченный запрос не тратит ресурсы.