Hushscript Developer API

Hushscript beantwortet auch einfache REST-Aufrufe, für Agenten und Skripte, die lieber einen HTTP-Endpunkt aufrufen als einen MCP-Client betreiben. Es ist durchgehend dasselbe Konto, dasselbe Guthaben und dieselben Bearer-Token: Nichts hier ändert, wie Transkription bepreist oder gespeichert wird.

Quickstart

Die API braucht einen persönlichen Zugriffstoken, und es gibt zwei Wege, an einen zu kommen. Eine Person erstellt einen unter Tokens 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 ganz ohne Person: POST /v1/agent/accounts startet eine bezahlte Registrierung, und POST /v1/agent/accounts/{signup_id}/claim tauscht dessen einmaliges Claim-Secret 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 geprägt wurde, funktioniert hier ebenfalls; siehe Verbinden. Ein Token kann nie andere Token prägen, 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:

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": 3,
    "max_daily_seconds": 36000,
    "active_jobs": 0,
    "daily_seconds_used": 0
  }
}

Das beantwortet das Guthaben in Sekunden, die von laufenden Jobs belegten Sekunden, das Ablaufdatum des Guthabens, ob eine Karte gespeichert ist, die Datenregion und die Zulassungsgrenzen (max_active_jobs, max_daily_seconds und deren Nutzung). Ein frisches Konto startet mit einem Guthaben von null. POST /v1/uploads prüft das Guthaben, nicht die Karte: ohne Minuten antwortet es mit 3001 insufficient_balance. Die Karte ist der Weg, wie das Guthaben dorthin gelangt, denn die einmalige Kartenverifizierung in der App gibt die 30 kostenlosen Minuten frei, und Pakete werden gegen eine gespeicherte Karte gekauft.

Von Anfang bis Ende automatisieren

Alles, was nach der Kontoeröffnung passiert, läuft ohne Person, egal ob eine Person das Konto in der App eröffnet hat oder ein Agent es über /v1/agent/accounts eröffnet hat (siehe Automatisierte Nutzung). Ein einziger Browserschritt bleibt, und ein Agent darf diesen Browser selbst steuern.

1. Das Konto lesen. GET /v1/account. Ist card_on_file falsch, zuerst eine Karte speichern.

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

   Das braucht die Berechtigung billing auf dem Token und Abrechnung, die für das Konto eingeschaltet ist. Ein Body ohne Karten-id, oder eine abgelehnte Karte, wird mit 4021 pat_purchase_requires_app zurückgewiesen; eine Karte, die der Aussteller herausfordern möchte, 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 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"
     }'

   Es setzt eine Guthabenreservierung und beantwortet 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=..." }
     ]
   }

   PUT jeden Teil 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. Nur Audio: mp3, m4a, wav, flac, ogg oder opus, höchstens 5 GB, serverseitig geprüft; extrahieren Sie die Tonspur aus einem Video, 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, 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, geprüft gegen dieselben Berechtigungen, 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, solange der Kontoinhaber die Abrechnung nicht für das Konto in der App eingeschaltet hat; ein Abrechnungsaufruf auf einem Konto, bei dem dieser Schalter aus ist, schlägt mit demselben pat_scope_missing fehl, und ein erneutes Prägen des Tokens hebt das nicht auf. Ein Token kann keine Token erstellen, auflisten oder widerrufen, und ein Konto hält höchstens 25 aktive.

Endpunkte

Heute live, jeder durch die gezeigte Berechtigung geschützt:

/v1/agent/accounts eröffnet eine kopflose Registrierung ohne Token, /v1/agent/accounts/{signup_id}/claim verwandelt eine bezahlte Registrierung in ein echtes Konto samt erstem Token, und /v1/agent/credentials/rotate prägt einen Nachfolger für den aufrufenden Token und widerruft diesen, 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 undurchsichtigen cursor entgegen und beantwortet 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: Behandeln Sie es als maßgeblicher als diese 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 51 Tools statt über diese Endpunkte bereit, für einen Client, der bereits MCP statt REST spricht.

Limits

Aufrufe mit einem Token sind auf 1.200 pro Minute und Token begrenzt. POST /v1/billing/setup-session und POST /v1/billing/purchase teilen sich ein engeres Budget von 60 pro Minute und Konto, noch vor dem Stripe-Aufruf, den sie machen würden. Ein abgelehnter Aufruf antwortet mit 429 rate_limited und einem Retry-After-Header, der die Wartezeit in Sekunden angibt; warten Sie so lange, bevor Sie es erneut versuchen. Uploads sind auf 5 GB und 10 Stunden begrenzt, mit einem Minimum von 15 Sekunden, und die eigenen Zulassungsgrenzen des Kontos (max_active_jobs, max_daily_seconds) meldet GET /v1/account.

Sandbox

Es gibt keinen Testmodus: Jeder /v1/-Aufruf läuft gegen ein echtes Konto, und der Kauf von Minuten kostet echtes Geld.

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.