API juhend

Veebilehe kolm teenust – transkriptsioon kõnelejate tuvastusega, video dubleerimine ja teksti kõneks muutmine – on kättesaadavad ka teie programmidest. Päring salvestise lingi või tekstiga, vastus tulemusega. Üks konto, üks krediitide saldo.

Sisukord

• Kuidas alustada
• Hind ja piirangud
• Aadress ja autentimine
• Konto
• — GET /v1/account
• Transkriptsioon
• — POST /v1/transcriptions
• — GET /v1/transcriptions/{id}
• Video dubleerimine
• — POST /v1/dubbings
• — GET /v1/dubbings/{id}
• Teksti kõneks muutmine
• — POST /v1/speech
• — GET /v1/speech/{id}
• Vead
• Näited
• Abi

Kuidas alustada

1. Registreeruge või logige sisse veebilehel kuulen.ee ja kinnitage oma e-posti aadress.
2. Ostke krediite (API kasutab samu krediite mis veebileht).
3. Avage kasutajamenüüs jaotis „API“ ja looge võti. Võtit näidatakse ainult üks kord – kopeerige see kohe.

Hind ja piirangud

• Transkriptsioon – 1 krediit iga alustatud salvestise minuti eest. Dubleerimine – 10 krediiti alustatud minuti eest. Kõneks muutmine – 2 krediiti iga alustatud 1000 märgi eest. API kaudu tasuta minuteid ega märke ei ole.
• Saldot kontrollitakse töö loomisel, krediidid võetakse maha alles siis, kui töö on valmis. Ebaõnnestunud tööd ei maksa midagi.
• Üks salvestis – kuni 3 tundi; faili suurus ei ole piiratud (sobivad ka mitme GB videod). Fail peab olema kättesaadav avalikul https:// aadressil.
• Kuni 200 MB failide kestus ja hind määratakse kohe; suurematel töötlemise ajal, seega on vastuses estimatedCredits väärtus null.
• Iga API tulemus ilmub ka teie projektide loendisse veebilehel.

Aadress ja autentimine

Baasaadress: https://kuulen.ee/api/v1. Lisage igale päringule päis X-API-Key: ak_… (või Authorization: Bearer ak_…).

Konto

GET /v1/account

Tagastab teie krediitide saldo.

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

Transkriptsioon

POST /v1/transcriptions

Loob transkriptsioonitöö. Salvestis laaditakse antud aadressilt alla, mõõdetakse kestus, kontrollitakse saldot. Salvestis transkribeeritakse selle veebilehe keeles.

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

Vastus 202 Accepted:

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

GET /v1/transcriptions/{id}

Olek või, kui valmis, kogu transkriptsioon. Olekud: queued, processing, completed, failed.

Töötlemise ajal:

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

Kui valmis (?format=json, vaikimisi):

{
  "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 ja end – sekundid. ?format=txt tagastab lihtteksti ([MM:SS] SPEAKER_00: tekst), ?format=srt – subtiitrid SubRip-vormingus.

Video dubleerimine

POST /v1/dubbings

Loob dubleerimistöö: salvestis transkribeeritakse, tõlgitakse ja loetakse valitud keeles sisse, muusika ja efektid säilivad. Salvestise link ja suuruse reeglid – samad mis transkriptsioonil.

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

Vastus 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}

Kui valmis, on downloadUrl dubleeritud video (või helifail, kui üles laaditi heli); outputKind on video või audio.

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

Teksti kõneks muutmine

POST /v1/speech

Loeb teksti loomuliku häälega ette ja tagastab MP3. Kuni 2 000 000 märki; pikad tekstid loetakse osade kaupa ja liidetakse. Teksti keel tuvastatakse automaatselt.

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

Vastus 202 Accepted:

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

GET /v1/speech/{id}

Kui valmis, on downloadUrl MP3-fail; durationSeconds – salvestise kestus, characters – etteloetud märkide arv.

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

Vead

Näited

BASE=https://kuulen.ee/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

Kontrollige olekut iga 10–30 s järel, kuni status on completed või failed.

import requests, time

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

Abi

Küsimused – abi@kuulen.ee.