API-útmutató

Az oldal három szolgáltatása – átírás beszélőfelismeréssel, videószinkron és szövegfelolvasás – a saját programjaiból is elérhető. Kérés a felvétel linkjével vagy a szöveggel, válasz az eredménnyel. Egy fiók, egy kreditegyenleg.

Tartalom

• Így kezdje
• Ár és korlátok
• Cím és hitelesítés
• Fiók
• — GET /v1/account
• Átírás
• — POST /v1/transcriptions
• — GET /v1/transcriptions/{id}
• Videószinkron
• — POST /v1/dubbings
• — GET /v1/dubbings/{id}
• Szövegfelolvasás
• — POST /v1/speech
• — GET /v1/speech/{id}
• Hibák
• Példák
• Segítség

Így kezdje

1. Regisztráljon vagy jelentkezzen be a hallok.hu oldalon, és erősítse meg az e-mail-címét.
2. Vásároljon krediteket (az API ugyanazokat a krediteket használja, mint az oldal).
3. A felhasználói menüben nyissa meg az „API” részt, és hozzon létre egy kulcsot. A kulcs csak egyszer jelenik meg – azonnal másolja ki.

Ár és korlátok

• Átírás – 1 kredit a felvétel minden megkezdett percéért. Szinkron – 10 kredit megkezdett percenként. Felolvasás – 2 kredit minden megkezdett 1000 karakterért. Az API-n keresztül nincsenek ingyenes percek vagy karakterek.
• Az egyenleget a feladat létrehozásakor ellenőrizzük, a krediteket csak a feladat elkészültekor vonjuk le. A sikertelen feladatok nem kerülnek semmibe.
• Egy felvétel – legfeljebb 3 óra; a fájlméret nincs korlátozva (több GB-os videók is). A fájlnak nyilvános https:// címen elérhetőnek kell lennie.
• 200 MB-ig a hosszt és az árat azonnal meghatározzuk; nagyobb fájloknál a feldolgozás során, ezért a válaszban az estimatedCredits értéke null.
• Minden API-eredmény megjelenik az oldalon a projektlistájában is.

Cím és hitelesítés

Alapcím: https://hallok.hu/api/v1. Minden kéréshez adja hozzá az X-API-Key: ak_… fejlécet (vagy Authorization: Bearer ak_…).

Fiók

GET /v1/account

Visszaadja a kreditegyenlegét.

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

Átírás

POST /v1/transcriptions

Átírási feladatot hoz létre. A felvételt letöltjük a megadott címről, megmérjük a hosszát, ellenőrizzük az egyenleget. A felvételt ennek a webhelynek a nyelvén írjuk át.

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

Válasz 202 Accepted:

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

GET /v1/transcriptions/{id}

Állapot, vagy ha kész, a teljes átirat. Állapotok: queued, processing, completed, failed.

Feldolgozás közben:

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

Ha kész (?format=json, alapértelmezett):

{
  "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": "…"
}

A start és end másodpercben értendő. A ?format=txt egyszerű szöveget ad vissza ([MM:SS] SPEAKER_00: szöveg), a ?format=srt SubRip feliratot.

Videószinkron

POST /v1/dubbings

Szinkronfeladatot hoz létre: a felvételt átírjuk, lefordítjuk és a választott nyelven felolvassuk, a zene és az effektek megmaradnak. A felvétel linkje és a méretszabályok – ugyanazok, mint az átírásnál.

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

Válasz 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}

Ha kész, a downloadUrl a szinkronizált videó (vagy hangfájl, ha hangot töltöttek fel); az outputKind video vagy audio.

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

Szövegfelolvasás

POST /v1/speech

Természetes hangon felolvassa a szöveget, és MP3-at ad vissza. Legfeljebb 2 000 000 karakter; a hosszú szövegeket részenként olvassa fel és fűzi össze. A szöveg nyelvét a rendszer automatikusan felismeri.

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

Válasz 202 Accepted:

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

GET /v1/speech/{id}

Ha kész, a downloadUrl az MP3-fájl; durationSeconds – a felvétel hossza, characters – a felolvasott karakterek száma.

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

Hibák

Példák

BASE=https://hallok.hu/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

Ellenőrizze az állapotot 10–30 másodpercenként, amíg a status completed vagy failed nem lesz.

import requests, time

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

Segítség

Kérdések – segitseg@hallok.hu.