---
url: /docs/asr_srt.zh.md
description: 语音转字幕接口。识别音频并直接返回 SRT 文件本体（Content-Disposition 下载），服务端不落盘。
---

# ASR\_SRT API 接口文档

## 🌐 语言切换

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

## 接口信息

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

::: warning 这是语音识别服务
本接口的基地址是 `https://autosubrt.jcaigc.cn`，与剪映小助手（`https://capcut-mate.jcaigc.cn`）不是同一个服务，路径前缀也不同。

```
完整请求地址 = https://autosubrt.jcaigc.cn + /openapi/autosubrt/v1/asr/srt
```

:::

## 功能描述

语音识别：把音频识别成 **SRT 字幕文件**，并把**文件本体**直接返回给调用方（`Content-Disposition: attachment`），服务端不落盘、不返回下载链接。

需要文案或时间线数据用 [语音转文案](/docs/asr.zh)；要按自己写的文本对齐时间线用 [文本对齐时间线](/docs/asr_text_align.zh)。

## 请求参数

```json
{
  "audio_url": "https://example.com/audio.mp3",
  "apiKey": "123e4567-e89b-12d3-a456-426614174000"
}
```

### 参数说明

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| audio\_url | string | ✅ | - | 音频文件 URL，需可被服务端直接下载，且必须是合法的 http/https 地址 |
| apiKey | string | 开启计费时必填 | - | 合法 UUID；可登录 https://jcaigc.cn 获取 |

### 参数详解

#### audio\_url

* **类型**: string
* **说明**: 服务端会先把这个 URL 下载到本地再识别，因此必须是**可直接访问的直链**（不能是需要登录的网页地址）
* **格式**: 常见音视频文件均可，如 wav、mp3、m4a、aac、flac、ogg，mp4、mov 等视频文件也能直接传（服务端自动抽取音轨）
* **限制**: 单文件最大 100MB（服务端 `FILE_SIZE_LIMIT` 默认 104857600 字节）

#### apiKey

* **类型**: string
* **说明**: 必须是合法 UUID；计费开启时（默认开启）必填，且账户积分需**大于 1**

## 响应格式

### 成功响应 (200)

成功时**不是 JSON**，响应体就是 SRT 文件内容：

```
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
请入席吧
```

### 响应头说明

| 响应头 | 值 | 说明 |
|--------|-----|------|
| Content-Type | `application/x-subrip; charset=utf-8` | 字幕文件；错误时是 `application/json` |
| Content-Disposition | `attachment; filename="subtitle.srt"` | 固定文件名 `subtitle.srt` |

### 错误响应

失败时返回 JSON 错误体（HTTP 仍是 200），**按 `Content-Type` 区分**是文件还是错误：

```json
{
  "code": 2003,
  "message": "下载文件失败"
}
```

| Content-Type | 含义 |
|--------------|------|
| `application/x-subrip; charset=utf-8` | SRT 字幕文件 |
| `application/json` | 错误，按 `code` 判断具体原因 |

## 使用示例

### cURL 示例

```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 示例

```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,
)

# 失败时返回的是 JSON 错误体，不是字幕文件
if resp.headers["Content-Type"].startswith("application/json"):
    raise RuntimeError(resp.json()["message"])

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

## 计费

本接口按**音频时长**扣费，与剪映小助手共用同一套积分体系。

| 项 | 说明 |
| --- | --- |
| 单价 | **0.00022 积分 / 秒** |
| 计费依据 | 音频实际时长（秒），由识别引擎给出 |
| 扣费时机 | 识别**成功之后**才扣费；识别失败不扣费 |
| 余额门槛 | 调用前账户积分需**大于 1**，否则直接拒绝（2035） |

| 音频时长 | 费用（积分） |
| --- | --- |
| 10 秒 | 0.002200 |
| 60 秒 | 0.013200 |
| 1 小时 | 0.792000 |

`apiKey` 必须是合法 UUID，可登录 <https://jcaigc.cn> 获取。

## 错误码说明

| 错误码 | 错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 1001 | 参数校验失败 | 缺少 audio\_url、audio\_url 不是合法 http/https 地址，或 apiKey 不是合法 UUID | 检查请求参数 |
| 2001 | 识别音频失败 | 音频无法解码、模型未加载，或 audio\_url 返回 401/403/404 | 换一个可正常播放的文件或可访问的直链 |
| 2002 | 文件大小超出限制 | 音频超过 100MB | 压缩或截取后再试 |
| 2003 | 下载文件失败 | 下载过程中网络或服务端错误，重试后仍失败 | 确认是公网可直链下载的地址 |
| 2005 | 下载文件超时 | 下载整体超时 | 换更快的源或更小的文件 |
| 2035 | 账户余额不足 | 账户积分需大于 1 才可继续使用服务 | 完成充值后重试 |
| 2036 | 无效的 apiKey | 计费开启时未传 apiKey | 登录 https://jcaigc.cn 获取 apiKey |
| 9997 | 服务器忙 | 并发已达上限，请求未排队 | 稍后重试 |
| 9998 | 系统内部错误 | 未预期的内部异常 | 联系技术支持 |
| 9999 | 未知异常 | 积分服务不可用等 | 稍后重试 |

## 注意事项

1. **响应体是文件本身**，不是 `{code, message, data}`：「文件下载链接」这种返回形式已废弃，消费方需按 `Content-Type` 分流。
2. **文件编码为 UTF-8，行尾为 `\n`**，序号从 1 开始，时间戳格式为 `时:分:秒,毫秒`。
3. **断句依据是静音**：相邻两字间隔超过 250 毫秒就断开一条字幕，整段无法分割时合成一条。
4. **SRT 文本不经标点模型**：内容直接来自识别结果，通常不带标点（与 [语音转文案](/docs/asr.zh) 的 `text` 不同）。
5. **完全没识别到语音**时会返回一条 0 秒 → 30 秒的空字幕，调用方可按「字幕内容为空」判断。
6. **服务端不落盘**：临时音频在请求结束时删除，不产生需要自行清理的静态文件。
7. **重复调用会重复扣费**，超时后请勿盲目重试。

## 工作流程

1. 校验 apiKey 与账户余额（计费开启时）
2. 下载 `audio_url` 指向的音视频到服务端临时目录
3. 语音识别，得到逐字时间线
4. 按静音间隔把字序列切成字幕条目
5. 识别成功后按音频时长扣费
6. 以 UTF-8 文本直接返回 SRT 文件本体，删除临时文件

## 相关接口

* [语音转文案](/docs/asr.zh)
* [语音转文本](/docs/asr_text.zh)
* [文本对齐时间线](/docs/asr_text_align.zh)

***

📚 **项目资源**\
**GitHub**: <https://github.com/Hommy-master/autosubrt>