API транскрибации на Звукограме

, Обновлено 19 ноября 2026

Асинхронное распознавание аудио и видео через HTTP API: передайте локальный файл или прямую HTTPS-ссылку, дождитесь готовности и скачайте результат в JSON, SRT, VTT, PDF, DOCX, CSV или TXT. Подходит для ботов, CRM, видеоредакторов и обработки интервью; API распознаёт запись целиком.

Базовый URL для всех запросов:

https://zvukogram.com/api/v1

Быстрый старт  |  Спецификация OpenAPI 3.0 (JSON)  |  API-ключ в личном кабинете

Как проходит распознавание

  1. Отправьте файл или ссылку запросом POST /transcriptions. Сервер вернёт HTTP 202 и id задачи.
  2. Проверяйте статус через GET /transcriptions/{id} примерно раз в 5 секунд до значения completed.
  3. Заберите текст с таймкодами из /result или готовый файл (SRT, VTT, PDF, DOCX, CSV, TXT) из /export.

Быстрый старт

Нужны API-ключ из личного кабинета, баланс для распознавания и локальный файл с аудиодорожкой. Подходит тот же ключ, который используется для озвучки.

  1. Шаг 1 из 3: Подготовьте ключ и выберите модель

    Команды ниже рассчитаны на Bash (Linux, macOS, WSL). Ключ вводится скрыто и хранится в переменной текущей сессии. В Windows используйте WSL либо адаптируйте команды для PowerShell.

    read -rsp 'API key: ' API_KEY; printf '\n' export API_KEY BASE='https://zvukogram.com/api/v1' curl --fail-with-body -sS "$BASE/transcription-models" \ -H "Authorization: Bearer $API_KEY" # Выберите id из полученного списка MODEL='azure-fast' FILE='./interview.mp3' # Сохраните ключ операции: повтор того же запроса делайте с тем же ключом REQUEST_KEY='interview-2026-001'
  2. Шаг 2 из 3: Загрузите файл

    curl --fail-with-body --progress-bar \ --connect-timeout 20 --max-time 3600 \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $REQUEST_KEY" \ -F "model=$MODEL" -F 'language=ru-RU' \ -F "file=@$FILE" \ "$BASE/transcriptions" -o task.json cat task.json

    Успешный ответ: HTTP 202 Accepted. Это подтверждение приёма, а не завершения распознавания. В заголовке Location приходит относительный адрес состояния задачи.

    { "id": "6cff193385bf026567661c6f23fd8da0", "status": "queued", "created_at": "2026-11-13T10:00:00+00:00", "expires_at": "2027-02-11T10:00:00+00:00", "duration_seconds": null, "cost_tokens": null, "refunded": false, "error": null }
  3. Шаг 3 из 3: Дождитесь готовности и скачайте результат

    Скопируйте id из task.json. Проверяйте состояние примерно раз в 5 секунд; при failed остановите ожидание и прочитайте error.

    ID='ВСТАВЬТЕ_ID_ИЗ_ОТВЕТА' curl --fail-with-body -sS \ -H "Authorization: Bearer $API_KEY" "$BASE/transcriptions/$ID" # После status=completed: curl --fail-with-body -sS \ -H "Authorization: Bearer $API_KEY" \ "$BASE/transcriptions/$ID/result" -o transcript.json curl --fail-with-body -sS \ -H "Authorization: Bearer $API_KEY" \ "$BASE/transcriptions/$ID/export?format=srt" -o subtitles.srt

Авторизация

Передавайте секретный ключ в заголовке каждого запроса, включая получение статуса и скачивание файлов.

Authorization: Bearer YOUR_API_KEY

Также поддерживается заголовок X-API-Key. Для совместимости POST принимает поля email и token; email должен принадлежать владельцу ключа. Для новой интеграции используйте Bearer.

Безопасность ключа Храните ключ на своём сервере, например в переменной окружения. Не размещайте его в клиентском JavaScript, мобильном приложении, URL или публичном репозитории. API не принимает ключ в query string.

Методы API

Метод Путь относительно /api/v1 Успешный ответ
GET /transcription-models 200 · каталог моделей и форматов
POST /transcriptions 202 · задача принята или найдена по ключу повтора
GET /transcriptions/{id} 200 · текущее состояние
GET /transcriptions/{id}/result 200 · нормализованный JSON
GET /transcriptions/{id}/export?format=srt 200 · файл результата

Ответы API приходят в JSON (UTF-8); экспорт возвращает файл выбранного формата. Используйте HTTPS и адреса из примеров без перенаправления POST.

Примеры кода для каждого этапа

Выбирайте язык отдельно в каждом блоке примеров. Каждый фрагмент самодостаточен: из общих настроек нужен только API_KEY в окружении. Замените путь к файлу или HTTPS-ссылку, выберите модель из каталога, а для проверки статуса и скачивания вставьте ID задачи.

cURL: Bash (Linux, macOS, WSL). Python: 3.9+, установите зависимости командой ниже. PHP: 8+ с расширением cURL. Node.js: 22.17+, сохраняйте примеры в файл .mjs и запускайте на сервере.

python -m pip install requests requests-toolbelt

Python-загрузка использует потоковый MultipartEncoder, а Node.js использует файловый Blob, чтобы не читать большой файл целиком в память. Не изменяйте файл во время отправки.

О повторах и ключах идемпотентности Это отдельные запросы по этапам. Для новой записи создавайте новый Idempotency-Key; после сетевого сбоя повторяйте отправку с прежним ключом. Сохраните id задачи. Примеры явно проверяют HTTP-ответ; правила задержек и повторов приведены в разделе «Ошибки».

Модели, языки и ограничения

Получайте актуальный каталог через GET /transcription-models. В параметр model передаётся поле id, а не отображаемое название name.

{ "models": [ { "id": "azure-mai-2", "name": "Максимальная точность", "languages": [ "ru-RU", "en-US" ], "auto_language": true, "max_bytes": 1073741824, "max_request_bytes": 249000000, "max_duration_seconds": 7200, "price_tokens_per_minute": 2 } ], "export_formats": [ "txt", "json", "srt", "vtt", "sub", "pdf", "docx", "csv" ] }
Поле модели Как использовать
id Актуальный публичный код. Прежние API-имена и постоянный код модели тоже принимаются. В каталоге одна запись на модель.
languages Допустимые коды языка. По умолчанию запрос использует ru-RU.
auto_language Если true, можно отправить language=auto.
max_bytes Максимальный размер оригинала в байтах: для файла и для загрузки по ссылке.
max_request_bytes Максимальный размер подготовленного сервером аудио перед распознаванием. Проверяется после конвертации.
max_duration_seconds Максимальная длительность записи в секундах.
price_tokens_per_minute Текущая цена минуты в токенах. Значения в примере иллюстративные; читайте реальный ответ каталога.
Разница между max_bytes и max_request_bytes Оригинал может быть больше max_request_bytes, если после серверной конвертации он укладывается в этот лимит. Конвертировать и разбивать запись на части самостоятельно не требуется. Общий предел оригинала сейчас составляет 1 ГиБ (1 073 741 824 байта); проверяйте также лимиты выбранной модели.

Пример запроса каталога

curl --fail-with-body -sS --connect-timeout 20 --max-time 60 \ -H "Authorization: Bearer $API_KEY" \ "https://zvukogram.com/api/v1/transcription-models"
import os import requests response = requests.get( "https://zvukogram.com/api/v1/transcription-models", headers={"Authorization": "Bearer " + os.environ["API_KEY"]}, timeout=(20, 60), allow_redirects=False, ) if response.status_code != 200: raise RuntimeError(f"HTTP {response.status_code}: {response.text}") data = response.json() for model in data["models"]: print(model["id"], model["name"], model["price_tokens_per_minute"])
<?php $token = getenv('API_KEY'); if (!$token) { throw new RuntimeException('Set API_KEY'); } $ch = curl_init("https://zvukogram.com/api/v1/transcription-models"); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_CONNECTTIMEOUT => 20, CURLOPT_TIMEOUT => 60, CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); $error = curl_error($ch); curl_close($ch); if ($body === false) { throw new RuntimeException($error); } if ($status !== 200) { throw new RuntimeException("HTTP $status: $body"); } $data = json_decode($body, true, 512, JSON_THROW_ON_ERROR); foreach ($data["models"] as $model) { echo $model["id"], ": ", $model["name"], PHP_EOL; }
if (!process.env.API_KEY) throw new Error('Set API_KEY'); const response = await fetch( 'https://zvukogram.com/api/v1/transcription-models', { headers: { Authorization: `Bearer ${process.env.API_KEY}` }, signal: AbortSignal.timeout(60_000), redirect: 'error' }); const body = await response.text(); if (response.status !== 200) { throw new Error(`HTTP ${response.status}: ${body}`); } const data = JSON.parse(body); for (const model of data.models) { console.log(model.id, model.name, model.price_tokens_per_minute); }

Создание задачи: файл или ссылка

POST /transcriptions · один источник и одна запись на запрос.

Параметр Обязателен Описание
model · string Да Код модели из каталога либо её прежнее имя.
language · string Нет По умолчанию ru-RU. Код из languages или auto при поддержке модели.
file · binary Файл или source_url Локальное аудио/видео в multipart/form-data. Не путь строкой и не Base64.
source_url · string Ссылка или file Прямая публичная HTTPS-ссылка на медиафайл; передаётся в JSON.

Загрузка локального файла

Пример multipart приведён в быстром старте. @ в file=@... означает чтение файла на машине, где запущен cURL. Отправляется один HTTP-запрос. Граница multipart задаётся клиентом автоматически, поэтому не устанавливайте Content-Type вручную при использовании -F.

Для больших записей используйте потоковую загрузку, как в примерах ниже, и таймаут, достаточный для передачи файла. Ответ 202 приходит после полной загрузки; распознавание выполняется отдельно в фоне. MP3, WAV, M4A, MP4 и другие читаемые медиаконтейнеры должны содержать аудиодорожку.

FILE='./interview.mp3' MODEL='azure-fast' # Выберите id из каталога REQUEST_KEY='interview-file-001' # Сохраните для сетевых повторов curl --fail-with-body --progress-bar \ --connect-timeout 20 --max-time 3600 \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $REQUEST_KEY" \ -F "model=$MODEL" -F 'language=ru-RU' \ -F "file=@$FILE" \ 'https://zvukogram.com/api/v1/transcriptions' -o task.json cat task.json
import os from pathlib import Path import requests from requests_toolbelt.multipart.encoder import MultipartEncoder path = Path("interview.mp3") request_key = "interview-file-001" # Тот же ключ при повторе with path.open("rb") as audio: # Тело передаётся потоком, без чтения всего файла в память. form = MultipartEncoder(fields={ "model": "azure-fast", "language": "ru-RU", "file": (path.name, audio, "application/octet-stream"), }) response = requests.post( "https://zvukogram.com/api/v1/transcriptions", data=form, timeout=(20, 3600), allow_redirects=False, headers={"Authorization": "Bearer " + os.environ["API_KEY"], "Idempotency-Key": request_key, "Content-Type": form.content_type}, ) if response.status_code != 202: raise RuntimeError(f"HTTP {response.status_code}: {response.text}") task = response.json() print(task["id"], task["status"]) # Сохраните id задачи
<?php $token = getenv('API_KEY'); if (!$token) { throw new RuntimeException('Set API_KEY'); } $path = realpath('interview.mp3'); if ($path === false || !is_readable($path)) { throw new RuntimeException('Cannot read interview.mp3'); } $ch = curl_init('https://zvukogram.com/api/v1/transcriptions'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_CONNECTTIMEOUT => 20, CURLOPT_TIMEOUT => 3600, CURLOPT_HTTPHEADER => ["Authorization: Bearer $token", 'Idempotency-Key: interview-file-001'], // cURL сам задаёт Content-Type и границу multipart. CURLOPT_POSTFIELDS => [ 'model' => 'azure-fast', 'language' => 'ru-RU', 'file' => new CURLFile($path, 'application/octet-stream', basename($path)), ], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); $error = curl_error($ch); curl_close($ch); if ($body === false) { throw new RuntimeException($error); } if ($status !== 202) { throw new RuntimeException("HTTP $status: $body"); } $task = json_decode($body, true, 512, JSON_THROW_ON_ERROR); echo $task['id'], PHP_EOL; // Сохраните id задачи
import { openAsBlob } from 'node:fs'; if (!process.env.API_KEY) throw new Error('Set API_KEY'); // Файл читается с диска, не загружается целиком в память. // Не изменяйте исходный файл до завершения отправки. const file = await openAsBlob('./interview.mp3'); const form = new FormData(); form.set('model', 'azure-fast'); form.set('language', 'ru-RU'); form.set('file', file, 'interview.mp3'); const response = await fetch('https://zvukogram.com/api/v1/transcriptions', { method: 'POST', body: form, signal: AbortSignal.timeout(3_600_000), redirect: 'error', headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Idempotency-Key': 'interview-file-001' } // Content-Type с границей multipart устанавливает fetch. }); const body = await response.text(); if (response.status !== 202) { throw new Error(`HTTP ${response.status}: ${body}`); } const task = JSON.parse(body); console.log(task.id, task.status); // Сохраните id задачи

Импорт по ссылке

Сервер скачает файл самостоятельно. 202 означает постановку в очередь: недоступная ссылка или превышение лимита будут отражены позднее в статусе задачи. Используйте прямую ссылку на файл, а не страницу плеера, YouTube или страницу облачного диска. Локальные адреса и переходы на них не принимаются. Ссылка должна оставаться доступной до завершения скачивания.

Ровно один источник на запрос Передача file вместе с source_url вернёт invalid_source. Параметры вебхуков, частичного распознавания и формата результата при создании задачи не поддерживаются: формат выбирается при скачивании.
curl --fail-with-body -sS \ --connect-timeout 20 --max-time 60 \ -H "Authorization: Bearer $API_KEY" \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: interview-url-001' \ 'https://zvukogram.com/api/v1/transcriptions' \ --data '{"model":"azure-fast","language":"ru-RU", "source_url":"https://files.example.com/interview.mp3"}'
import os import requests response = requests.post( "https://zvukogram.com/api/v1/transcriptions", headers={"Authorization": "Bearer " + os.environ["API_KEY"], "Idempotency-Key": "interview-url-001"}, json={"model": "azure-fast", "language": "ru-RU", "source_url": "https://files.example.com/interview.mp3"}, timeout=(20, 60), allow_redirects=False, ) if response.status_code != 202: raise RuntimeError(f"HTTP {response.status_code}: {response.text}") task = response.json() print(task["id"], task["status"]) # Сохраните id задачи
<?php $token = getenv('API_KEY'); if (!$token) { throw new RuntimeException('Set API_KEY'); } $ch = curl_init('https://zvukogram.com/api/v1/transcriptions'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_CONNECTTIMEOUT => 20, CURLOPT_TIMEOUT => 60, CURLOPT_HTTPHEADER => ["Authorization: Bearer $token", 'Content-Type: application/json', 'Idempotency-Key: interview-url-001'], CURLOPT_POSTFIELDS => json_encode([ 'model' => 'azure-fast', 'language' => 'ru-RU', 'source_url' => 'https://files.example.com/interview.mp3' ], JSON_THROW_ON_ERROR), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); $error = curl_error($ch); curl_close($ch); if ($body === false) { throw new RuntimeException($error); } if ($status !== 202) { throw new RuntimeException("HTTP $status: $body"); } $task = json_decode($body, true, 512, JSON_THROW_ON_ERROR); echo $task['id'], PHP_EOL;
if (!process.env.API_KEY) throw new Error('Set API_KEY'); const response = await fetch('https://zvukogram.com/api/v1/transcriptions', { method: 'POST', signal: AbortSignal.timeout(60_000), redirect: 'error', headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': 'interview-url-001' }, body: JSON.stringify({ model: 'azure-fast', language: 'ru-RU', source_url: 'https://files.example.com/interview.mp3' }) }); const body = await response.text(); if (response.status !== 202) { throw new Error(`HTTP ${response.status}: ${body}`); } const task = JSON.parse(body); console.log(task.id, task.status);

Ожидание результата

GET /transcriptions/{id}

Вебхуков в v1 нет. После создания сохраните ID в своей системе и опрашивайте статус примерно раз в 5 секунд. При перезапуске приложения продолжайте опрос существующей задачи.

status Что происходит Действие клиента
queuedЗадача в очередиПродолжать опрос
downloadingСкачивание по ссылкеПродолжать опрос
validatingПроверка медиаПродолжать опрос
processingПодготовка или распознаваниеПродолжать опрос
completedРезультат готовСкачать JSON или экспорт
failedЗадача завершена с ошибкойОстановить опрос, обработать error

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

Поле состояния Значение
idИдентификатор задачи.
created_at, expires_atВремя создания и окончания доступа в ISO 8601.
duration_secondsДлительность в секундах; до анализа может быть null.
cost_tokensСписанная сумма; до списания может быть null.
refundedПризнак возврата списания. Проверяйте вместе с cost_tokens.
errorОбъект причины сбоя или null.
Проверяйте поле status, а не только HTTP-код HTTP 200 при проверке состояния означает успешный запрос статуса. Сама задача при этом может иметь status=failed. Всегда проверяйте это поле в теле ответа.

Пример запроса статуса

Один запрос состояния. Запускайте его примерно раз в 5 секунд до completed или failed. При 429 выдерживайте Retry-After; не создавайте новую задачу вместо повторного опроса.

ID='ВСТАВЬТЕ_ID_ЗАДАЧИ' curl --fail-with-body -sS --connect-timeout 20 --max-time 60 \ -H "Authorization: Bearer $API_KEY" \ "https://zvukogram.com/api/v1/transcriptions/$ID"
import os import requests task_id = "ВСТАВЬТЕ_ID_ЗАДАЧИ" response = requests.get( f"https://zvukogram.com/api/v1/transcriptions/{task_id}", headers={"Authorization": "Bearer " + os.environ["API_KEY"]}, timeout=(20, 60), allow_redirects=False, ) if response.status_code != 200: raise RuntimeError(f"HTTP {response.status_code}: {response.text}") data = response.json() print(data["id"], data["status"]) if data["status"] == "failed": raise RuntimeError(data["error"]) if data["status"] == "completed": print("Готово: можно получить результат") else: print("Повторите проверку примерно через 5 секунд")
<?php $token = getenv('API_KEY'); if (!$token) { throw new RuntimeException('Set API_KEY'); } $id = rawurlencode("ВСТАВЬТЕ_ID_ЗАДАЧИ"); $ch = curl_init("https://zvukogram.com/api/v1/transcriptions/{$id}"); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_CONNECTTIMEOUT => 20, CURLOPT_TIMEOUT => 60, CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); $error = curl_error($ch); curl_close($ch); if ($body === false) { throw new RuntimeException($error); } if ($status !== 200) { throw new RuntimeException("HTTP $status: $body"); } $data = json_decode($body, true, 512, JSON_THROW_ON_ERROR); echo $data['status'], PHP_EOL; if ($data['status'] === 'failed') { throw new RuntimeException(json_encode($data['error'], JSON_UNESCAPED_UNICODE)); } echo $data['status'] === 'completed' ? 'Готово: можно получить результат' : 'Повторите проверку примерно через 5 секунд'; echo PHP_EOL;
if (!process.env.API_KEY) throw new Error('Set API_KEY'); const id = encodeURIComponent('ВСТАВЬТЕ_ID_ЗАДАЧИ'); const response = await fetch( `https://zvukogram.com/api/v1/transcriptions/${id}`, { headers: { Authorization: `Bearer ${process.env.API_KEY}` }, signal: AbortSignal.timeout(60_000), redirect: 'error' }); const body = await response.text(); if (response.status !== 200) { throw new Error(`HTTP ${response.status}: ${body}`); } const data = JSON.parse(body); console.log(data.id, data.status); if (data.status === 'failed') throw new Error(JSON.stringify(data.error)); console.log(data.status === 'completed' ? 'Готово: можно получить результат' : 'Повторите проверку примерно через 5 секунд');

Результат в JSON

GET /transcriptions/{id}/result

Единая структура результата содержит текст, сегменты, слова и спикеров. Пример ниже сокращён; идентификаторы спикеров условные.

{ "id": "6cff193385bf026567661c6f23fd8da0", "schema_version": 1, "text": "Добрый день.", "language": "ru-RU", "duration_seconds": 4, "no_speech": false, "segments": [ { "text": "Добрый день.", "start_ms": 1000, "end_ms": 2500, "speaker_id": "speaker_0", "words": [ { "text": "Добрый", "start_ms": 1000, "end_ms": 1700 }, { "text": "день.", "start_ms": 1800, "end_ms": 2500 } ] } ], "speakers": [ { "id": "speaker_0", "name": "Спикер 1" } ] }

start_ms и end_ms заданы в миллисекундах от начала записи, duration_seconds в секундах. speaker_id связывает сегмент со списком speakers. Не фиксируйте ID спикеров в коде и допускайте пустые массивы слов: детализация зависит от результата распознавания.

schema_version обозначает версию структуры. При no_speech=true осмысленный текст не обнаружен; обрабатывайте этот результат отдельно. Если задача ещё не готова, эндпоинт вернёт 409 с кодом result_not_ready.

Пример запроса JSON

Выполните после completed. Пример сохраняет JSON в transcript.json и выводит распознанный текст.

ID='ВСТАВЬТЕ_ID_ЗАДАЧИ' curl --fail-with-body -sS --connect-timeout 20 --max-time 60 \ -H "Authorization: Bearer $API_KEY" \ "https://zvukogram.com/api/v1/transcriptions/$ID/result" -o transcript.json cat transcript.json
import os import requests import json from pathlib import Path task_id = "ВСТАВЬТЕ_ID_ЗАДАЧИ" response = requests.get( f"https://zvukogram.com/api/v1/transcriptions/{task_id}/result", headers={"Authorization": "Bearer " + os.environ["API_KEY"]}, timeout=(20, 60), allow_redirects=False, ) if response.status_code != 200: raise RuntimeError(f"HTTP {response.status_code}: {response.text}") data = response.json() Path("transcript.json").write_text( json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8") print(data["text"])
<?php $token = getenv('API_KEY'); if (!$token) { throw new RuntimeException('Set API_KEY'); } $id = rawurlencode("ВСТАВЬТЕ_ID_ЗАДАЧИ"); $ch = curl_init("https://zvukogram.com/api/v1/transcriptions/{$id}/result"); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_CONNECTTIMEOUT => 20, CURLOPT_TIMEOUT => 60, CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); $error = curl_error($ch); curl_close($ch); if ($body === false) { throw new RuntimeException($error); } if ($status !== 200) { throw new RuntimeException("HTTP $status: $body"); } $data = json_decode($body, true, 512, JSON_THROW_ON_ERROR); if (file_put_contents('transcript.json', $body) === false) { throw new RuntimeException('Cannot save transcript.json'); } echo $data['text'], PHP_EOL;
import { writeFile } from 'node:fs/promises'; if (!process.env.API_KEY) throw new Error('Set API_KEY'); const id = encodeURIComponent('ВСТАВЬТЕ_ID_ЗАДАЧИ'); const response = await fetch( `https://zvukogram.com/api/v1/transcriptions/${id}/result`, { headers: { Authorization: `Bearer ${process.env.API_KEY}` }, signal: AbortSignal.timeout(60_000), redirect: 'error' }); const body = await response.text(); if (response.status !== 200) { throw new Error(`HTTP ${response.status}: ${body}`); } const data = JSON.parse(body); await writeFile('transcript.json', JSON.stringify(data, null, 2), 'utf8'); console.log(data.text);

Скачать PDF, SRT и другие форматы

GET /transcriptions/{id}/export?format=pdf

PDF, DOCX, SRT и остальные форматы можно скачать готовыми файлами после статуса completed. Повторное распознавание для этого не требуется, баланс повторно не списывается.

format Результат Применение
txtТекст UTF-8Простой текст; формат по умолчанию
jsonСтруктурированный JSONОбработка в приложении
srtSubRipСубтитры для видеоредакторов
vttWebVTTСубтитры для веб-плеера
subФайл субтитров SUBСистемы с поддержкой этого экспорта
pdfPDF-документЧтение и пересылка
docxДокумент WordРедактирование текста
csvТаблица CSVОбработка табличных данных
curl --fail-with-body -sS \ -H "Authorization: Bearer $API_KEY" \ "$BASE/transcriptions/$ID/export?format=pdf" -o transcript.pdf

Ответ содержит тело файла и заголовок Content-Disposition: attachment. Сохраняйте двоичный ответ как файл. Список доступных форматов также возвращается в export_formats каталога.

Пример скачивания файла

Пример скачивает SRT. Для PDF замените значение format / fmt / FORMAT на pdf, и имя выходного файла изменится вместе с ним.

ID='ВСТАВЬТЕ_ID_ЗАДАЧИ' FORMAT='srt' # Для PDF замените на pdf curl --fail-with-body -sS --connect-timeout 20 --max-time 300 \ -H "Authorization: Bearer $API_KEY" \ "https://zvukogram.com/api/v1/transcriptions/$ID/export?format=$FORMAT" \ -o "transcript.$FORMAT"
import os from pathlib import Path import requests task_id = "ВСТАВЬТЕ_ID_ЗАДАЧИ" fmt = "srt" # Для PDF замените на "pdf" target = Path(f"transcript.{fmt}") temporary = target.with_suffix(target.suffix + ".part") try: with requests.get( f"https://zvukogram.com/api/v1/transcriptions/{task_id}/export", params={"format": fmt}, stream=True, timeout=(20, 300), headers={"Authorization": "Bearer " + os.environ["API_KEY"]}, allow_redirects=False, ) as response: if response.status_code != 200: raise RuntimeError(f"HTTP {response.status_code}: {response.text}") with temporary.open("wb") as output: for chunk in response.iter_content(chunk_size=1024 * 1024): output.write(chunk) temporary.replace(target) # Только полностью скачанный файл except Exception: temporary.unlink(missing_ok=True) raise print(target)
<?php $token = getenv('API_KEY'); if (!$token) { throw new RuntimeException('Set API_KEY'); } $id = rawurlencode('ВСТАВЬТЕ_ID_ЗАДАЧИ'); $format = 'srt'; // Для PDF замените на pdf $target = "transcript.$format"; $temporary = "$target.part"; $output = fopen($temporary, 'wb'); if ($output === false) { throw new RuntimeException('Cannot open output file'); } $ch = curl_init("https://zvukogram.com/api/v1/transcriptions/$id/export?format=$format"); curl_setopt_array($ch, [ CURLOPT_FILE => $output, CURLOPT_CONNECTTIMEOUT => 20, CURLOPT_TIMEOUT => 300, CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"], ]); $ok = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); $error = curl_error($ch); curl_close($ch); fclose($output); if (!$ok || $status !== 200) { $details = $ok ? file_get_contents($temporary) : $error; unlink($temporary); throw new RuntimeException("HTTP $status: $details"); } if (!rename($temporary, $target)) { throw new RuntimeException('Cannot save result'); } echo $target, PHP_EOL;
import { createWriteStream } from 'node:fs'; import { rename, rm } from 'node:fs/promises'; import { Readable } from 'node:stream'; import { pipeline } from 'node:stream/promises'; if (!process.env.API_KEY) throw new Error('Set API_KEY'); const id = encodeURIComponent('ВСТАВЬТЕ_ID_ЗАДАЧИ'); const format = 'srt'; // Для PDF замените на pdf const target = `transcript.${format}`; const temporary = `${target}.part`; const response = await fetch( `https://zvukogram.com/api/v1/transcriptions/${id}/export?format=${format}`, { headers: { Authorization: `Bearer ${process.env.API_KEY}` }, signal: AbortSignal.timeout(300_000), redirect: 'error' }); if (response.status !== 200) { throw new Error(`HTTP ${response.status}: ${await response.text()}`); } try { await pipeline(Readable.fromWeb(response.body), createWriteStream(temporary)); await rename(temporary, target); } catch (error) { await rm(temporary, { force: true }); throw error; } console.log(target);

Повторы без дублирования задач

Передавайте заголовок Idempotency-Key при создании каждой задачи. Он должен быть уникальным для новой операции и оставаться неизменным при её сетевых повторах. Допустимо до 200 байт без пробелов и управляющих символов; подойдёт UUID.

Ситуация Что делать
Соединение оборвалось после отправки файла Повторить тот же POST с прежним ключом и тем же содержимым. Не создавать новый ключ только из-за таймаута.
Тот же ключ, модель, язык, имя и байты файла / URL Вернётся та же задача. Повторного списания за новую задачу не будет.
Изменился только публичный алиас той же модели Идемпотентность сохраняется.
Тот же ключ, но другое содержимое 409 idempotency_conflict. Для новой операции нужен новый ключ.
Задача уже failed Старый ключ возвращает прежнюю ошибочную задачу. Осознанный новый запуск выполняйте с новым ключом; он может быть платным.
Задача истекла Ключ действует в пределах срока хранения. Возможен idempotency_expired; для нового запуска нужен новый ключ.
Для source_url сравнивается строка ссылки Сравнивается сам URL, а не будущее содержимое по нему. Если файл по тому же адресу изменился и его нужно распознать заново, создайте новую операцию с новым ключом.

Ошибки и правила повторов

В ответах на неуспешный HTTP-запрос ошибка находится в объекте error. При фоновом сбое этот же объект приходит в состоянии задачи со статусом failed.

{ "error": { "code": "file_too_large", "message": "File exceeds the upload limit for model azure-fast: 1073741824 bytes.", "details": { "model": "azure-fast", "max_bytes": 1073741824, "actual_bytes": 1200000000, "stage": "download" }, "retryable": false } }

Ветвление делайте по code, а не по тексту message. Поле details содержит контекст: лимит, фактический размер, этап или HTTP-статус источника. Допускайте неизвестные коды и дополнительные поля.

HTTP Типичные коды Рекомендуемое действие
400 / 415invalid_request, invalid_model, invalid_language, invalid_sourceИсправить параметры или Content-Type.
401 / 403invalid_api_key, account_disabledПроверить ключ и состояние аккаунта.
404not_foundПроверить ID, аккаунт и срок хранения.
409result_not_readyПродолжить опрос; учитывать Retry-After.
409task_failedПричина в details.task_error; автоматический опрос прекратить.
409idempotency_conflictПроверить совпадение параметров с исходной операцией.
413file_too_large, upload_limitСверить размер с лимитом; повтор без изменений не поможет.
429rate_limit, active_limitВыдержать Retry-After и снизить частоту / дождаться завершения задач.
500 / 503internal_error, model_unavailable, storage_unavailableОграниченные повторы с задержкой; POST повторять с прежним ключом.
Причины ошибок при обработке записи и загрузке по ссылке
Код / группа Значение
prepared_file_too_largeПосле конвертации превышен max_request_bytes.
duration_exceededПревышена допустимая длительность.
empty_file, no_audio, invalid_mediaПустой файл, нет аудиодорожки или запись не читается.
source_not_found, source_access_deniedФайл по ссылке отсутствует или закрыт.
source_not_media, source_address_blockedСсылка ведёт на страницу либо недопустимый адрес.
download_timeout, download_incomplete, download_failedТаймаут, обрыв или другая ошибка скачивания.
insufficient_balanceНедостаточно токенов для всей записи.
provider_timeout, provider_unavailable, provider_rate_limitedСбой или ограничение распознавателя.
language_not_identifiedНе удалось определить язык. Проверьте запись и язык запроса.
Как трактовать retryable=true retryable=true означает, что причина может быть временной. Это не запускает задачу заново и не гарантирует бесплатный повтор. Используйте ограниченное число попыток, увеличивающуюся задержку и случайный разброс. При failed решение о новом платном запуске принимается отдельно. Ошибка прокси до приложения может вернуть HTML, поэтому проверяйте HTTP-статус и Content-Type до разбора JSON.

Частота запросов, баланс и хранение

Ограничение Значение
Создание задачДо 20 запросов в минуту на аккаунт. Повторные POST также учитываются.
Чтение APIДо 120 запросов в минуту на аккаунт, включая каталог, статусы и результаты.
Одновременно активные задачиДо 20 на аккаунт.
Рекомендованный опросПримерно раз в 5 секунд для одной задачи. Для нескольких распределяйте запросы в пределах общего лимита.
Хранение90 дней с создания задачи. Точный момент указан в expires_at.
Размер и длительностьЧитайте max_bytes, max_request_bytes и max_duration_seconds в каталоге.

Ориентировочная стоимость: длительность в секундах / 60 × price_tokens_per_minute. Итоговое списание смотрите в cost_tokens. Для запуска нужен баланс на всю запись.

Ошибка не всегда означает возврат: проверяйте поле refunded. В частности, ошибка определения языка может сохранить списание. Скачайте нужные результаты до expires_at и храните их в своей системе.

Перед запуском интеграции

  • Ключ хранится на сервере и передаётся только по HTTPS.
  • Модель, язык и лимиты берутся из каталога; приложение не зависит от названия поставщика.
  • ID задачи и ключ идемпотентности сохраняются до сетевого повтора.
  • Обрабатываются оба конечных статуса: completed и failed.
  • Есть таймаут ожидания, поддержка Retry-After и ограничение количества повторов.
  • JSON разбирается только после проверки HTTP-ответа; файл экспорта сохраняется как двоичные данные.
  • Результаты скачиваются до окончания срока хранения.

Нужна озвучка текста через API? Откройте документацию API синтеза речи. У транскрибации отдельные эндпоинты и структура ответов, но используются те же API-ключи из личного кабинета.