API zamiany mowy na tekst dla nagranego audio

API zamiany mowy na tekst Hushscript przyjmuje nagrane audio przez /v1/, a potem pozwala skryptowi odpytywać zadanie i odczytać transkrypcję. To przebieg transkrypcji online, a nie strumieniowanie na żywo ani surowy endpoint modelu rozpoznawania. Serwer MCP korzysta z tego samego konta, salda i tokenu okaziciela, gdy twój klient woli narzędzia od wywołań HTTP.

Transkrypcja audio i wideo przez API

API do transkrypcji audio przyjmuje przygotowane pliki audio, także nagrany głos. Do integracji STT (zamiana mowy na tekst) przesyłaj nagrane pliki; strumieniowanie na żywo z mikrofonu nie jest dostępne. W przypadku transkrypcji wideo prześlij plik MP4 lub MOV ze ścieżką audio bez zmian: serwer odczytuje ścieżkę audio i pomija wideo. Z każdego innego formatu wideo najpierw wyodrębnij audio; API nie przyjmuje linku do wideo. Proces w przeglądarce opisano na stronie wideo na tekst.

Szybki start

API wymaga osobistego tokenu dostępu, który można mieć na dwa sposoby. Osoba tworzy go w sekcji Tokens na stronie MCP w koncie, wybiera jego zakresy i decyduje, czy może on kupować minuty. Albo agent otwiera własne konto bez człowieka będącego właścicielem konta: POST /v1/agent/accounts rozpoczyna płatną rejestrację, a POST /v1/agent/accounts/{signup_id}/claim wymienia jednorazowy sekret odbioru na prawdziwe konto i pierwszy token. W obu przypadkach token jest pokazywany raz i wygląda tak: hsr1:<region>:pat.<id>.<secret>. Token wystawiony przez logowanie OAuth serwera MCP działa tu również; zobacz Połączenie. Token nigdy nie może tworzyć, wyświetlać ani unieważniać innych tokenów, a konto ma najwyżej 25 aktywnych; pełny proces konta agenta, z rotacją poświadczeń, opisuje przewodnik Automatyzacja.

Gdy masz token, wywołuj API bezpośrednio. Ten przykład przedstawia nowe konto osobiste przed weryfikacją karty lub zakupem; konto utworzone przez agenta zaczyna od pakietu minut, który opłaciło:

curl https://api.hushscript.com/v1/account \
  -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293"

{
  "balance_seconds": 0,
  "held_seconds": 0,
  "credits_expire_at": null,
  "card_on_file": false,
  "data_region": "eu",
  "limits": {
    "max_active_jobs": 50,
    "max_daily_seconds": 144000,
    "active_jobs": 0,
    "used_today_seconds": 0
  }
}

W odpowiedzi dostajesz saldo w sekundach, sekundy zarezerwowane przez trwające zadania, credits_expire_at (zawsze null, ponieważ minuty nie wygasają), informację, czy karta jest zapisana, region danych oraz limity przyjmowania zadań (max_active_jobs, max_daily_seconds i ich wykorzystanie). Limit dzienny to bieżący, rzeczywisty limit konta, a nie wartość do wpisania na stałe. POST /v1/uploads sprawdza dostępne minuty, a nie kartę: bez wystarczającej liczby minut zwraca 3001 insufficient_balance.

Czy API zamiany mowy na tekst jest bezpłatne?

Nie ma ogólnego bezpłatnego poziomu API, ale proces możesz wypróbować, zanim napiszesz jakikolwiek kod: publiczny podgląd transkrybuje do pięciu minut z jednego nagrania przed zalogowaniem. Konto osobiste spełniające warunki dostaje potem 30 bezpłatnych minut po weryfikacji karty (zobacz Cennik, jak to działa); konto utworzone przez agenta pomija minuty powitalne i zaczyna od pakietu kupionego przy rejestracji. Pełne zadanie API wymaga w obu przypadkach konta i minut.

Automatyzacja od początku do końca

Te same wywołania /v1/ działają z tokenem utworzonym przez osobę w aplikacji albo odebranym przez agenta po płatnej rejestracji (zobacz Automatyzacja). Zapisanie karty wymaga hostowanego Checkout w przeglądarce; agent może go obsłużyć. Późniejsze zakupy off-session nadal mogą zostać odrzucone, jeśli wystawca karty wymaga uwierzytelnienia.

1. Odczytaj konto. GET /v1/account. Jeśli musisz kupić minuty, a card_on_file ma wartość false, najpierw zapisz kartę.

2. Zapisz kartę, jednorazowo. POST /v1/billing/setup-session zwraca checkout_url, session_id i expires_at:

   curl -X POST https://api.hushscript.com/v1/billing/setup-session \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293"

   {
     "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_a1B2c3D4e5F6g7H8",
     "session_id": "seti_1PxYzQ2eZvKYlo2C",
     "expires_at": "2026-09-11T15:45:00Z"
   }

   Otwórz adres URL w przeglądarce, którą kontrolujesz, i dokończ hostowaną stronę Stripe; nic nie jest obciążane, a Hushscript nigdy nie widzi karty. Potem GET /v1/billing/cards pokazuje ją razem z identyfikatorem. POST /v1/billing/cards/default zmienia kartę domyślną, jeśli konto ma ich kilka.

3. Kup minuty. GET /v1/billing/packs zwraca pięć pakietów z polami id, seconds, amount i currency:

   curl https://api.hushscript.com/v1/billing/packs \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293"

   POST /v1/billing/purchase z pack, quick_payment_method_id (identyfikator zapisanej karty) i idempotency_key obciąża kartę w trybie off-session i zwraca nowe balance_seconds:

   curl -X POST https://api.hushscript.com/v1/billing/purchase \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293" \
     -H "Content-Type: application/json" \
     -d '{
       "pack": "300min",
       "quick_payment_method_id": "pm_2QeT4bY7uX9mK3nP",
       "idempotency_key": "purchase-2026-09-11-02"
     }'

   { "balance_seconds": 18000 }

   Wymaga to zakresu billing, włączonych rozliczeń na tokenie i włączonych rozliczeń na koncie. Treść bez identyfikatora karty lub z odrzuconą kartą kończy się błędem 4021 pat_purchase_requires_app; karta, którą wystawca chce zweryfikować, kończy się błędem 4023 pat_purchase_requires_authentication. Żaden z nich nie otwiera strony, której nikt nie może dokończyć.

4. Prześlij. POST /v1/uploads z size_bytes, duration_seconds (od 15 sekund do 10 godzin), opcjonalnymi title, transcription_options, matter_code oraz z idempotency_key:

   curl -X POST https://api.hushscript.com/v1/uploads \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293" \
     -H "Content-Type: application/json" \
     -d '{
       "size_bytes": 41943040,
       "duration_seconds": 1200,
       "title": "Q3 board call",
       "transcription_options": { "speaker_detection": true },
       "idempotency_key": "upload-2026-09-11-02"
     }'

   matter_code to dowolny tekst do 64 znaków i ma znaczenie tylko dla tokenu należącego do przestrzeni zespołu: jest pokazywany przy zadaniu w księdze i raportach wykorzystania tej przestrzeni. Przestrzeń zespołu, w której zasada dotycząca spraw wymaga kodu, odrzuca przesłanie bez niego z błędem org_matter_code_required. client_code jest przyjmowany i ignorowany, ponieważ klient jest atrybutem sprawy, ustawianym przez administratora przestrzeni zespołu.

   Wywołanie rezerwuje kredyt i zwraca job_id oraz pierwszą stronę wstępnie podpisanych adresów URL części:

   {
     "job_id": "job_5e2a91cf4d7b6081a9f3c2e4b5d6a7c8",
     "part_urls": [
       { "n": 1, "url": "https://r2.hushscript.com/uploads/job_5e2a91cf.../part-1?X-Amz-Signature=..." }
     ]
   }

   Wyślij PUT każdej części pod jej adres URL (domyślnie części po 32 MiB, ostatnia mniejsza):

   curl -X PUT "https://r2.hushscript.com/uploads/job_5e2a91cf.../part-1?X-Amz-Signature=..." \
     --data-binary @part-01.bin

   Kolejne strony pobierzesz z GET /v1/uploads/{job}/part-urls?start=<n>, a podczas długiego przesyłania wywołuj POST /v1/uploads/{job}/heartbeat z dużym zapasem przed upływem 20-minutowego limitu bezczynności. Gdy wstępnie podpisane adresy URL są niedostępne albo jedna część się nie powiedzie, PUT /v1/uploads/{job}/parts/{n} wysyła bajty tej części przez API; ponowny PUT zastępuje część, więc ponawianie jest bezpieczne. Obsługiwane: mp3, m4a, mp4 lub mov (używana jest ścieżka audio, ścieżki wideo są pomijane), wav, flac, ogg lub opus, sprawdzane na serwerze; z każdego innego formatu wideo wyodrębnij audio przed przesłaniem.

5. Uruchom i poczekaj. POST /v1/uploads/{job}/complete z n i etag każdej części wysłanej pod wstępnie podpisany adres URL (pomiń parts, gdy każda część poszła przez API):

   curl -X POST https://api.hushscript.com/v1/uploads/job_5e2a91cf4d7b6081a9f3c2e4b5d6a7c8/complete \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293" \
     -H "Content-Type: application/json" \
     -d '{
       "parts": [
         { "n": 1, "etag": "\"9f86d081884c7d65\"" }
       ]
     }'

   Potem odpytuj GET /v1/jobs/{id}: state przechodzi przez uploading, queued i processing do done lub failed, a zakończone zadanie zawiera transcript_id:

   curl https://api.hushscript.com/v1/jobs/job_5e2a91cf4d7b6081a9f3c2e4b5d6a7c8 \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293"

   {
     "id": "job_5e2a91cf4d7b6081a9f3c2e4b5d6a7c8",
     "state": "done",
     "transcript_id": "trs_2b6e1d4a9f7c3088a1b2c3d4e5f6a7b9"
   }

6. Odczytaj wynik. GET /v1/transcripts/{id} zwraca metadane i pełną treść, z nazwami osób mówiących, wykrytym językiem, tagami i datą automatycznego usunięcia:

   curl https://api.hushscript.com/v1/transcripts/trs_2b6e1d4a9f7c3088a1b2c3d4e5f6a7b9 \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293"

   GET /v1/transcripts zwraca listę stronami.

Opcje transkrypcji są takie same jak w aplikacji: language_code albo automatyczne wykrywanie, speaker_detection, medical_mode (wymaga language_code ustawionego na en, es, fr lub de, rozliczany z dopłatą +100%), translation_targets (+25% za każdy język), multichannel, keyterms_prompt, dowolny tekst prompt oraz zapisane dictionary_ids i prompt_preset_id, które wylistuje GET /v1/transcription-context.

Część konta jest nadal dostępna tylko przez MCP. Import z linku, edycja i usuwanie transkrypcji, Insights, eksporty, zapisywanie słowników i zestawów instrukcji oraz ustawienia konta nie mają jeszcze trasy /v1/; serwer MCP obejmuje je wszystkie tym samym tokenem.

Uwierzytelnianie

Każde wywołanie /v1/ niesie token okaziciela w nagłówku Authorization, sprawdzany względem tych samych zakresów, których używa serwer MCP:

Wywołanie poza zakresami tokenu kończy się błędem pat_scope_missing, ze statusem 403. Zakres billing jest też nieaktywny, dopóki rozliczenia nie są włączone zarówno na tokenie, jak i na koncie. Wywołanie rozliczeń z jednym z tych przełączników wyłączonym kończy się tym samym błędem pat_scope_missing; ponowne wystawienie tokenu nie włącza przełącznika na koncie. Token nie może tworzyć, wyświetlać ani unieważniać tokenów, a konto ma najwyżej 25 aktywnych.

Tych 11 zakresów można wybierać. pat:rotate to osobny zakres przyznawany pierwszemu tokenowi konta agenta i jego kolejnym, rotowanym następcom; pozwala temu tokenowi zastąpić samego siebie, a nie zarządzać innymi tokenami. Nie można go wybrać przy tworzeniu tokenu w aplikacji.

Endpointy

Produkcyjny dokument OpenAPI wymienia 38 operacji metoda/ścieżka na 37 ścieżkach. Każda operacja poniżej jest chroniona pokazanym zakresem:

/v1/agent/accounts otwiera rejestrację bez interfejsu, gdy nie ma jeszcze tokenu, /v1/agent/accounts/{signup_id}/claim zamienia opłaconą rejestrację w prawdziwe konto i jego pierwszy token, a /v1/agent/credentials/rotate wystawia następcę dla wywołującego tokenu i unieważnia go, nie dotykając żadnego innego poświadczenia konta. Przewodnik Automatyzacja omawia wszystkie trzy od początku do końca.

Każda lista przyjmuje limit i nieprzezroczysty cursor oraz zwraca next_cursor, który na ostatniej stronie ma wartość null. Przekaż kursor z powrotem bez zmian; koduje on pozycję, więc strona nigdy nie jest pomijana ani powtarzana, gdy między wywołaniami pojawiają się nowe wiersze.

Pełna, aktualna definicja, z parametrami i schematami odpowiedzi każdej operacji, to dokument OpenAPI: traktuj go jako źródło prawdy ponad tą tabelą. Jest udostępniany każdemu tokenowi okaziciela niezależnie od zakresu, więc klient może go pobrać z poświadczeniami, które już ma.

Interfejs MCP

Wolisz narzędzia od surowego HTTP? Serwer MCP udostępnia to samo konto przez 56 narzędzi zamiast tych endpointów, dla klienta, który zna już MCP, a nie REST. Pokazuje tylko te narzędzia, na które pozwalają zakresy podłączonego tokenu.

Limity

Żądania wykonywane tokenem konta osoby są ograniczone do 1200 na minutę na token. Rotowane tokeny konta agenta dzielą ten budżet w obrębie konta. Trasy rozliczeń wywołujące Stripe mają dla wywołujących z PAT węższy wspólny limit 60 na minutę na konto: sesja konfiguracji, zakup, zmiany karty domyślnej, usunięcie karty i chybienia pamięci podręcznej listy kart. Zwykłe ograniczanie zwraca 429 rate_limited z Retry-After w sekundach; tyle poczekaj przed ponowieniem. Zakupy konta agenta lub PAT konta osoby dzielą limit 3 prób na kroczące 24 godziny na konto. Liczy się zakup przy rejestracji agenta; odrzucenia i błędy po rezerwacji też się liczą. Zakup w sesji przeglądarki osoby jest z limitu wyłączony. Odmowa z powodu limitu zwraca HTTP 429 z 4038 agent_purchase_capped i Retry-After. Nagrania mogą trwać od 15 sekund do 10 godzin. GET /v1/account zwraca bieżące limity przyjmowania zadań konta (max_active_jobs, max_daily_seconds).

Piaskownica

Nie ma ogólnej piaskownicy transkrypcji: zwykłe wywołania /v1/ działają na prawdziwych kontach, a zakupy wydają prawdziwe pieniądze. Wyjątkiem jest sprawdzanie rejestracji: POST /v1/agent/accounts przyjmuje dry_run: true, zwraca signup_id z prefiksem dry_, którego nie można odebrać, i nie otwiera ani sesji Stripe, ani konta.

Błędy

Błąd to treść JSON ze stałym numerycznym code i slugiem error, ze statusem HTTP pokazanym poniżej. Treści błędów /v1/ to zamrożona projekcja: error, code i stały zestaw kluczy szczegółów. Kształt błędów /api nie jest zamrożony i może zawierać więcej. Kody, które musi obsłużyć automatyczny wywołujący:

Dokument OpenAPI podaje dokładny kod, który może zwrócić każda operacja, a serwer MCP publikuje cały katalog jako zasób hushscript://error-codes.