Ръководство за API

Трите услуги на сайта – транскрипция с разпознаване на говорещите, дублаж на видео и озвучаване на текст – са достъпни и от вашите програми. Заявка с линк към записа или с текст, отговор с резултата. Един профил, един баланс на кредитите.

Съдържание

• Как да започнете
• Цена и ограничения
• Адрес и удостоверяване
• Профил
• — GET /v1/account
• Транскрипция
• — POST /v1/transcriptions
• — GET /v1/transcriptions/{id}
• Дублаж на видео
• — POST /v1/dubbings
• — GET /v1/dubbings/{id}
• Озвучаване на текст
• — POST /v1/speech
• — GET /v1/speech/{id}
• Грешки
• Примери
• Помощ

Как да започнете

1. Регистрирайте се или влезте в сайта slusham.bg и потвърдете имейл адреса си.
2. Купете кредити (API използва същите кредити като сайта).
3. В потребителското меню отворете раздел „API“ и създайте ключ. Ключът се показва само веднъж – копирайте го веднага.

Цена и ограничения

• Транскрипция – 1 кредит за всяка започната минута от записа. Дублаж – 10 кредита за започната минута. Озвучаване на текст – 2 кредита за всеки започнати 1000 знака. През API няма безплатни минути или знаци.
• Балансът се проверява при създаване на задачата, кредитите се приспадат едва когато задачата е готова. Неуспешните задачи не струват нищо.
• Един запис – до 3 часа; размерът на файла не е ограничен (и видео от няколко GB). Файлът трябва да е достъпен на публичен https:// адрес.
• За файлове до 200 MB продължителността и цената се определят веднага; за по-големи – по време на обработката, затова в отговора estimatedCredits е null.
• Всеки резултат през API се появява и в списъка с вашите проекти в сайта.

Адрес и удостоверяване

Основен адрес: https://slusham.bg/api/v1. Към всяка заявка добавете заглавка X-API-Key: ak_… (или Authorization: Bearer ak_…).

Профил

GET /v1/account

Връща баланса на вашите кредити.

{ "credits": 120, "creditsPerMinute": 1 }

Транскрипция

POST /v1/transcriptions

Създава задача за транскрипция. Записът се изтегля от посочения адрес, измерва се продължителността, проверява се балансът. Записът се транскрибира на езика на този сайт.

{
  "audioUrl": "https://example.com/recordings/call.mp3",
  "fileName": "call.mp3",
  "webhookUrl": "https://example.com/hooks/transcripts"
}

Отговор 202 Accepted:

{
  "id": "k3FgT9bQ2w",
  "status": "queued",
  "languageCode": "bg-BG",
  "fileName": "call.mp3",
  "durationSeconds": 1532,
  "estimatedCredits": 26,
  "pollUrl": "/v1/transcriptions/k3FgT9bQ2w"
}

GET /v1/transcriptions/{id}

Състояние или, когато е готово, цялата транскрипция. Състояния: queued, processing, completed, failed.

Докато се обработва:

{ "id": "k3FgT9bQ2w", "status": "processing", "progress": 40, "languageCode": "bg-BG", "fileName": "call.mp3", "durationSeconds": 1532 }

Когато е готово (?format=json, по подразбиране):

{
  "id": "k3FgT9bQ2w",
  "status": "completed",
  "creditsCharged": 26,
  "speakers": ["SPEAKER_00", "SPEAKER_01"],
  "segments": [
    { "speaker": "SPEAKER_00", "start": 0.0, "end": 4.2, "text": "…" },
    { "speaker": "SPEAKER_01", "start": 4.2, "end": 7.9, "text": "…" }
  ],
  "text": "…"
}

start и end са секунди. ?format=txt връща обикновен текст ([MM:SS] SPEAKER_00: текст), ?format=srt – субтитри във формат SubRip.

Дублаж на видео

POST /v1/dubbings

Създава задача за дублаж: записът се транскрибира, превежда и озвучава на избрания език, музиката и ефектите се запазват. Линкът към записа и правилата за размер са същите като при транскрипцията.

{
  "audioUrl": "https://example.com/recordings/talk.mp4",
  "targetLanguage": "en",
  "sourceLanguage": "auto",
  "keepBackground": true,
  "originalVoices": false,
  "fileName": "talk.mp4",
  "webhookUrl": "https://example.com/hooks/dubbing"
}

Отговор 202 Accepted:

{ "id": "p8Dk2Qa1Lm", "kind": "dubbing", "status": "queued", "fileName": "talk.mp4", "durationSeconds": 184, "estimatedCredits": 40, "targetLanguage": "en", "sourceLanguage": "auto", "pollUrl": "/v1/dubbings/p8Dk2Qa1Lm" }

GET /v1/dubbings/{id}

Когато е готово, downloadUrl е дублираното видео (или аудио файл, ако е качено аудио); outputKind е video или audio.

{ "id": "p8Dk2Qa1Lm", "kind": "dubbing", "status": "completed", "targetLanguage": "en", "durationSeconds": 184, "creditsCharged": 40, "downloadUrl": "https://…/dubbed.mp4", "outputKind": "video", "segments": 42, "flaggedSegments": 0 }

Озвучаване на текст

POST /v1/speech

Озвучава текста с естествен глас и връща MP3. До 2 000 000 знака; дългите текстове се озвучават на части и се съединяват. Езикът на текста се разпознава автоматично.

{ "text": "…", "voice": "female", "fileName": "intro", "webhookUrl": "https://example.com/hooks/speech" }

Отговор 202 Accepted:

{ "id": "s4Hn7Rt9Wq", "kind": "speech", "status": "queued", "characters": 1840, "voice": "female", "estimatedCredits": 4, "pollUrl": "/v1/speech/s4Hn7Rt9Wq" }

GET /v1/speech/{id}

Когато е готово, downloadUrl е MP3 файл; durationSeconds – продължителност на записа, characters – брой озвучени знаци.

{ "id": "s4Hn7Rt9Wq", "kind": "speech", "status": "completed", "characters": 1840, "durationSeconds": 131.4, "creditsCharged": 4, "downloadUrl": "https://…/full.mp3" }

Грешки

Примери

BASE=https://slusham.bg/api/v1
KEY=ak_...

curl -s $BASE/account -H "X-API-Key: $KEY"

curl -s -X POST $BASE/transcriptions -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"audioUrl":"https://example.com/call.mp3"}'

curl -s $BASE/transcriptions/JOB_ID -H "X-API-Key: $KEY"
curl -s "$BASE/transcriptions/JOB_ID?format=srt" -H "X-API-Key: $KEY" -o call.srt

Проверявайте състоянието на всеки 10–30 s, докато status стане completed или failed.

import requests, time

BASE = "https://slusham.bg/api/v1"
H = {"X-API-Key": "ak_..."}

job = requests.post(f"{BASE}/transcriptions", headers=H,
                    json={"audioUrl": "https://example.com/call.mp3"}).json()
while True:
    r = requests.get(f"{BASE}/transcriptions/{job['id']}", headers=H).json()
    if r["status"] in ("completed", "failed"):
        break
    time.sleep(15)
print(r.get("text") or r.get("error"))

Помощ

Въпроси – pomosht@slusham.bg.