---
url: /docs/asr_srt.md
description: >-
  Speech-to-subtitle API. Transcribe audio and return the SRT file body itself
  (Content-Disposition attachment); nothing is stored server-side.
---

# ASR\_SRT API Documentation

## 🌐 Language Switch

[中文版](/docs/asr_srt.zh) | [English](/docs/asr_srt)

## Interface Information

```
POST /openapi/autosubrt/v1/asr/srt
```

::: 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/srt
```

:::

## Function Description

Speech recognition: transcribe audio into an **SRT subtitle file** and return the **file body itself** to the caller (`Content-Disposition: attachment`). Nothing is written to disk server-side and no download link is returned.

For the copy or timeline data use [ASR](/docs/asr); to align your own text against the audio use [Align Text To Audio](/docs/asr_text_align).

## 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 and a valid http/https URL |
| 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)

On success the response is **not JSON** — the body is the SRT file content:

```
HTTP/1.1 200 OK
Content-Type: application/x-subrip; charset=utf-8
Content-Disposition: attachment; filename="subtitle.srt"

1
00:00:02,810 --> 00:00:03,330
多谢

2
00:00:04,889 --> 00:00:06,009
请入席吧
```

### Response Header Description

| Header | Value | Description |
|--------|-------|-------------|
| Content-Type | `application/x-subrip; charset=utf-8` | Subtitle file; `application/json` on failure |
| Content-Disposition | `attachment; filename="subtitle.srt"` | Fixed file name `subtitle.srt` |

### Error Response

On failure a JSON error body is returned (still with HTTP 200). Tell the two apart **by `Content-Type`**:

```json
{
  "code": 2003,
  "message": "Download file failed"
}
```

| Content-Type | Meaning |
|--------------|---------|
| `application/x-subrip; charset=utf-8` | An SRT subtitle file |
| `application/json` | An error; read `code` for the reason |

## Usage Examples

### cURL Examples

```bash
curl -X POST https://autosubrt.jcaigc.cn/openapi/autosubrt/v1/asr/srt \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/audio.mp3",
    "apiKey": "123e4567-e89b-12d3-a456-426614174000"
  }' \
  -o subtitle.srt
```

### Python Example

```python
import requests

resp = requests.post(
    "https://autosubrt.jcaigc.cn/openapi/autosubrt/v1/asr/srt",
    json={
        "audio_url": "https://example.com/audio.mp3",
        "apiKey": "123e4567-e89b-12d3-a456-426614174000",
    },
    timeout=600,
)

# A failure returns a JSON error body, not a subtitle file
if resp.headers["Content-Type"].startswith("application/json"):
    raise RuntimeError(resp.json()["message"])

with open("subtitle.srt", "wb") as f:
    f.write(resp.content)
```

## 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 <https://jcaigc.cn>.

## Error Code Description

| Error Code | Error Message | Description | Solution |
|------------|---------------|-------------|----------|
| 1001 | Parameter validation failed | audio\_url missing or not a valid http/https URL, 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. **The body is the file itself**, not `{code, message, data}`: the old `data.srt_url` download-link form is gone, so callers must branch on `Content-Type`.
2. **The file is UTF-8 with `\n` line endings**, indices start at 1, and timestamps use `HH:MM:SS,mmm`.
3. **Cues are split on silence**: a gap of more than 250 milliseconds between two characters starts a new cue; if the whole audio cannot be split it becomes a single cue.
4. **SRT text does not pass through the punctuation model**: it comes straight from the recognition result and usually carries no punctuation (unlike `text` from [ASR](/docs/asr)).
5. **When no speech is recognized at all**, one empty cue from 0s to 30s is returned; treat an empty cue text as "no speech".
6. **Nothing is stored server-side**: the temp audio is deleted when the request finishes, so there are no static files to clean up.
7. **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. Split the character sequence into cues on silence gaps
5. Charge by audio duration after a successful recognition
6. Return the SRT file body as UTF-8 text, then delete the temp file

## Related Interfaces

* [ASR](/docs/asr)
* [ASR Text](/docs/asr_text)
* [Align Text To Audio](/docs/asr_text_align)

***

📚 **Project Resources**\
**GitHub**: <https://github.com/Hommy-master/autosubrt>