Fun-ASR recording Java SDK

使用指南：教程、代码示例和模型详情请参见录音文件转写。

使用限制

输入格式：仅支持公开可访问的文件 URL（HTTP/HTTPS），不支持本地文件和 Base64 编码音频。示例：https://your-domain.com/file.mp3 通过 fileUrls 参数设置文件 URL，每次请求最多 100 个 URL。

音频格式：aac、amr、avi、flac、flv、m4a、mkv、mov、mp3、mp4、mpeg、ogg、opus、wav、webm、wma、wmv

音视频格式变体众多，API 无法保证所有变体都能正确识别。请先测试您的文件，确认识别效果。

音频采样率：不限
文件大小和时长：最大 2 GB、12 小时。如果启用说话人分离功能，建议音频时长不超过 2 小时。更大文件请参见预处理最佳实践。
批量大小：每次请求最多 100 个文件 URL。
支持语言： fun-asr 和 fun-asr-mtl（含所有版本）均支持中文、英语、日语、韩语等 30 种语言，详见支持的语言。fun-asr-2025-08-25 仅支持中文和英文。

请求参数

通过 TranscriptionParam 构建器方法设置请求参数。

点击查看示例

TranscriptionParam param = TranscriptionParam.builder()
  .model("fun-asr")
  .fileUrls(
          Arrays.asList(
                  "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
                  "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav"))
  .build();

参数	类型	默认值	是否必填	描述
model	String	-	是	转写模型。参见支持的模型。
fileUrls	List<String>	-	是	待转写的音视频文件 URL 列表，支持 HTTP 和 HTTPS，每次请求最多 100 个 URL。
vocabularyId	String	-	否	热词词表 ID，启用后在识别时应用该词表中的热词。默认不启用。参见自定义热词。
channelId	List<Integer>	[0]	否	需要识别的音频声道索引（从 0 开始）。[0] 仅识别第一个声道；[0, 1] 识别两个声道。每个声道单独计费。
specialWordFilter	String	-	否	识别过程中需要过滤的敏感词。详见敏感词过滤说明。
diarizationEnabled	Boolean	false	否	是否启用说话人分离（仅支持单声道音频）。启用后结果中包含 `speaker_id` 字段以区分说话人。参见识别结果。如果启用说话人分离功能，建议音频时长不超过 2 小时，否则可能导致识别失败或超时。
speakerCount	Integer	-	否	预期的说话人数量（2-100）。仅在 `diarizationEnabled` 为 true 时生效。该值用于指导算法，不保证输出的说话人数量完全一致。
language_hints	String[]	-	否	语言代码。不设置则自动检测。参见支持的语言。
apiKey	String	-	否	API Key。如已设置环境变量则无需传入。

敏感词过滤说明

未设置 specialWordFilter 时，系统默认启用内置过滤（匹配千问云敏感词列表（文件名为历史遗留）中的词将被替换为 *）。设置后，可使用以下过滤策略：

替换为 *：将匹配的词替换为等长的星号。
直接过滤：从结果中删除匹配的词。

值为 JSON 字符串：

{
  "filter_with_signed": {
    "word_list": ["test"]
  },
  "filter_with_empty": {
    "word_list": ["start", "happen"]
  },
  "system_reserved_filter": true
}

字段说明：

filter_with_signed
- 类型：object（可选）
- 将匹配的词替换为等长的 *。
- 示例："Help me test this piece of code" -> "Help me **** this piece of code"
- 字段：word_list（需要替换的词数组）
filter_with_empty
- 类型：object（可选）
- 从结果中删除匹配的词。
- 示例："Is the game about to start?" -> "Is the game about to?"（过滤后结果可能形成语义不完整的句子）
- 字段：word_list（需要删除的词数组）
system_reserved_filter
- 类型：boolean（默认值：true）
- 启用系统预设的敏感词规则。为 true 时启用内置过滤（匹配千问云敏感词列表（文件名为历史遗留）中的词将被替换为 *）。

支持的语言

各模型支持的语言代码：

fun-asr、fun-asr-2025-11-07：
- zh：中文
- en：英语
- ja：日语
- ko：韩语
- vi：越南语
- th：泰语
- id：印尼语
- ms：马来语
- tl：菲律宾语
- hi：印地语
- ar：阿拉伯语
- fr：法语
- de：德语
- es：西班牙语
- pt：葡萄牙语
- ru：俄语
- it：意大利语
- nl：荷兰语
- sv：瑞典语
- da：丹麦语
- fi：芬兰语
- no：挪威语
- el：希腊语
- pl：波兰语
- cs：捷克语
- hu：匈牙利语
- ro：罗马尼亚语
- bg：保加利亚语
- hr：克罗地亚语
- sk：斯洛伐克语
fun-asr-2025-08-25：
- zh：中文
- en：英文
fun-asr-mtl、fun-asr-mtl-2025-08-25：
- zh：中文
- en：英语
- ja：日语
- ko：韩语
- vi：越南语
- th：泰语
- id：印尼语
- ms：马来语
- tl：菲律宾语
- hi：印地语
- ar：阿拉伯语
- fr：法语
- de：德语
- es：西班牙语
- pt：葡萄牙语
- ru：俄语
- it：意大利语
- nl：荷兰语
- sv：瑞典语
- da：丹麦语
- fi：芬兰语
- no：挪威语
- el：希腊语
- pl：波兰语
- cs：捷克语
- hu：匈牙利语
- ro：罗马尼亚语
- bg：保加利亚语
- hr：克罗地亚语
- sk：斯洛伐克语

通过 TranscriptionParam 的 parameter 或 parameters 方法设置 language_hints：

使用 parameter 设置
使用 parameters 设置

TranscriptionParam param = TranscriptionParam.builder()
  .model("fun-asr")
  .parameter("language_hints", new String[]{"zh", "en"})
  .build();

响应

任务结果（`TranscriptionResult`）

TranscriptionResult 包含任务结果。

方法	参数	返回值	描述
`public String getRequestId()`	无	requestId	获取请求 ID。
`public String getTaskId()`	无	taskId	获取任务 ID。
`public TaskStatus getTaskStatus()`	无	`TaskStatus`	获取任务状态（`PENDING`、`RUNNING`、`SUCCEEDED` 或 `FAILED`）。包含多个子任务时，只要有一个子任务成功，整体状态即为 `SUCCEEDED`。请通过 `subtask_status` 查看每个子任务的状态。
`public List<TranscriptionTaskResult> getResults()`	无	TranscriptionTaskResult	获取子任务结果列表。每个文件对应一个子任务。
`public JsonObject getOutput()`	无	JSON	以 JSON 格式获取结果。参见 JSON 输出示例。

JSON 输出示例

成功示例

transcription_url 的路径格式仅供参考，实际路径随模型和时间不同而异。

{
  "task_id":"0795ff8c-b666-4e91-bb8b-xxx",
  "task_status":"SUCCEEDED",
  "submit_time":"2025-02-13 16:12:09.109",
  "scheduled_time":"2025-02-13 16:12:09.128",
  "end_time":"2025-02-13 16:12:10.189",
  "results":[
    {
      "file_url":"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav",
      "transcription_url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/fun-asr/20250213/16%3A12/34604a7b-579a-4223-8797-5116a49b07ec-1.json?Expires=1739520730&OSSAccessKeyId=yourOSSAccessKeyId&Signature=tMqyH56oB5rDW9%2FFqD8Yo%2F3WaPk%3D",
      "subtask_status":"SUCCEEDED"
    },
    {
      "file_url":"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
      "transcription_url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/fun-asr/20250213/16%3A12/3baafe5f-d09d-46c6-8b01-724927670edb-1.json?Expires=1739520730&OSSAccessKeyId=yourOSSAccessKeyId&Signature=BF7vPxlsJN9hkJlY%2BLReezxOwK8%3D",
      "subtask_status":"SUCCEEDED"
    }
  ],
  "task_metrics":{
    "TOTAL":2,
    "SUCCEEDED":2,
    "FAILED":0
  }
}

错误示例 code 和 message 字段仅在出错时出现。

{
  "task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
  "task_status": "SUCCEEDED",
  "submit_time": "2024-12-16 16:30:59.170",
  "scheduled_time": "2024-12-16 16:30:59.204",
  "end_time": "2024-12-16 16:31:02.375",
  "results": [
    {
      "file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/long_audio_demo_cn.mp3",
      "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/fun-asr/20241216/xxxx",
      "subtask_status": "SUCCEEDED"
    },
    {
      "file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/rich_text_exaple_1.wav",
      "code": "InvalidFile.DownloadFailed",
      "message": "The audio file cannot be downloaded.",
      "subtask_status": "FAILED"
    }
  ],
  "task_metrics": {
    "TOTAL": 2,
    "SUCCEEDED": 1,
    "FAILED": 1
  }
}

子任务结果（`TranscriptionTaskResult`）

TranscriptionTaskResult 包含单个文件的转写结果。

方法	参数	返回值	描述
`public String getFileUrl()`	无	文件 URL	获取已识别文件的 URL。
`public String getTranscriptionUrl()`	无	结果 URL	获取转写结果 URL（有效期 24 小时）。结果为 JSON 文件，可通过 HTTP 下载或读取。参见识别结果。
`public TaskStatus getSubTaskStatus()`	无	`TaskStatus`	获取子任务状态（`PENDING`、`RUNNING`、`SUCCEEDED` 或 `FAILED`）。
`public String getMessage()`	无	消息（可能为空）	获取错误详情。任务失败时请检查此字段。

识别结果

识别结果为 JSON 文件。

点击查看识别结果示例

以下为启用说话人分离（diarizationEnabled=true）时的示例，结果中包含 speaker_id 字段。

{
  "file_url":"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
  "properties":{
    "audio_format":"pcm_s16le",
    "channels":[
      0
    ],
    "original_sampling_rate":16000,
    "original_duration_in_milliseconds":3834
  },
  "transcripts":[
    {
      "channel_id":0,
      "content_duration_in_milliseconds":3720,
      "text":"Hello world, this is Alibaba Speech Lab.",
      "sentences":[
        {
          "begin_time":100,
          "end_time":3820,
          "text":"Hello world, this is Alibaba Speech Lab.",
          "sentence_id":1,
          "speaker_id":0,
          "words":[
            {
              "begin_time":100,
              "end_time":596,
              "text":"Hello ",
              "punctuation":""
            },
            {
              "begin_time":596,
              "end_time":844,
              "text":"world",
              "punctuation":", "
            }
          ]
        }
      ]
    }
  ]
}

主要字段：

参数	类型	描述
audio_format	string	源文件的音频格式。
channels	array[integer]	音频声道索引。单声道返回 [0]，双声道返回 [0, 1]，依此类推。
original_sampling_rate	integer	采样率（Hz）。
original_duration_in_milliseconds	integer	原始音频时长（毫秒）。
channel_id	integer	已转写的音频声道索引（从 0 开始）。
content_duration_in_milliseconds	integer	语音内容时长（毫秒）。计费以语音时长为准，非语音内容不计费。AI 判定的语音时长可能与音频总时长不同。
text	string	转写文本（段落级、句子级或词级，取决于所在层级）。
sentences	array	句子级转写结果。
words	array	词级转写结果。
begin_time	integer	开始时间戳（毫秒）。
end_time	integer	结束时间戳（毫秒）。
sentence_id	integer	句子序号（从 1 开始）。
speaker_id	integer	说话人索引（从 0 开始）。仅在启用说话人分离时出现。
punctuation	string	该词后预测的标点符号（如有）。

核心接口

查询参数类（`TranscriptionQueryParam`）

在 Transcription 实例上调用 wait 或 fetch 方法时，需要传入 TranscriptionQueryParam。通过静态方法 FromTranscriptionParam 创建。

点击查看示例

// 创建转写请求参数
TranscriptionParam param = TranscriptionParam.builder()
  // 如果未将 API Key 设置为环境变量，请将 apiKey 替换为您自己的 API Key
  //.apiKey("apikey")
  .model("fun-asr")
  .fileUrls(
      Arrays.asList(
          "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
          "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav"))
  .build();
try {
  Transcription transcription = new Transcription();
  // 提交转写请求
  TranscriptionResult result = transcription.asyncCall(param);
  System.out.println("RequestId: " + result.getRequestId());
  TranscriptionQueryParam queryParam = TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId());

} catch (Exception e) {
  System.out.println("error: " + e);
}

方法	参数	返回值	描述
`public static TranscriptionQueryParam FromTranscriptionParam(TranscriptionParam param, String taskId)`	`param`：`TranscriptionParam` 实例，`taskId`：任务 ID	`TranscriptionQueryParam` 实例	创建 `TranscriptionQueryParam` 实例。

核心类（`Transcription`）

通过 import com.alibaba.dashscope.audio.asr.transcription.*; 导入。主要方法：

方法	参数	返回值	描述
`public TranscriptionResult asyncCall(TranscriptionParam param)`	`param`：`TranscriptionParam` 实例	TranscriptionResult	异步提交转写任务。
`public TranscriptionResult wait(TranscriptionQueryParam queryParam)`	`queryParam`：`TranscriptionQueryParam` 实例	TranscriptionResult	阻塞等待，直到任务状态变为 `SUCCEEDED` 或 `FAILED`。
`public TranscriptionResult fetch(TranscriptionQueryParam queryParam)`	`queryParam`：`TranscriptionQueryParam` 实例	TranscriptionResult	查询当前任务结果。

​使用限制

​请求参数

​敏感词过滤说明

​支持的语言

​响应

​任务结果（TranscriptionResult）

​JSON 输出示例

​子任务结果（TranscriptionTaskResult）

​识别结果

​核心接口

​查询参数类（TranscriptionQueryParam）

​核心类（Transcription）

使用限制

请求参数

敏感词过滤说明

支持的语言

响应

任务结果（`TranscriptionResult`）

JSON 输出示例

子任务结果（`TranscriptionTaskResult`）

识别结果

核心接口

查询参数类（`TranscriptionQueryParam`）

核心类（`Transcription`）