Automatisierte Nutzung

Ein Hushscript-Konto zu eröffnen brauchte früher zumindest einmal einen Menschen. Das ist nicht mehr die ganze Geschichte. Ein zahlungsorientierter Ablauf lässt einen Agenten ein eigenes Konto eröffnen, finanzieren und betreiben, ohne dass irgendwo ein menschlicher Kontoinhaber im Spiel ist. /developers und /mcp dokumentieren die beiden Schnittstellen, die dieses Konto danach nutzt; diese Seite ist die Anleitung, um eines zu bekommen.

Registrieren

POST /v1/agent/accounts startet eine kopflose Registrierung. Es gibt noch kein Konto, kein Cookie und kein Token: nur einen ausstehenden Kauf.

curl -X POST https://api.hushscript.com/v1/agent/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "contact_email": "ops@example-agent.dev",
    "pack_id": "300min",
    "accept_terms_version": "2026-08-01",
    "agent": {
      "name": "research-crawler",
      "platform": "langgraph",
      "contact_url": "https://example-agent.dev/bots/research-crawler"
    }
  }'

{
  "signup_id": "hsr1:eu:4c3a1f9e7b2d4e6f8a0c1b2d3e4f5061",
  "claim_secret": "cs_9f3d2a1b7e6c4f5a8b9d0e1f2a3b4c5d",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_a1B2c3D4e5F6",
  "pack": "300min",
  "amount": 599,
  "currency": "usd",
  "expires_at": 1789112400
}

contact_email dient nur für Belege und Benachrichtigungen, niemals als Login. pack_id ist eines von 45min, 300min, 900min, 1800min, 6000min; senden Sie amount oder currency niemals selbst, beide werden auf dem Server aus dem Paket abgeleitet. Nur die beiden kleinsten Pakete, 45min und 300min, können bei der Registrierung gekauft werden. Ein größeres pack_id wird abgelehnt, und die Ablehnung enthält details.allowed_packs mit den Paketen, die dieses Konto gerade kaufen darf, sodass ein Aufrufer es ohne Raten erneut versuchen kann. Der Rest der Stufenleiter schaltet sich mit dem Alter frei, nicht mit dem Volumen: siehe Was ein neues Konto kaufen darf weiter unten. accept_terms_version muss exakt der aktuellen Richtlinienversion des Servers entsprechen, sonst schlägt der Aufruf mit policy_version_stale fehl, dessen Body den aktuellen Wert nennt. Ein optionaler data_region-Hinweis wird nur berücksichtigt, wenn er mit der Region übereinstimmt, die Ihr Netzwerkstandort ohnehin nahelegt. Ein optionales dry_run: true validiert alles ohne Stripe-Sitzung und ohne Belastung; seine signup_id trägt das Präfix dry_ und kann nie beansprucht werden.

claim_secret wird nur einmal angezeigt, in dieser Antwort. Hushscript speichert nur dessen Hash. Wird es vor dem Claim-Aufruf verloren, ist die Registrierung verloren: Es gibt keinen Wiederherstellungsweg für ein Claim-Secret, und die treuhänderisch gehaltene Zahlung wird durch den unten beschriebenen Sweep erstattet, nicht durch eine Abfrage zurückgegeben.

Checkout im eigenen Browser abschließen

checkout_url ist eine gehostete Stripe-Checkout-Seite. Sie ist der einzige Schritt in diesem gesamten Ablauf, der einen Browser braucht, und es muss nicht der Browser eines Menschen sein: Ein Agent kann sie mit eigener Automatisierung steuern (Kartenfelder ausfüllen, absenden, der Weiterleitung folgen). Hushscript sieht die Kartendaten so oder so nie; Stripe schon. Das Zeitfenster, um sie abzuschließen und danach zu beanspruchen, beträgt 30 Minuten, das expires_at oben.

Eine Registrierung, die bezahlt, aber nie beansprucht wird, wird automatisch durch einen stündlichen Sweep erstattet, etwa eine Stunde nachdem sich dieses 30-Minuten-Fenster schließt. Die Erstattung ist vollständig, denn Minuten werden erst bei der Beanspruchung einem Guthaben gutgeschrieben, sodass eine unbeanspruchte Registrierung nie welche zum Verbrauchen hatte.

Konto beanspruchen

POST /v1/agent/accounts/{signup_id}/claim verwandelt eine bezahlte, unbeanspruchte Registrierung in einem einzigen Aufruf in ein echtes Konto.

curl -X POST https://api.hushscript.com/v1/agent/accounts/hsr1:eu:4c3a1f9e7b2d4e6f8a0c1b2d3e4f5061/claim \
  -H "Content-Type: application/json" \
  -d '{"claim_secret": "cs_9f3d2a1b7e6c4f5a8b9d0e1f2a3b4c5d"}'

{
  "user_id": "usr_7d1a2b3c4d5e6f708192a3b4c5d6e7f8",
  "pat": "hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170",
  "scopes": [
    "transcripts:read",
    "transcripts:write",
    "transcribe",
    "account:read",
    "export",
    "billing",
    "pat:rotate"
  ],
  "balance_seconds": 18000
}

Das Beanspruchen ist Einmalgebrauch. Es erstellt genau ein Konto mit einer synthetischen, nicht auflösbaren Login-Identität dahinter, gewährt das bezahlte Paket genau einmal, selbst wenn der Aufruf wiederholt wird, und prägt genau ein PAT: den pat-Wert oben, ebenfalls nur einmal angezeigt.

Ein falsches Secret, eine unbekannte signup_id, eine bereits beanspruchte, eine erstattete und eine abgelaufene Registrierung beantworten alle mit demselben Fehler agent_claim_invalid. Ein Aufrufer kann diese Fälle absichtlich nicht anhand der Antwort unterscheiden. Erst wenn das Secret selbst stimmt, kommt der Zahlungsstatus ins Spiel: Eine Checkout Session, die noch nicht abgerechnet ist, antwortet stattdessen mit wrong_state.

Das balance_seconds oben ist das gesamte Startguthaben. Agenten-Konten erhalten keinen Willkommensbonus und keine kostenlosen Minuten durch Kartenverifizierung, wie es beim ersten Konto einer Person der Fall ist; sie starten mit nichts außer dem Paket, das sie bezahlt haben. Das ist Absicht, keine Lücke: Das Konto war bereits bezahlt, bevor es existierte.

Weitere Minuten kaufen

Von hier an verhält sich das Konto wie jedes andere, über dieselbe /v1/-Oberfläche, die /developers vollständig dokumentiert.

curl -X POST https://api.hushscript.com/v1/billing/purchase \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170" \
  -H "Content-Type: application/json" \
  -d '{
    "pack": "300min",
    "quick_payment_method_id": "pm_1PqR2sT3uV4wX5yZ",
    "idempotency_key": "purchase-2026-09-11-01"
  }'

{
  "balance_seconds": 36000
}

Das erfordert den Scope billing, den die Claim-Antwort oben bereits gewährt hat, und teilt sich mit der Route zum Speichern der Karte ein engeres Limit von 60 Anfragen pro Minute und Konto, noch vor dem Stripe-Aufruf, den jede der beiden macht.

Was ein neues Konto kaufen darf

Die Paketgröße schaltet sich anhand des Alters abgerechneter Zahlungen frei, nicht danach, wie viel ein Konto ausgibt. Ein Kauf zählt erst zur nächsten Stufe, sobald er 7 Tage nach seinem eigenen Zahlungsdatum liegt, sodass ein brandneues Konto die großen Pakete nicht durch schnelles Kaufen erreichen kann.

Ein abgelehnter Kauf nennt die aktuelle Auswahl in details.allowed_packs, statt blind zu scheitern. Der Registrierungsaufruf wendet die erste Zeile dieser Tabelle an, weshalb die Anleitung oben 300min kauft und nicht etwas Größeres. Unabhängig von der Stufenleiter begrenzt eine gleitende 24-Stunden-Verbrauchsgrenze, wie schnell Guthaben ausgegeben werden kann, das das Streitfenster noch nicht überschritten hat.

Transkribieren

Hochladen und Transkribieren laufen über denselben mehrteiligen Ablauf wie bei jedem anderen Konto.

curl -X POST https://api.hushscript.com/v1/uploads \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170" \
  -H "Content-Type: application/json" \
  -d '{
    "size_bytes": 48213504,
    "duration_seconds": 1860,
    "title": "weekly-standup-2026-09-11",
    "idempotency_key": "upload-2026-09-11-01"
  }'

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

Laden Sie jeden Teil per PUT an seine vorsignierte URL hoch, senden Sie dann ein POST an /complete desselben Jobs mit dem n und etag jedes so gesendeten Teils. Pollen Sie danach den Job:

curl https://api.hushscript.com/v1/jobs/job_3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "id": "job_3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d",
  "state": "done",
  "transcript_id": "trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180"
}

curl https://api.hushscript.com/v1/transcripts/trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180 \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "id": "trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180",
  "language": "en",
  "duration_seconds": 1860,
  "body": "..."
}

PAT rotieren

Ein Maschinenkonto hat kein Passwort und kein nutzbares Postfach, daher gibt es keinen „Passwort vergessen”-Weg, falls ein PAT durchsickert oder einfach ersetzt werden muss. Rotation ist dieser Weg.

curl -X POST https://api.hushscript.com/v1/agent/credentials/rotate \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "pat": "hsr1:eu:pat.p9q8r7.1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "pat_id": "p9q8r7",
  "scopes": [
    "transcripts:read",
    "transcripts:write",
    "transcribe",
    "account:read",
    "export",
    "billing",
    "pat:rotate"
  ],
  "expires_at": null
}

Der Aufruf braucht keinen Body. Er prägt atomar einen Nachfolger und widerruft das Token, das die Anfrage authentifiziert hat, sodass das alte PAT beim allernächsten damit ausgeführten Aufruf fehlschlägt. Der Nachfolger übernimmt die Scopes, die Abrechnungsberechtigung, den Namen, das Client-Label und die Ablaufrichtlinie des Vorgängers. Diese Route fasst nichts an außer dem eigenen PAT des Aufrufers: Sie kann kein anderes Zugangstoken des Kontos auflisten, prägen oder widerrufen. Es ist der einzige Weg zur Wiederherstellung von Zugangsdaten, den ein Maschinenkonto hat, also rotieren Sie, bevor das alte PAT verworfen wird, nicht danach.

Fehler

Diese vier sind spezifisch für Agenten-Konten und werden von einem menschlichen Konto nie erreicht:

Sobald das Claim-Secret selbst stimmt, antwortet eine unbezahlte Checkout Session mit wrong_state (4001) statt mit agent_claim_invalid. Der vollständige Katalog ist das OpenAPI-Dokument.

Limits

Aufrufe sind auf 1.200 pro Minute begrenzt. Bei einem Agenten-Konto gehört dieses Budget dem Konto, nicht dem einzelnen Token: Jedes Zugangstoken in der Rotationslinie greift auf dasselbe Budget zu, Rotation eines PAT verschafft dem Nachfolger also kein frisches Kontingent. Die beiden abrechnungsbezogenen Schreibvorgänge, das Speichern einer Karte und der Kauf eines Pakets, teilen sich ein engeres Limit von 60 pro Minute und Konto, noch vor dem Stripe-Aufruf, den jeder der beiden macht. Die 24-Stunden-Kaufgrenze oben wird auf dieselbe Weise gezählt, pro Konto statt pro Zugangstoken.

Mehr erfahren

Diese Seite behandelt den Lebenszyklus des Kontos: es eröffnen, finanzieren und sein Zugangstoken am Leben halten. Alles, was das Konto danach tun kann, zeigt die REST-API, einschließlich des vollständigen OpenAPI-Dokuments, oder der MCP-Server für dasselbe Konto über Tools statt über rohes HTTP.