Recorded audio के लिए Speech to text API

Hushscript की speech to text API /v1/ के ज़रिए recorded audio लेती है। फिर आपकी script job को poll करके transcript पढ़ सकती है। यह online transcription workflow है, live streaming या raw recognition-model endpoint नहीं। अगर आपका client HTTP calls के बजाय tools इस्तेमाल करता है, तो MCP server उसी account, balance और bearer token के साथ काम करता है।

API से audio और video transcription

Audio transcription API तैयार audio files लेती है, जिनमें recorded voice भी शामिल है। STT (speech-to-text) integration के लिए recorded files भेजें; live microphone streaming उपलब्ध नहीं है। Video transcription के लिए audio track वाली MP4 या MOV file को जैसी है वैसी ही upload करें: server audio track पढ़ता है और video छोड़ देता है। किसी दूसरे video format से पहले audio निकालें; API video URL नहीं लेती। Browser workflow वीडियो से टेक्स्ट पर समझाया गया है।

जल्दी शुरुआत करें

API के लिए personal access token चाहिए, जो दो तरीक़ों से मिल सकता है। कोई व्यक्ति account के MCP page पर नया टोकन बनाएं से token बनाता है, उसके scopes चुनता है और तय करता है कि वह मिनट खरीद सकेगा या नहीं। या कोई agent बिना किसी human account holder के अपना account खोलता है: POST /v1/agent/accounts paid signup शुरू करता है, और POST /v1/agent/accounts/{signup_id}/claim one-time claim secret के बदले असली account और पहला token देता है। दोनों स्थितियों में token सिर्फ़ एक बार दिखता है और hsr1:<region>:pat.<id>.<secret> जैसा होता है। MCP server के OAuth sign-in से बना token भी यहां काम करता है; कनेक्ट करें देखें। Token दूसरे tokens बना, list या revoke नहीं कर सकता, और account में ज़्यादा से ज़्यादा 25 active tokens हो सकते हैं। Credential rotation सहित पूरा agent-account flow Agents के लिए automatic transcription में समझाया गया है।

Token मिलने के बाद सीधे API call करें। यह उदाहरण card verification या purchase से पहले के नए personal account का है; agent-created account उस minute pack से शुरू होता है जिसके लिए उसने भुगतान किया है:

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

इससे seconds में balance, चल रहे jobs के लिए hold किए गए seconds, credits_expire_at (हमेशा null, क्योंकि मिनट expire नहीं होते), saved card की स्थिति, data region और admission limits (max_active_jobs, max_daily_seconds और उनका इस्तेमाल) मिलते हैं। Daily limit account की वर्तमान effective limit है; इसे hardcode न करें। POST /v1/uploads उपलब्ध मिनट जांचता है, card नहीं: पर्याप्त मिनट न होने पर 3001 insufficient_balance मिलता है।

क्या speech to text API मुफ़्त है?

कोई सामान्य free API tier नहीं है, लेकिन code लिखने से पहले workflow आज़मा सकते हैं: public preview sign in से पहले एक recording के अधिकतम पांच मिनट transcribe करता है। पात्र personal account को फिर card verification के बाद 30 मुफ़्त मिनट मिलते हैं (यह कैसे काम करता है, इसके लिए कीमतें देखें)। Agent-created account को welcome minutes नहीं मिलते; वह signup पर खरीदे pack से शुरू होता है। दोनों स्थितियों में पूरे API job के लिए account और मिनट चाहिए।

शुरू से अंत तक automation

वही /v1/ calls app में किसी व्यक्ति के बनाए token या paid signup के बाद agent के claim किए token के साथ काम करती हैं (Agents के लिए automatic transcription देखें)। Card सहेजने के लिए browser में hosted Checkout पूरा करना होता है; agent browser चला सकता है। बाद की off-session purchases भी अस्वीकार हो सकती हैं अगर card issuer authentication मांगता है।

1. Account पढ़ें। GET /v1/account। अगर मिनट खरीदने हैं और card_on_file false है, तो पहले card सहेजें।

2. एक बार card सहेजें। POST /v1/billing/setup-session से checkout_url, session_id और 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"
   }

   अपने नियंत्रण वाले browser में URL खोलकर hosted Stripe page पूरा करें; कोई charge नहीं लगता और Hushscript card नहीं देखता। फिर GET /v1/billing/cards card को उसके id के साथ list करता है। कई cards होने पर POST /v1/billing/cards/default default बदलता है।

3. मिनट खरीदें। GET /v1/billing/packs पांच packs को id, seconds, amount और currency के साथ list करता है:

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

   POST /v1/billing/purchase, pack, quick_payment_method_id (saved card का id) और idempotency_key के साथ card पर off-session charge करता है और नया 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 }

   इसके लिए billing scope, token पर enabled billing और account के लिए enabled billing चाहिए। Card id के बिना body या declined card पर 4021 pat_purchase_requires_app मिलता है; issuer challenge मांगने पर 4023 pat_purchase_requires_authentication मिलता है। इनमें से कोई भी ऐसा page नहीं खोलता जिसे कोई पूरा न कर सके।

4. Upload करें। POST /v1/uploads में size_bytes, duration_seconds (15 seconds से 10 घंटे), optional title, transcription_options, matter_code और 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 अधिकतम 64 characters का free text है और इसका मतलब सिर्फ़ workspace से जुड़े token के लिए है: यह उस workspace के ledger और usage reports में job के साथ दिखता है। जिस workspace की matter policy इसे required रखती है, वह इसके बिना आया upload org_matter_code_required के साथ अस्वीकार करता है। client_code स्वीकार किया जाता है लेकिन इस्तेमाल नहीं होता, क्योंकि client matter का attribute है जिसे workspace admin सेट करता है।

   इससे credit hold लगता है और job_id के साथ presigned part URLs का पहला page मिलता है:

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

   हर part को उसके URL पर PUT करें (default में 32 MiB के parts, आख़िरी part छोटा):

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

   अगले pages GET /v1/uploads/{job}/part-urls?start=<n> से लें। लंबे transfer में 20 मिनट का idle timeout आने से काफ़ी पहले POST /v1/uploads/{job}/heartbeat call करें। Presigned URLs उपलब्ध न हों या कोई part fail हो जाए, तो PUT /v1/uploads/{job}/parts/{n} उस part के bytes सीधे API से भेजता है; दोबारा PUT करने पर part replace होता है, इसलिए retry सुरक्षित है। समर्थित: mp3, m4a, mp4 या mov (audio track इस्तेमाल होता है, video tracks छोड़ दिए जाते हैं), wav, flac, ogg या opus, जिसकी server पर जांच होती है; किसी दूसरे video format से upload करने से पहले audio निकालें।

5. शुरू करें और इंतज़ार करें। POST /v1/uploads/{job}/complete में presigned URL पर भेजे हर part के n और etag दें (सभी parts API से भेजे हों तो parts छोड़ दें):

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

   फिर GET /v1/jobs/{id} poll करें: state, uploading, queued और processing से गुज़रकर done या failed होता है। पूरे हुए job में 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. नतीजा पढ़ें। GET /v1/transcripts/{id} metadata और पूरा body लौटाता है, जिसमें speaker names, detected भाषा, tags और auto-delete date होती है:

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

   GET /v1/transcripts list को pages में लौटाता है।

Transcription options हूबहू app वाली हैं: language_code या auto-detection, speaker_detection, medical_mode (इसके लिए language_code में en, es, fr या de चाहिए, +100% billing), translation_targets (हर भाषा के लिए +25%), multichannel, keyterms_prompt, free-text prompt, और saved dictionary_ids व prompt_preset_id, जिन्हें GET /v1/transcription-context list करता है।

Account के कुछ काम अभी सिर्फ़ MCP से होते हैं। Link से import, transcripts की editing या deletion, Insights, exports, dictionaries और prompt presets सहेजना, और account settings के लिए अभी /v1/ route नहीं है; MCP server उसी token से ये सब काम करता है।

Authentication

हर /v1/ call के Authorization header में bearer token होता है, जिसे MCP server वाले scopes के आधार पर जांचा जाता है:

Token के scopes से बाहर की call पर 403 के साथ pat_scope_missing मिलता है। billing scope भी तब तक काम नहीं करता जब तक token और account दोनों पर billing enabled न हो। इनमें से किसी भी switch के बंद होने पर billing call को वही pat_scope_missing मिलता है; नया token बनाने से account का switch चालू नहीं होता। Token दूसरे tokens बना, list या revoke नहीं कर सकता, और account में अधिकतम 25 active tokens हो सकते हैं।

Caller इन 11 scopes को चुन सकता है। pat:rotate अलग scope है जो agent account के पहले token और rotation से बने उसके अगले tokens को मिलता है; इससे token ख़ुद को replace कर सकता है, दूसरे tokens manage नहीं कर सकता। App में token बनाते समय आप इसे नहीं चुन सकते।

Endpoints

Production OpenAPI document में 37 paths पर 38 method/path operations हैं। नीचे हर operation के लिए दिखाया गया scope ज़रूरी है:

/v1/agent/accounts बिना token के headless signup खोलता है। /v1/agent/accounts/{signup_id}/claim paid signup को असली account और उसके पहले token में बदलता है। /v1/agent/credentials/rotate call करने वाले token की जगह नया token बनाकर, उसके पहली बार इस्तेमाल होते ही पुराने को retire कर देता है, account के किसी दूसरे credential को नहीं छूता। Agents के लिए automatic transcription में तीनों का पूरा flow है।

हर list में limit और opaque cursor दिया जाता है, और next_cursor लौटता है जो आख़िरी page पर null होता है। Cursor बिना बदले वापस भेजें; यह position encode करता है, इसलिए calls के बीच नई rows आने पर भी कोई page छूटता या दोहराया नहीं जाता।

हर operation के parameters और response schemas सहित पूरी वर्तमान definition OpenAPI document में है: इस table से ऊपर इसे source of truth मानें। यह किसी भी bearer token को scope की परवाह किए बिना मिलता है, इसलिए client अपने मौजूदा credentials से इसे ले सकता है।

MCP interface

Raw HTTP के बजाय tools पसंद हैं? MCP server वही account इन endpoints के बजाय 56 tools से उपलब्ध कराता है, उन clients के लिए जो REST के बजाय MCP इस्तेमाल करते हैं। यह सिर्फ़ वही tools advertise करता है जिन्हें connected token के scopes अनुमति देते हैं।

सीमाएं

Human account के token से प्रति token प्रति मिनट अधिकतम 1,200 requests की अनुमति है। Agent account के rotated tokens पूरे account में यही budget साझा करते हैं। Stripe call करने वाले billing routes पर PAT callers के लिए प्रति account प्रति मिनट 60 की सख़्त साझा सीमा है: setup session, purchase, default-card changes, card removal और card-list cache misses। सामान्य throttling पर 429 rate_limited और seconds में Retry-After मिलता है; retry से पहले उतना इंतज़ार करें। Agent account या human account के PAT से purchases के लिए प्रति account हर rolling 24 घंटे में 3 attempts की साझा सीमा है। Agent की signup purchase भी गिनी जाती है; reservation के बाद declines या errors भी गिने जाते हैं। Human browser-session purchase इससे बाहर है। Cap के कारण refusal पर HTTP 429 के साथ 4038 agent_purchase_capped और Retry-After मिलता है। Recordings 15 seconds से 10 घंटे तक हो सकती हैं। GET /v1/account account की वर्तमान admission limits (max_active_jobs, max_daily_seconds) बताता है।

Sandbox

कोई सामान्य transcription sandbox नहीं है: सामान्य /v1/ calls असली accounts पर चलती हैं और purchases में असली पैसे खर्च होते हैं। Signup validation इसका अपवाद है: POST /v1/agent/accounts, dry_run: true स्वीकार करता है, ऐसा dry_ signup id लौटाता है जिसे claim नहीं कर सकते, और कोई Stripe session या account नहीं खोलता।

Errors

Error एक JSON body है जिसमें स्थिर numeric code और error slug होता है, नीचे दिखाए HTTP status के साथ। /v1/ error bodies का projection तय है: error, code और detail keys का निश्चित सेट। /api का error shape तय नहीं है और उसमें अधिक जानकारी हो सकती है। Automated caller को ये codes संभालने होंगे:

OpenAPI document बताता है कि हर operation कौन-सा exact code लौटा सकता है, और MCP server पूरा catalog hushscript://error-codes resource के रूप में publish करता है।