Príručka k API

Tri služby stránky – prepis s rozpoznávaním rečníkov, dabing videa a prevod textu na reč – sú dostupné aj z vašich programov. Požiadavka s odkazom na nahrávku alebo textom, odpoveď s výsledkom. Jeden účet, jeden zostatok kreditov.

Obsah

• Ako začať
• Cena a limity
• Adresa a overenie
• Účet
• — GET /v1/account
• Prepis
• — POST /v1/transcriptions
• — GET /v1/transcriptions/{id}
• Dabing videa
• — POST /v1/dubbings
• — GET /v1/dubbings/{id}
• Prevod textu na reč
• — POST /v1/speech
• — GET /v1/speech/{id}
• Chyby
• Príklady
• Pomoc

Ako začať

1. Zaregistrujte sa alebo sa prihláste na stránke pocujem.sk a potvrďte e-mailovú adresu.
2. Kúpte si kredity (API používa rovnaké kredity ako stránka).
3. V používateľskej ponuke otvorte časť „API“ a vytvorte kľúč. Kľúč sa zobrazí iba raz – hneď si ho skopírujte.

Cena a limity

• Prepis – 1 kredit za každú začatú minútu nahrávky. Dabing – 10 kreditov za začatú minútu. Prevod textu na reč – 2 kredity za každých začatých 1000 znakov. Cez API nie sú žiadne bezplatné minúty ani znaky.
• Zostatok sa kontroluje pri vytváraní úlohy, kredity sa odpočítajú až po dokončení úlohy. Neúspešné úlohy nič nestoja.
• Jedna nahrávka – do 3 hodín; veľkosť súboru nie je obmedzená (aj videá s veľkosťou niekoľko GB). Súbor musí byť dostupný na verejnej adrese https://.
• Pri súboroch do 200 MB sa dĺžka a cena určia hneď; pri väčších počas spracovania, preto je v odpovedi estimatedCredits rovné null.
• Každý výsledok cez API sa objaví aj vo vašom zozname projektov na stránke.

Adresa a overenie

Základná adresa: https://pocujem.sk/api/v1. Ku každej požiadavke pridajte hlavičku X-API-Key: ak_… (alebo Authorization: Bearer ak_…).

Účet

GET /v1/account

Vráti zostatok vašich kreditov.

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

Prepis

POST /v1/transcriptions

Vytvorí úlohu prepisu. Nahrávka sa stiahne z uvedenej adresy, zmeria sa dĺžka, skontroluje sa zostatok. Nahrávka sa prepisuje v jazyku tejto stránky.

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

Odpoveď 202 Accepted:

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

GET /v1/transcriptions/{id}

Stav alebo, keď je hotovo, celý prepis. Stavy: queued, processing, completed, failed.

Počas spracovania:

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

Keď je hotovo (?format=json, predvolené):

{
  "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 a end sú sekundy. ?format=txt vráti obyčajný text ([MM:SS] SPEAKER_00: text), ?format=srt titulky vo formáte SubRip.

Dabing videa

POST /v1/dubbings

Vytvorí úlohu dabingu: nahrávka sa prepíše, preloží a nahovorí vo zvolenom jazyku, hudba a efekty zostanú. Odkaz na nahrávku a pravidlá veľkosti – rovnaké ako pri prepise.

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

Odpoveď 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}

Keď je hotovo, downloadUrl je dabované video (alebo zvukový súbor, ak bol nahraný zvuk); outputKind je video alebo audio.

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

Prevod textu na reč

POST /v1/speech

Prečíta text prirodzeným hlasom a vráti MP3. Do 2 000 000 znakov; dlhé texty sa čítajú po častiach a spájajú. Jazyk textu sa rozpoznáva automaticky.

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

Odpoveď 202 Accepted:

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

GET /v1/speech/{id}

Keď je hotovo, downloadUrl je súbor MP3; durationSeconds – dĺžka nahrávky, characters – počet prečítaných znakov.

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

Chyby

Príklady

BASE=https://pocujem.sk/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

Kontrolujte stav každých 10–30 s, kým status nebude completed alebo failed.

import requests, time

BASE = "https://pocujem.sk/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"))

Pomoc

Otázky – pomoc@pocujem.sk.