Speech-to-Text-API für Aufnahmen

Die Speech-to-Text-API für Aufnahmen von Hushscript nimmt Audiodateien über /v1/ an. Anschließend kann Ihr Skript den Job abfragen und das Transkript lesen. Der Ablauf dient der Online-Transkription, nicht dem Live-Streaming oder dem direkten Zugriff auf ein Spracherkennungsmodell. Der MCP-Server verwendet dasselbe Konto, Guthaben und denselben Bearer-Token, wenn Ihr Client Tools gegenüber HTTP-Aufrufen bevorzugt.

Audio und Video über die API transkribieren

Die API für Audiotranskription akzeptiert vorbereitete Audiodateien, auch Sprachaufnahmen. Für eine STT-Integration (Speech-to-Text) reichen Sie aufgezeichnete Dateien ein; Live-Streaming vom Mikrofon ist nicht verfügbar. Für die Videotranskription laden Sie eine MP4- oder MOV-Datei mit Audiospur unverändert hoch: Der Server liest die Audiospur und überspringt das Video. Extrahieren Sie bei jedem anderen Videoformat zuerst das Audio; die API akzeptiert keine Video-URL. Den Browserablauf erklärt Video in Text.

Quickstart

Die API braucht einen persönlichen Zugriffstoken, und es gibt zwei Wege, an einen zu kommen. Eine Person erstellt einen unter Neuen Token erstellen auf der MCP-Seite im Konto, wählt dessen Berechtigungen aus und entscheidet, ob er Minuten kaufen darf. Oder ein Agent eröffnet sein eigenes Konto ohne menschlichen Kontoinhaber: POST /v1/agent/accounts startet eine bezahlte Registrierung, und POST /v1/agent/accounts/{signup_id}/claim tauscht dessen einmaliges Geheimnis zur Kontoaktivierung gegen ein echtes Konto und einen ersten Token ein. So oder so wird der Token einmal angezeigt und sieht aus wie hsr1:<region>:pat.<id>.<secret>. Ein Token, der über die OAuth-Anmeldung des MCP-Servers erstellt wurde, funktioniert hier ebenfalls; siehe Verbinden. Ein Token kann nie andere Token erstellen, auflisten oder widerrufen, und ein Konto hält höchstens 25 aktive; der vollständige Agenten-Konto-Ablauf, einschließlich Rotation der Zugangsdaten, ist die Anleitung Automatisierte Nutzung.

Sobald Sie einen Token besitzen, rufen Sie die API direkt auf. Dieses Beispiel steht für ein neues persönliches Konto vor der Kartenverifizierung oder einem Kauf; ein von einem Agenten angelegtes Konto startet mit dem Minutenpaket, das es bezahlt hat:

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

Die Antwort enthält das Guthaben in Sekunden, die für laufende Jobs reservierten Sekunden, credits_expire_at (immer null, da Minuten nicht verfallen), ob eine Karte gespeichert ist, die Datenregion und die Zulassungsgrenzen (max_active_jobs, max_daily_seconds und deren Nutzung). Die Tagesgrenze ist die aktuell wirksame Grenze des Kontos, kein Wert, den Sie fest im Code hinterlegen sollten. POST /v1/uploads prüft die verfügbaren Minuten, nicht die Karte: ohne ausreichend Minuten antwortet es mit 3001 insufficient_balance.

Ist die Speech-to-Text-API kostenlos?

Es gibt keinen allgemeinen kostenlosen API-Tarif. Sie können den Ablauf aber vor dem Programmieren ausprobieren: Die öffentliche Vorschau transkribiert vor der Anmeldung bis zu fünf Minuten einer Aufnahme. Ein berechtigtes persönliches Konto erhält anschließend nach der Kartenverifizierung 30 kostenlose Minuten (wie das funktioniert, steht unter Preise). Ein von einem Agenten erstelltes Konto erhält keine Willkommensminuten und startet mit dem bei der Registrierung gekauften Paket. Ein vollständiger API-Job benötigt in beiden Fällen ein Konto und Minuten.

Von Anfang bis Ende automatisieren

Dieselben /v1/-Aufrufe funktionieren mit einem Token, den eine Person in der App erstellt hat, oder mit einem, den ein Agent nach der bezahlten Registrierung durch die Kontoaktivierung erhalten hat (siehe Automatisierte Nutzung). Das Speichern einer Karte erfordert den gehosteten Checkout in einem Browser; ein Agent darf diesen steuern. Spätere Off-Session-Käufe können weiterhin abgelehnt werden, wenn der Kartenaussteller eine Authentifizierung verlangt.

1. Kontodaten lesen. GET /v1/account. Wenn Sie Minuten kaufen möchten und card_on_file false ist, speichern Sie zuerst eine Karte.

2. Einmalig eine Karte speichern. POST /v1/billing/setup-session liefert eine checkout_url, eine session_id und ein 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"
   }

   Öffnen Sie die URL in einem Browser, den Sie kontrollieren, und schließen Sie die gehostete Stripe-Seite ab; es wird nichts belastet, und Hushscript sieht die Karte nie. Danach listet GET /v1/billing/cards sie mit ihrer ID auf. POST /v1/billing/cards/default wechselt die Standardkarte, wenn das Konto mehrere hält.

3. Minuten kaufen. GET /v1/billing/packs listet die fünf Pakete mit id, seconds, amount und currency:

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

   POST /v1/billing/purchase mit pack, quick_payment_method_id (der ID der gespeicherten Karte) und einem idempotency_key belastet die Karte off-session und liefert das neue 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 }

   Dafür sind die Berechtigung billing sowie die aktivierte Abrechnung auf dem Token und für das Konto erforderlich. Ein Body ohne Karten-ID oder eine abgelehnte Karte wird mit 4021 pat_purchase_requires_app zurückgewiesen; eine Karte, für die der Aussteller eine zusätzliche Authentifizierung verlangt, wird mit 4023 pat_purchase_requires_authentication zurückgewiesen. Keiner der beiden Fälle öffnet eine Seite, die niemand abschließen kann.

4. Hochladen. POST /v1/uploads mit size_bytes, duration_seconds (15 Sekunden bis 10 Stunden), einem optionalen title, transcription_options, matter_code und einem 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 ist Freitext von höchstens 64 Zeichen, und er hat nur eine Bedeutung für einen Token, der zu einem Workspace gehört: Er wird zum Auftrag im Journal und in den Nutzungsberichten dieses Workspaces angezeigt. Ein Workspace, dessen Aktenzeichen-Richtlinie auf verpflichtend gesetzt ist, weist einen Upload ohne Aktenzeichen mit org_matter_code_required zurück. client_code wird angenommen und ignoriert, weil der Mandant ein Attribut der Akte ist, festgelegt von einem Workspace-Admin.

   Der Aufruf setzt eine Guthabenreservierung und liefert eine job_id sowie eine erste Seite vorsignierter Teil-URLs:

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

   Senden Sie jeden Teil per PUT an seine URL (standardmäßig 32-MiB-Teile, der letzte kleiner):

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

   Holen Sie weitere Seiten über GET /v1/uploads/{job}/part-urls?start=<n>, und rufen Sie während eines langen Transfers gut innerhalb des 20-minütigen Leerlauf-Timeouts POST /v1/uploads/{job}/heartbeat auf. Sind vorsignierte URLs nicht verfügbar, oder schlägt ein Teil fehl, sendet PUT /v1/uploads/{job}/parts/{n} die Bytes dieses Teils stattdessen durch die API; ein wiederholtes PUT ersetzt den Teil, sodass Wiederholungen gefahrlos sind. Unterstützt: mp3, m4a, mp4 oder mov (die Audiospur wird verwendet, Videospuren werden übersprungen), wav, flac, ogg oder opus, serverseitig geprüft; extrahieren Sie bei jedem anderen Videoformat das Audio, bevor Sie es hochladen.

5. Starten und warten. POST /v1/uploads/{job}/complete mit n und etag jedes an eine vorsignierte URL gesendeten Teils (lassen Sie parts weg, wenn jeder Teil durch die API ging):

   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\"" }
       ]
     }'

   Pollen Sie danach GET /v1/jobs/{id}: state durchläuft uploading, queued und processing bis zu done oder failed, und ein abgeschlossener Job trägt eine 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. Das Ergebnis lesen. GET /v1/transcripts/{id} liefert die Metadaten und den vollständigen Inhalt, mit Sprechernamen, erkannter Sprache, Tags und dem Datum der automatischen Löschung:

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

   GET /v1/transcripts paginiert die Liste.

Die Transkriptionsoptionen sind wortgleich die der App: language_code oder automatische Erkennung der Ausgangssprache, speaker_detection, medical_mode (braucht language_code in en, es, fr oder de, berechnet mit +100 %), translation_targets (+25 % pro Sprache), multichannel, keyterms_prompt, ein frei formulierter prompt, sowie die gespeicherten dictionary_ids und prompt_preset_id, die GET /v1/transcription-context listet.

Ein Teil des Kontos ist weiterhin nur über MCP erreichbar. Import per Link, Bearbeiten oder Löschen von Transkripten, Insights, Exporte, das Speichern von Wörterbüchern und Prompt-Vorlagen sowie Kontoeinstellungen haben noch keine /v1/-Route; der MCP-Server deckt sie alle mit demselben Token ab.

Authentifizierung

Jeder /v1/-Aufruf trägt einen Bearer-Token im Authorization-Header, der anhand derselben Berechtigungen geprüft wird, die der MCP-Server verwendet:

Ein Aufruf außerhalb der Berechtigungen des Tokens schlägt mit pat_scope_missing fehl, mit Status 403. Die Berechtigung billing bleibt zudem wirkungslos, sofern die Abrechnung nicht sowohl auf dem Token als auch für das Konto aktiviert ist. Ein Abrechnungsaufruf, bei dem einer der beiden Schalter aus ist, schlägt mit demselben pat_scope_missing fehl; ein erneutes Erstellen des Tokens schaltet den Kontoschalter nicht ein. Ein Token kann keine Token erstellen, auflisten oder widerrufen, und ein Konto hält höchstens 25 aktive.

Diese 11 Berechtigungen sind beim Erstellen auswählbar. pat:rotate ist eine separate Berechtigung, die dem ersten Token eines Agenten-Kontos und dessen rotierten Nachfolgern gewährt wird; sie erlaubt es diesem Token, sich selbst zu ersetzen, nicht andere Token zu verwalten. Sie lässt sich beim Erstellen eines Tokens in der App nicht auswählen.

Endpunkte

Das produktive OpenAPI-Dokument listet 38 Methoden-/Pfad-Operationen über 37 Pfade. Jede Operation unten ist durch die gezeigte Berechtigung geschützt:

/v1/agent/accounts startet eine Registrierung ohne Bedienoberfläche und zunächst ohne Token, /v1/agent/accounts/{signup_id}/claim aktiviert nach der bezahlten Registrierung das Konto und liefert dessen ersten Token, und /v1/agent/credentials/rotate erstellt einen Nachfolger für den aufrufenden Token und setzt diesen außer Kraft, sobald der Nachfolger zum ersten Mal verwendet wird, ohne ein anderes Zugangstoken des Kontos anzufassen. Die Anleitung Automatisierte Nutzung deckt alle drei von Anfang bis Ende ab.

Jede Liste nimmt ein limit und einen opaken cursor entgegen und liefert einen next_cursor, der auf der letzten Seite null ist. Geben Sie den Cursor unverändert zurück; er kodiert die Position, sodass eine Seite nie übersprungen oder wiederholt wird, wenn zwischen Aufrufen neue Zeilen entstehen.

Die vollständige, aktuelle Definition, mit Parametern und Antwortschemata für jede Operation, ist das OpenAPI-Dokument: Nutzen Sie es als maßgebliche Quelle gegenüber dieser Tabelle. Es wird jedem Bearer-Token unabhängig von dessen Berechtigungen ausgeliefert, sodass ein Client es mit den Zugangsdaten abrufen kann, die er ohnehin besitzt.

MCP-Schnittstelle

Bevorzugen Sie Tools gegenüber rohem HTTP? Der MCP-Server stellt dasselbe Konto über 56 Tools statt über diese Endpunkte bereit, für einen Client, der bereits MCP statt REST spricht. Er bietet nur die Tools an, die die Berechtigungen des verbundenen Tokens erlauben.

Limits

Aufrufe mit dem Token eines menschlichen Kontos sind auf 1.200 pro Minute und Token begrenzt. Die rotierten Token eines Agenten-Kontos teilen sich dieses Budget kontoweit. Billing-Routen, die Stripe aufrufen, teilen sich für PAT-Aufrufer ein engeres Budget von 60 pro Minute und Konto: Setup-Session, Kauf, Wechsel der Standardkarte, Entfernen einer Karte und Cache-Fehlzugriffe der Kartenliste. Normale Drosselung antwortet mit 429 rate_limited und Retry-After in Sekunden; warten Sie so lange, bevor Sie es erneut versuchen. Käufe eines Agenten-Kontos oder per PAT eines menschlichen Kontos teilen sich ein Limit von 3 Versuchen pro rollierenden 24 Stunden und Konto. Der Registrierungskauf des Agenten zählt mit; auch Ablehnungen oder Fehler nach der Reservierung zählen. Ein Kauf in einer menschlichen Browser-Sitzung ist ausgenommen. Eine Ablehnung wegen des Limits antwortet mit HTTP 429, 4038 agent_purchase_capped und Retry-After. Aufnahmen können von 15 Sekunden bis 10 Stunden lang sein. GET /v1/account meldet die aktuellen Zulassungsgrenzen des Kontos (max_active_jobs, max_daily_seconds).

Sandbox

Es gibt keine allgemeine Transkriptions-Sandbox: Normale /v1/-Aufrufe laufen gegen echte Konten, und Käufe kosten echtes Geld. Die Ausnahme ist die Registrierungsprüfung: POST /v1/agent/accounts akzeptiert dry_run: true, liefert eine dry_-Registrierungs-ID, mit der sich kein Konto aktivieren lässt, und eröffnet weder eine Stripe-Sitzung noch ein Konto.

Fehler

Ein Fehler ist ein JSON-Body mit einem stabilen numerischen code und einem error-Slug, beim unten gezeigten HTTP-Status. /v1/-Fehlerbodys sind eine feste Projektion: error, code und ein fester Satz von Detail-Schlüsseln. Die Fehlerform von /api ist nicht fest und kann mehr enthalten. Die Codes, die ein automatisierter Aufrufer behandeln muss:

Das OpenAPI-Dokument nennt den genauen Code, den jede Operation zurückgeben kann, und der MCP-Server veröffentlicht den vollständigen Katalog als Ressource hushscript://error-codes.