Przewodnik po API

Trzy usługi serwisu – transkrypcja z rozpoznawaniem mówców, dubbing wideo i zamiana tekstu na mowę – dostępne także z Twoich programów. Zapytanie z linkiem do nagrania lub tekstem, odpowiedź z wynikiem. Jedno konto, jedno saldo kredytów.

Spis treści

• Jak zacząć
• Cena i limity
• Adres i uwierzytelnianie
• Konto
• — GET /v1/account
• Transkrypcja
• — POST /v1/transcriptions
• — GET /v1/transcriptions/{id}
• Dubbing wideo
• — POST /v1/dubbings
• — GET /v1/dubbings/{id}
• Tekst na mowę
• — POST /v1/speech
• — GET /v1/speech/{id}
• Błędy
• Przykłady
• Pomoc

Jak zacząć

1. Zarejestruj się lub zaloguj w serwisie slyszec.pl i potwierdź adres e-mail.
2. Kup kredyty (API korzysta z tych samych kredytów co serwis).
3. W menu użytkownika otwórz sekcję „API” i utwórz klucz. Klucz jest pokazywany tylko raz – skopiuj go od razu.

Cena i limity

• Transkrypcja – 1 kredyt za każdą rozpoczętą minutę nagrania. Dubbing – 10 kredytów za rozpoczętą minutę. Tekst na mowę – 2 kredyty za każde rozpoczęte 1000 znaków. Przez API nie ma darmowych minut ani znaków.
• Saldo jest sprawdzane przy tworzeniu zadania, kredyty są pobierane dopiero po zakończeniu zadania. Nieudane zadania nic nie kosztują.
• Jedno nagranie – do 3 godzin; rozmiar pliku nie jest ograniczony (także wideo o wielkości kilku GB). Plik musi być dostępny pod publicznym adresem https://.
• Dla plików do 200 MB czas trwania i cena są ustalane od razu; dla większych – podczas przetwarzania, dlatego w odpowiedzi estimatedCredits ma wartość null.
• Każdy wynik z API pojawia się także na liście Twoich projektów w serwisie.

Adres i uwierzytelnianie

Adres bazowy: https://slyszec.pl/api/v1. Do każdego zapytania dodaj nagłówek X-API-Key: ak_… (lub Authorization: Bearer ak_…).

Konto

GET /v1/account

Zwraca saldo Twoich kredytów.

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

Transkrypcja

POST /v1/transcriptions

Tworzy zadanie transkrypcji. Nagranie jest pobierane z podanego adresu, mierzony jest czas trwania, sprawdzane saldo. Nagranie jest transkrybowane w języku tego serwisu.

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

Odpowiedź 202 Accepted:

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

GET /v1/transcriptions/{id}

Status lub, po zakończeniu, cała transkrypcja. Statusy: queued, processing, completed, failed.

W trakcie przetwarzania:

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

Po zakończeniu (?format=json, domyślnie):

{
  "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 i end – sekundy. ?format=txt zwraca zwykły tekst ([MM:SS] SPEAKER_00: tekst), ?format=srt – napisy w formacie SubRip.

Dubbing wideo

POST /v1/dubbings

Tworzy zadanie dubbingu: nagranie jest transkrybowane, tłumaczone i czytane w wybranym języku, muzyka i efekty zostają zachowane. Link do nagrania i zasady rozmiaru – takie same jak dla transkrypcji.

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

Odpowiedź 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}

Po zakończeniu downloadUrl to zdubbingowane wideo (lub plik audio, jeśli przesłano audio); outputKind to video albo audio.

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

Tekst na mowę

POST /v1/speech

Czyta tekst naturalnym głosem i zwraca MP3. Do 2 000 000 znaków; długie teksty są czytane w częściach i łączone. Język tekstu jest wykrywany automatycznie.

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

Odpowiedź 202 Accepted:

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

GET /v1/speech/{id}

Po zakończeniu downloadUrl to plik MP3; durationSeconds – długość nagrania, characters – liczba przeczytanych znaków.

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

Błędy

Przykłady

BASE=https://slyszec.pl/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

Sprawdzaj status co 10–30 s, aż status zmieni się na completed lub failed.

import requests, time

BASE = "https://slyszec.pl/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

Pytania – pomoc@slyszec.pl.