Перейти к основному содержимому

От файла до результата

Во всех примерах нужны MINDVOICE_API_KEY и WORKSPACE_ID из подготовки доступа. Публичный API доступен по адресу https://api.mindvoice.pro. Загрузка и запуск задач выполняются асинхронно: успешный ответ означает постановку задачи, а не готовый текст или анализ.

1. Загрузите один или несколько файлов​

Для каждого файла отправьте отдельный POST /api/v1/workspaces/{workspace_id}/recordings с multipart/form-data: обязательное поле file, необязательные metadata (строка с JSON-объектом) и retention_days (целое число дней в пределах тарифа). Поддерживаются WAV, MP3, MP4/M4A и OGG; точные MIME-типы: audio/wav, audio/wave, audio/mpeg, audio/mp4, audio/ogg, audio/x-m4a. Проверяйте размер и доступный срок хранения в вашей среде.

curl --fail-with-body -X POST \
  "https://api.mindvoice.pro/api/v1/workspaces/$WORKSPACE_ID/recordings" \
  -H "Authorization: Bearer $MINDVOICE_API_KEY" \
  -F 'file=@./call.mp3;type=audio/mpeg' \
  -F 'metadata={"external_id":"crm-call-7781"}' \
  -F 'retention_days=7'

curl -F отправляет поля как multipart/form-data и сам задаёт Content-Type с boundary. В ответе сохраните поле id записи для следующих запросов.

Если файл доступен по прямой публичной HTTP(S)-ссылке, можно вызвать импорт:

curl --fail-with-body -X POST \
  "https://api.mindvoice.pro/api/v1/workspaces/$WORKSPACE_ID/recordings/import" \
  -H "Authorization: Bearer $MINDVOICE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://<публичный-хост>/call.mp3","filename":"call.mp3","metadata":{"external_id":"crm-call-7781"}}'

Импорт отвечает 202 и сначала имеет статус download_pending. Пока файл не скачан, ручная транскрибация вернёт 409. Следите за карточкой записи: возможны downloading, download_retry_wait, download_failed, затем обычные queued, processing, completed или failed. После download_failed используйте POST /recordings/{recording_id}/import/retry с необязательным новым url. Ссылка должна быть доступна без дополнительных заголовков и cookies.

2. Дождитесь подготовки записи​

curl --fail-with-body \
  "https://api.mindvoice.pro/api/v1/workspaces/$WORKSPACE_ID/recordings/$RECORDING_ID" \
  -H "Authorization: Bearer $MINDVOICE_API_KEY"

recordings:read нужен для чтения. completed означает, что подготовка аудио закончилась; это не статус транскрибации. Если для Workspace настроен активный автоматический сценарий, после подготовки транскрибация запустится сама. Если нет, выполните следующий шаг. Для списка файлов доступен GET /recordings с limit, offset, cursor и фильтрами; при постраничном обходе используйте next_cursor, если он возвращён.

3. Запустите транскрибацию вручную​

Список готовых сценариев: GET /api/v1/workspaces/{workspace_id}/transcription-scenarios (transcripts:read). ID нужного сценария начинается с sct-.

curl --fail-with-body -X POST \
  "https://api.mindvoice.pro/api/v1/workspaces/$WORKSPACE_ID/recordings/$RECORDING_ID/transcription-runs" \
  -H "Authorization: Bearer $MINDVOICE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"transcription_scenario_id\":\"$TRANSCRIPTION_SCENARIO_ID\"}"

Нужен transcripts:write. Ответ содержит id запуска trn-<UUID> и status: "queued". Проверяйте GET /transcription-runs/{run_id} до completed, failed или cancelled. При completed читайте текст этого запуска через GET /transcription-runs/{run_id}/transcript (transcripts:read). Ответ содержит id текста (обычный UUID), segments, words, language, а также поля резюме, если оно включено. GET /recordings/{recording_id}/transcript возвращает последний текст записи и может указывать на другой запуск.

Для группы файлов вызовите POST /transcription-scenarios/{scenario_id}/executions с {"recording_ids":["fl-…","fl-…"],"idempotency_key":"<ваш-уникальный-ключ>"}. Без recording_ids применяются сохранённый фильтр сценария и его правила отбора. Сохраняйте id исполнения и смотрите GET /transcription-scenarios/{scenario_id}/executions либо дочерние GET /transcription-runs?jobId=<UUID-исполнения>.

4. Получите AI-анализ​

Если активен автоматический сценарий анализа, он стартует после появления подходящего текста. Для ручного запуска выберите sca-<UUID> из GET /analysis-scenarios и отправьте:

curl --fail-with-body -X POST \
  "https://api.mindvoice.pro/api/v1/workspaces/$WORKSPACE_ID/recordings/$RECORDING_ID/analysis-runs" \
  -H "Authorization: Bearer $MINDVOICE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"analysis_scenario_id\":\"$ANALYSIS_SCENARIO_ID\",\"transcript_id\":\"$TRANSCRIPT_ID\"}"

Нужен analysis:write. transcript_id необязателен; укажите его, чтобы привязать анализ к конкретной версии текста. Без него backend выбирает последний текст записи. Ответ содержит analysis_run_id вида anl-<UUID> в поле id. Проверяйте GET /analysis-runs/{run_id} до терминального статуса. После completed читайте GET /recordings/{recording_id}/analysis-results/{analysis_run_id} или GET /analysis-results с фильтром recording_id/transcription_run_id (analysis:read). Результат содержит summary, answers, ссылки на запуск и транскрибацию. Для нескольких файлов используйте POST /analysis-scenarios/{scenario_id}/executions с массивом recording_ids и idempotency_key.

5. Обрабатывайте сбои​

При failed проверьте error_code, error_message и retryable в карточке запуска. Повтор транскрибации: POST /transcription-runs/{run_id}/retry; анализа: POST /analysis-runs/{run_id}/retry. Повтор создаёт новый запуск, исходный остаётся в истории. Автоматические повторы временных ошибок регулируются настройками сценария. Ошибки API и пагинация описаны отдельно.