ASR_TEXT_ALIGN API 接口文档

🌐 语言切换

中文版 | English

接口信息

POST /openapi/autosubrt/v1/asr/text/align

这是语音识别服务

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

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

功能描述

把你提供的文本按音频的时间轴对齐：服务端先识别音频，再把文本切成一行行字幕，给出每行的起止时间，同时返回音频里每个字的时间线。

适合「文案已经写好，只需要卡时间」的场景（如已有人工校对过的台词稿）。识别结果本身就是你要的文案时，用 语音转文案 更省事。

时间单位是微秒

本接口返回的时间线单位是微秒（1 秒 = 1000000），而 语音转文案 返回的是毫秒，两者相差 1000 倍。

请求参数

{
  "audio_url": "https://example.com/audio.mp3",
  "text": "多谢，请入席吧。",
  "max_chars_per_line": 15,
  "apiKey": "123e4567-e89b-12d3-a456-426614174000"
}

参数说明

参数名	类型	必填	默认值	说明
audio_url	string	✅	-	音频文件 URL，需可被服务端直接下载
text	string	✅	-	与该音频对应的字幕文本
max_chars_per_line	int	❌	15	每行最大字数，超过则拆成多条字幕
apiKey	string	开启计费时必填	-	合法 UUID；可登录 https://jcaigc.cn 获取

参数详解

audio_url

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

text

• 类型: string
• 说明: 需要对齐的字幕文本，行内容应与音频实际说的一致
• 切分规则: 先按标点切句（。！？，；.!?,;: 与换行都会切开），切分后标点被去掉；超过 max_chars_per_line 的句子会再平均拆成多行

max_chars_per_line

• 类型: int
• 说明: 每行最大字数，默认 15。拆分是「平均分」而不是「按标点分」：30 字分成 2 行各 15 字；31 字分成 3 行（11、10、10）；46 字分成 4 行（12、12、11、11）

apiKey

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

响应格式

成功响应 (200)

{
  "code": 0,
  "message": "成功",
  "data": {
    "texts": ["多谢", "请入席吧"],
    "timelines": [
      { "start": 2810000, "end": 3330000 },
      { "start": 4889000, "end": 6009000 }
    ],
    "words": ["多", "谢", "请", "入", "席", "吧"],
    "words_timelines": [
      { "start": 2810000, "end": 3070000 },
      { "start": 3070000, "end": 3330000 },
      { "start": 4889000, "end": 5320000 },
      { "start": 5320000, "end": 5620000 },
      { "start": 5620000, "end": 5860000 },
      { "start": 5860000, "end": 6009000 }
    ]
  }
}

响应字段说明

字段名	类型	说明
code	int	0 表示成功，非 0 见下方错误码说明
message	string	提示信息，默认中文，带 Accept-Language: en 时返回英文
data.texts	array	对齐后的字幕文本列表，每行一条，不含标点
data.timelines	array	与 texts 一一对应的行级时间线，单位微秒
data.timelines[].start	int	开始时间（微秒）
data.timelines[].end	int	结束时间（微秒）
data.words	array	音频识别出的字，按顺序排列（不是用户文本切出来的字）
data.words_timelines	array	与 words 一一对应的字级时间线，单位微秒

错误响应

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

错误体不包含 data 字段；所有错误都返回 HTTP 200，需按 code 判断成功与否。

使用示例

cURL 示例

curl -X POST https://autosubrt.jcaigc.cn/openapi/autosubrt/v1/asr/text/align \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/audio.mp3",
    "text": "多谢，请入席吧。",
    "max_chars_per_line": 15,
    "apiKey": "123e4567-e89b-12d3-a456-426614174000"
  }'

Python 示例

import requests

resp = requests.post(
    "https://autosubrt.jcaigc.cn/openapi/autosubrt/v1/asr/text/align",
    json={
        "audio_url": "https://example.com/audio.mp3",
        "text": "多谢，请入席吧。",
        "max_chars_per_line": 15,
        "apiKey": "123e4567-e89b-12d3-a456-426614174000",
    },
    timeout=600,
)

result = resp.json()
if result["code"] != 0:
    raise RuntimeError(result["message"])

for line, timeline in zip(result["data"]["texts"], result["data"]["timelines"]):
    # 时间线单位是微秒，可直接用于剪映小助手 add_captions 的 start / end
    print(f"{timeline['start'] / 1e6:.2f}s - {timeline['end'] / 1e6:.2f}s  {line}")

计费

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

项	说明
单价	0.00022 积分 / 秒
计费依据	音频实际时长（秒），由识别引擎给出
扣费时机	音频下载并识别完成之后才扣费；没有识别到语音也会按实际时长扣费
余额门槛	调用前账户积分需大于 1，否则直接拒绝（2035）

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

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

错误码说明

错误码	错误信息	说明	解决方案
1001	参数校验失败	缺少 audio_url 或 text，或 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. 时间单位是微秒（1 秒 = 1000000），与 语音转文案、语音转 SRT 字幕 的毫秒不同。返回的时间线可直接用于剪映小助手 add_captions 的 start / end。
2. texts 不含标点：切句时标点被去掉，需要带标点的文案请用 语音转文案。
3. words 是音频识别出的字，不是 text 切出来的字；它与 words_timelines 一一对应，可用来自行校准或做逐字高亮。
4. 文本与音频不一致时仍会返回结果：对齐用的是编辑距离，文本比音频多出或少掉的字会被跳过或按比例摊到相邻区间，时间线只能保证大致贴合。
5. 没有识别到语音时返回 texts = [原始文本]、timelines = [{start: 0, end: 30000000}]（30 秒占位）、words 与 words_timelines 为空数组，调用方需自行判断这种兜底结果。
6. 重复调用会重复扣费，超时后请勿盲目重试。

工作流程

1. 校验 apiKey 与账户余额（计费开启时）
2. 下载 audio_url 指向的音视频到服务端临时目录
3. 语音识别，得到逐字时间线
4. 按标点切句、按 max_chars_per_line 拆行，用编辑距离把文本字与识别字对齐
5. 计算行级时间线，并用字级时间线做全局校准
6. 识别完成后按音频时长扣费
7. 返回文本、行级时间线与字级时间线，删除临时文件

相关接口

• 语音转文案
• 语音转文本
• 语音转 SRT 字幕

---

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