Асинхронное распознавание аудио и видео через HTTP API: передайте локальный файл или прямую HTTPS-ссылку, дождитесь готовности и скачайте результат в JSON, SRT, VTT, PDF, DOCX, CSV или TXT. Подходит для ботов, CRM, видеоредакторов и обработки интервью; API распознаёт запись целиком.
Базовый URL для всех запросов:
https://zvukogram.com/api/v1
Быстрый старт | Спецификация OpenAPI 3.0 (JSON) | API-ключ в личном кабинете
Как проходит распознавание
- Отправьте файл или ссылку запросом
POST /transcriptions. Сервер вернётHTTP 202иidзадачи. - Проверяйте статус через
GET /transcriptions/{id}примерно раз в 5 секунд до значенияcompleted. - Заберите текст с таймкодами из
/resultили готовый файл (SRT, VTT, PDF, DOCX, CSV, TXT) из/export.
Быстрый старт
Нужны API-ключ из личного кабинета, баланс для распознавания и локальный файл с аудиодорожкой. Подходит тот же ключ, который используется для озвучки.
-
Шаг 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 из 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: Дождитесь готовности и скачайте результат
Скопируйте
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.
Методы 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_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=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 | Обработка в приложении |
srt | SubRip | Субтитры для видеоредакторов |
vtt | WebVTT | Субтитры для веб-плеера |
sub | Файл субтитров SUB | Системы с поддержкой этого экспорта |
pdf | PDF-документ | Чтение и пересылка |
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; для нового запуска нужен новый ключ. |
Ошибки и правила повторов
В ответах на неуспешный 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 / 415 | invalid_request, invalid_model, invalid_language, invalid_source | Исправить параметры или Content-Type. |
| 401 / 403 | invalid_api_key, account_disabled | Проверить ключ и состояние аккаунта. |
| 404 | not_found | Проверить ID, аккаунт и срок хранения. |
| 409 | result_not_ready | Продолжить опрос; учитывать Retry-After. |
| 409 | task_failed | Причина в details.task_error; автоматический опрос прекратить. |
| 409 | idempotency_conflict | Проверить совпадение параметров с исходной операцией. |
| 413 | file_too_large, upload_limit | Сверить размер с лимитом; повтор без изменений не поможет. |
| 429 | rate_limit, active_limit | Выдержать Retry-After и снизить частоту / дождаться завершения задач. |
| 500 / 503 | internal_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 означает, что причина может быть временной. Это не запускает задачу заново и не гарантирует бесплатный повтор. Используйте ограниченное число попыток, увеличивающуюся задержку и случайный разброс. При 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-ключи из личного кабинета.