--- url: /docs/asr.md description: >- Speech-to-copy API. Transcribe audio into punctuated full text, sentence-split utterances, and per-character timelines (milliseconds). --- # ASR API Documentation ## 🌐 Language Switch [中文版](/docs/asr.zh) | [English](/docs/asr) ## Interface Information ``` POST /openapi/autosubrt/v1/asr ``` ::: warning This is the speech recognition service The base URL of this interface is `https://autosubrt.jcaigc.cn`, which is a different service (and a different path prefix) from CapCut Mate (`https://capcut-mate.jcaigc.cn`). ``` Full URL = https://autosubrt.jcaigc.cn + /openapi/autosubrt/v1/asr ``` ::: ## Function Description Speech recognition: transcribe audio into **punctuated full text**, split it into sentences by sentence-ending punctuation, and return a timeline for every character of each sentence. Use it when you have audio and want copy or subtitles directly. For plain text only use [ASR Text](/docs/asr_text); for an SRT subtitle file use [ASR SRT](/docs/asr_srt); to align your own text against the audio use [Align Text To Audio](/docs/asr_text_align). Punctuation is restored by a dedicated punctuation model (Whisper is unreliable on Chinese punctuation), so `text` **always carries punctuation** — the split sentences do too. ## Request Parameters ```json { "audio_url": "https://example.com/audio.mp3", "apiKey": "123e4567-e89b-12d3-a456-426614174000" } ``` ### Parameter Description | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | audio\_url | string | ✅ | - | Audio file URL, must be downloadable by the server | | apiKey | string | Required when billing is on | - | A valid UUID; get one at https://jcaigc.cn | ### Parameter Details #### audio\_url * **Type**: string * **Description**: The server downloads this URL before transcribing, so it must be a **direct, publicly reachable link** (not a page that requires login) * **Format**: Any common audio or video file: wav, mp3, m4a, aac, flac, ogg; video files such as mp4 and mov also work (the audio track is extracted server-side) * **Limit**: 100MB per file (server-side `FILE_SIZE_LIMIT`, 104857600 bytes by default) #### apiKey * **Type**: string * **Description**: Must be a valid UUID; required while billing is enabled (it is by default), and the account balance must be **greater than 1** ## Response Format ### Success Response (200) ```json { "code": 0, "message": "Success", "data": { "text": "多谢，请入席吧。", "utterances": [ { "text": "多谢，请入席吧。", "words": [ { "text": "多", "start_time": 2810, "end_time": 3070 }, { "text": "谢", "start_time": 3070, "end_time": 3330 }, { "text": "请", "start_time": 4889, "end_time": 5320 }, { "text": "入", "start_time": 5320, "end_time": 5620 }, { "text": "席", "start_time": 5620, "end_time": 5860 }, { "text": "吧", "start_time": 5860, "end_time": 6009 } ] } ] } } ``` ### Response Field Description | Field | Type | Description | |-------|------|-------------| | code | int | 0 means success; see the error codes below otherwise | | message | string | Human-readable message, Chinese by default, English when `Accept-Language: en` is sent | | data.text | string | Full copy, **always punctuated** | | data.utterances | array | Sentence-split result, each item ends with sentence-ending punctuation | | data.utterances\[].text | string | Text of one sentence, punctuation included | | data.utterances\[].words | array | Per-character timeline of that sentence, **punctuation excluded** | | data.utterances\[].words\[].text | string | A single character (Latin text is split into letters) | | data.utterances\[].words\[].start\_time | int | Start time (**milliseconds**) | | data.utterances\[].words\[].end\_time | int | End time (**milliseconds**) | ### Error Response ```json { "code": 2003, "message": "Download file failed" } ``` Error bodies contain **no** `data` field; every error is returned with HTTP 200, so check `code` instead of the status code. ## Usage Examples ### cURL Examples ```bash curl -X POST https://autosubrt.jcaigc.cn/openapi/autosubrt/v1/asr \ -H "Content-Type: application/json" \ -d '{ "audio_url": "https://example.com/audio.mp3", "apiKey": "123e4567-e89b-12d3-a456-426614174000" }' ``` ### Python Example ```python import requests resp = requests.post( "https://autosubrt.jcaigc.cn/openapi/autosubrt/v1/asr", json={ "audio_url": "https://example.com/audio.mp3", "apiKey": "123e4567-e89b-12d3-a456-426614174000", }, timeout=600, ) result = resp.json() if result["code"] != 0: raise RuntimeError(result["message"]) for sentence in result["data"]["utterances"]: print(sentence["text"]) for word in sentence["words"]: print(word["text"], word["start_time"], word["end_time"]) # milliseconds ``` ## Billing This interface is charged by **audio duration** and shares the same points system as CapCut Mate. | Item | Description | | --- | --- | | Price | **0.00022 points / second** | | Basis | Actual audio duration in seconds, as reported by the recognition engine | | When charged | Only after a **successful** recognition; failures are not charged | | Balance gate | The account must hold **more than 1** point before the call, otherwise it is rejected (2035) | | Audio duration | Cost (points) | | --- | --- | | 10 seconds | 0.002200 | | 60 seconds | 0.013200 | | 1 hour | 0.792000 | `apiKey` must be a valid UUID and can be obtained at . ## Error Code Description | Error Code | Error Message | Description | Solution | |------------|---------------|-------------|----------| | 1001 | Parameter validation failed | audio\_url missing, or apiKey is not a valid UUID | Check the request parameters | | 2001 | Failed to recognize audio | Audio could not be decoded, model not loaded, or audio\_url returned 401/403/404 | Try a playable file or a reachable direct link | | 2002 | File size exceeds the limit | Audio is larger than 100MB | Compress or trim it and retry | | 2003 | Download file failed | Network or server error during download, still failing after retries | Make sure it is a public direct download link | | 2005 | Download file timeout | Overall download timed out | Use a faster source or a smaller file | | 2035 | Insufficient account balance | The account needs more than 1 point to keep using the service | Recharge and retry | | 2036 | Invalid apiKey | apiKey missing while billing is enabled | Get an apiKey at https://jcaigc.cn | | 9997 | Server is busy | Concurrency limit reached; the request was not queued | Retry later | | 9998 | Internal server error | Unexpected internal error | Contact technical support | | 9999 | Unknown error | Points service unavailable, etc. | Retry later | ## Notes 1. **Time unit is milliseconds** (1 second = 1000). Note that [Align Text To Audio](/docs/asr_text_align) returns **microseconds** instead. 2. **Sentences are split by sentence-ending punctuation only**: a sentence ends on `。！？.!?`; commas, enumeration commas and colons stay inside the sentence. 3. **Concatenating all sentences reproduces `data.text` character by character**: `"".join(u.text) == data.text`. 4. **Punctuation has no timestamp**: `words` only contains real characters; punctuation appears in `text` only. 5. **When no speech is recognized**, `data.text` is an empty string and `data.utterances` is an empty array — the call still succeeds. 6. **Repeated calls are charged repeatedly**; do not blindly retry after a timeout. ## Workflow 1. Validate apiKey and account balance (while billing is enabled) 2. Download the audio/video behind `audio_url` into a server-side temp directory 3. Run speech recognition to obtain per-character timelines 4. Restore punctuation with the punctuation model to get the punctuated full text 5. Split by sentence-ending punctuation; punctuation stays with its sentence 6. Charge by audio duration after a successful recognition 7. Return the copy and sentence timelines, then delete the temp file ## Related Interfaces * [ASR Text](/docs/asr_text) * [ASR SRT](/docs/asr_srt) * [Align Text To Audio](/docs/asr_text_align) *** 📚 **Project Resources**\ **GitHub**: