开发者中心 - 小鱼易连

接口清单

接口序号	接口类型	接口功能	URL	备注
1	HTTP POST	分配转写资源	`/api/rest/external/v1/transcription/task/allocate`	需签名鉴权，返回用于后续操作的具体地址。
2	HTTP POST	创建离线转写任务	接口1返回的 `offlineAsrTaskUrl/api/rest/aigw/platform/offline/asr/task/create/v1`	需通过 `multipart/form-data` 上传音频文件或提供下载地址。
3	HTTP GET	查询离线转写状态	接口1返回的 `queryProgressUrl/api/rest/aigw/platform/offline/asr/progress/query/v1`	可轮询调用，获取任务进度或最终结果。
4	HTTP POST	转写完成通知接口；该接口需要资源使用方实现	由用户在接口1的`callback`参数中指定	平台在任务完成后主动回调此地址。若不提供`callback`，则只能通过接口3获取结果。

术语表

术语	说明
`sessionId`	任务唯一标识符。由接口1分配，在后续所有与AI服务的交互中，都需通过URL参数携带，用于关联任务。有效期24小时。
`offlineAsrTaskUrl`	创建离线转写任务的动态地址。由接口1返回，用于调用接口2。有效期24小时。
`queryProgressUrl`	查询离线转写进度的动态地址。由接口1返回，用于调用接口3。有效期24小时。
`callback`	回调通知地址。用户在接口1中提供的URL，平台在任务完成后将向此地址发送POST请求（接口4格式）通知结果。
`aiResult`	转写结果的JSON格式数据。包含转写文本、时间戳、角色分离、翻译等信息。在接口3（任务完成时）和接口4（成功时）的响应体中返回，格式见2.5。

1、交互流程

sequenceDiagram
    participant Client
    participant 云平台
    participant AI_Service

    Note over Client,AI_Service: 鉴权资源分配
    Client->>云平台: POST /接口1,分配转写资源(callbackUrl)
    云平台-->>AI_Service: {分配offlineAsrTaskUrl, queryProgressUrl}
    云平台-->>Client: {offlineAsrTaskUrl, queryProgressUrl}

    Note over Client,AI_Service: 上传/下载音频，开启转写任务
    Client->>AI_Service: POST /接口2,offlineAsrTaskUrl (multipart上传音频流或提供音频下载地址)
    AI_Service-->>Client: 接收确认

    Note over AI_Service,Client: 方式一：转写状态查询
    loop 
        Client->>AI_Service: GET /接口3,查询状态
        AI_Service-->>Client: {status, progress, aiResult}
    end

    Note over AI_Service,Client: 方式二：转写回调通知
    AI_Service-->>Client: POST /接口4，通知转写完成(status, aiResult)

Client先请求小鱼云平台，进行鉴权认证及动态分配转写资源，云平台返回开启转写的地址和转写进度查询地址。开启转写地址和查询地址在24小时内有效。地址过期有对应的错误码提示，需要重新请求资源分配接口重新分配。

2、接口细节

安全性：资源分配接口（接口1）需要进行接口签名认证。签名规则参照签名规则。资源分配之后的任务接口（接口2、3）使用sessionId进行认证。
音频格式：支持 wav、aac。
音频大小：文件大小限制为500MB以内。
有效期：sessionId及所有动态分配的URL有效期均为24小时。
调用限制：

分配AI资源接口（接口1），每次生成不同的sessionId，转写任务通过sessionId关联。
开启转写任务接口（接口2），24小时内有效。上传失败可以重新上传，上传成功后接口失效，不允许再传其他文件。提供下载地址后不允许重新更新音频下载地址。
查询接口（接口3），24小时内有效。
回调通知接口（接口4），由用户服务保证可用性

错误码定义

错误码	描述	userMessage	备注
0	成功	success	通用错误码
1001	参数不合法	invalid.parameter	通用错误码
60001	传入的 enterpriseId 有误	sdk.invalid.key	云平台的错误码
60003	API 签名不对	openapi.invalid.signature	云平台的错误码
60011	没有传签名	signature.required	云平台的错误码
60015	没有权限	no permission	云平台的错误码
60060	找不到可用的AI服务资源	no ai service	云平台的错误码
340201	任务ID不存在，或接口过期(可多次查询，最久24小时有效)	id not found	AI能力服务错误码
340202	任务已启用，一个session只允许被创建一个离线转写任务。即接口offlineAsrTaskUrl不允许被同一个sessionId多次调用	already used	AI能力服务错误码
340203	音频格式不支持，当前仅支持aac、wav	audio format not support	AI能力服务错误码
340204	上传音频 body大小超过限制(500MB)	audio file too large	AI能力服务错误码
340205	上传音频失败	uploading failed	AI能力服务错误码
340206	音频流下载失败	downloading failed	AI能力服务错误码
340207	音频解码失败	decode audio failed	AI能力服务错误码
340208	ASR转写失败	asr failed	AI能力服务错误码
340209	向用户回调通知失败	notify callback failed	AI能力服务错误码
340210	ASR进程未初始化或未就绪	asr proc un init	AI能力服务错误码
340301	必需的HTTP头部字段缺失	required header	AI能力服务错误码
340302	缺少metadata参数	no metadata	AI能力服务错误码
340303	服务器关闭	server closed	AI能力服务错误码
340304	客户端主动断开连接	client disconnected	AI能力服务错误码
340305	上传超时	upload timeout	AI能力服务错误码
340306	上传失败	upload failed	AI能力服务错误码
340307	无效的sourceType参数	invalid source type	AI能力服务错误码

2.1分配AI服务器资源

URL: /api/rest/external/v1/transcription/task/allocate?enterpriseId=xxxxx
Method： POST
Content-Type： application/json

请求参数

参数名	必选	类型	说明
enterpriseId	是	string	外部企业ID，可以从管理平台获取，用来将请求路由到企业专有服务器。
type	是	string	转写类型：`offline`，离线转写；`realtime`，实时转写 (暂不支持)。
callback	否	string	离线转写专用。任务完成后的回调通知地址。若不提供，则只能通过查询接口（接口3）获取转写状态和结果。

{
  "type": "offline",
  "callback": "https://your-server.com/callback/path"
}

成功响应 (HTTP 200)

{
  "sessionId": "ef43fe808f7377564ed04d969fb88625",
  "offlineAsrTaskUrl": "https://ai-service.example.com/api/rest/aigw/offline/asr/task/create/v1?router=xxx&sessionId=ef43fe808f7377564ed04d969fb88625",
  "queryProgressUrl": "https://ai-service.example.com/api/rest/aigw/offline/asr/progress/query/v1?router=xxx&sessionId=ef43fe808f7377564ed04d969fb88625",
  "expiresAt": 1752205576
}

错误响应 (HTTP 4XX)

{
  "errorCode": 60003,
  "developerMessage": "签名验证失败",
  "userMessage": "openapi.invalid.signature",
  "moreInfo": "请检查您的签名算法和密钥"
}

参数名	必选	类型	说明
errorCode	是	int	错误码，非0值见错误码定义
developerMessage	否	string	错误信息提示
userMessage	否	string	错误信息提示
moreInfo	否	string	错误信息提示

2.2 创建离线转写任务接口

URL： 接口1返回的 offlineAsrTaskUrl
Method： POST
Content-Type： multipart/form-data
音频获取方式：支持通过表单上传音频二进制数据，或提供可公开访问的音频下载地址。
注意：目前源语音仅支持中文，srcLang 参数请固定设置为 zh。 tarLang 同理。

请求参数 (置于 `multipart/form-data` 中)

参数名	必选	类型	说明
metadata	是	string	JSON格式字符串，包含以下任务配置参数。
audio	是	file/string	当`sourceType=0`时，为二进制音频文件。当`sourceType=1`时，为一个URL编码的字符串，格式如`url=https%3A%2F%2F...`。

metadata JSON对象字段

参数名	必选	类型	说明
srcLang	是	string	音频源语言。当前仅支持 `zh` (中文)。
tarLang	否	string	翻译目标语言。支持 `en` (英文)。仅在 `enableTrans` 为 `true` 时有效。
enableTrans	否	bool	是否开启翻译功能，默认不开启
enableRole	是	bool	是否开启说话人角色分离功能。
roleNum	是	int	音频中说话人的数量。`0`: 不确定，由算法自动识别；`1`: 单人；`2`: 双人；最多支持 `10` 人。仅当 `enableRole` 为 `true` 时此参数有效。
sourceType	是	int	`0`: 音频数据上传模式；`1`: 提供音频文件下载url模式。
audioFormat	是	string	音频格式。当前仅支持：`wav` 或 `aac`

请求示例

方式一：上传音频文件 (sourceType: 0)

http

POST https://ai-service.example.com/...&sessionId=xxx
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{"srcLang":"zh","tarLang":"en","enableTrans":true,"enableRole":true,"roleNum":3,"sourceType":0, "audioFormat":"aac"}
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="audio"; filename="meeting.aac"
Content-Type: audio/aac

(这里是音频文件的二进制数据)
----WebKitFormBoundary7MA4YWxkTrZu0gW--

方式二：提供音频下载地址 (sourceType: 1)

http

POST https://ai-service.example.com/...&sessionId=xxx
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{"srcLang":"zh","tarLang":"en","enableTrans":true,"enableRole":true,"roleNum":2,"sourceType":1, "audioFormat":"aac"}
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="audio"
Content-Type: text/plain

https://your-storage.com/audio/meeting.aac
----WebKitFormBoundary7MA4YWxkTrZu0gW--

成功响应 (HTTP 200)

任务已成功接收并进入处理队列。

错误响应 (HTTP 4XX)

格式同接口1。

2.3 转写状态查询接口

URL： 接口1返回的 queryProgressUrl
Method： GET

成功响应 (HTTP 200)

{
  "status": "processing",
  "estimatedRemainingSeconds": 120,
  "userMessage": "wait processing",
  "sessionId":"ef43fe808f7377564ed04d969fb88625",
  "aiResult":{ /* 完整的2.5格式的JSON数据 */ }
}

字段说明：

status: 任务状态。取值：

pending: 排队中
processing: 转写中
completed: 转写完成
failed: 转写失败（通常通过HTTP 4XX错误码体现）

estimatedRemainingSeconds: 转写完成预估剩余时间（秒）。此时间仅供参考，可能不准确。
aiResult: 仅当 status 为 completed 时，此字段才存在不为空，内容为完整的转写结果JSON，格式见 2.5。
userMessage: (可选字段) 当转写成功但回调通知(callback)失败时，此字段会包含提示信息（如”request the callback failed”），此时aiResult仍包含有效结果，用户可通过此接口获取。

错误响应 (HTTP 4XX)

格式同接口1。

2.4 转写结束通知接口（需用户实现）

URL： 用户在接口1的 callback 参数中提供的地址。
Method： POST
Content-Type： application/json

请求参数

参数名	必选	类型	说明
sessionId	是	string	任务唯一ID，与接口1返回的 `sessionId` 一致。
status	是	string	任务最终状态：`completed` (成功) 或 `failed` (失败)。
aiResult	否	string	当 `status` 为 `completed` 时存在，为转写结果JSON，格式见 2.5。
errorCode	否	int	当 `status` 为 `failed` 时存在，错误码见文档前文。
userMessage	否	string	当 `status` 为 `failed` 时存在，错误描述信息。

请求示例

转写成功

json

{
  "sessionId":"ef43fe808f7377564ed04d969fb88625",
  "status": "completed",
  "aiResult":{ /* 完整的2.5格式的JSON数据 */ }
}

转写失败

json

{
  "sessionId": "ef43fe808f7377564ed04d969fb88625",
  "status": "failed",
  "errorCode": 340203,
  "userMessage": "audio format not support"
}

响应要求

用户服务在收到回调后，应尽快处理并返回 HTTP 200 状态码。
若用户服务返回非200状态码或网络超时，平台侧可能会重试（重试策略请咨询平台方），并可能在查询接口（接口3）的响应中附带回调失败提示。

2.5 转写结果格式 (`aiResult` 字段)

aiResult 字段是一个JSON对象，其结构示例如下：

{
  "createdAt": 1752205656,
  "completedAt": 1752205789,
  "details": [
    {
      "bt": 1358,
      "et": 23838,
      "text": "各位好",
      "targetText": "Hello everybody",
      "srcLang": "zh",
      "targetLang": "en",
      "seId": "5ee460bc1f9742e395e96cdd3bea09a3",
      "role": 1,
      "words": [
        {
          "word": "各位",
          "bt": 1358,
          "et": 21358
        },
        {
          "word": "好",
          "bt": 21358,
          "et": 23838
        }
      ]
    },
    {
      "bt": 23838,
      "et": 542345,
      "text": "今天的讨论的重点是，如何提高工作效率",
      "targetText": "Today's discussion focuses on how to improve work efficiency",
      "srcLang": "zh",
      "targetLang": "en",
      "seId": "b408a48efcea4c9ba892bd576e182bf2",
      "role": 2,
      "words": [
        // ... 分词数据
      ]
    }
  ]
}

字段说明：

createdAt/completedAt: 任务创建和完成的Unix时间戳（单位秒），含音频上传下载时间。
details: 数组，包含每一句的转写结果。

bt/et: 句子开始和结束时间，相对于音频开始的毫秒数。
text: 源语言转写文本。
targetText: 翻译文本（仅当开启翻译时存在）。
srcLang/targetLang: 源语言和目标语言代码。
seId: 句子唯一ID。
role: 说话人角色ID。-1：未开启角色分离；0：已开启但未识别出角色；1-10：识别出的具体说话人编号。
words: 分词列表，包含每个词的文本及其起止时间，单位毫秒。

2026-03-16 15:27:02

导出PDF文档

接口清单

术语表

1、交互流程

2、接口细节

2.1分配AI服务器资源

请求参数

2.2 创建离线转写任务接口

请求参数 (置于 multipart/form-data 中)

请求示例

成功响应 (HTTP 200)

错误响应 (HTTP 4XX)

2.3 转写状态查询接口

成功响应 (HTTP 200)

错误响应 (HTTP 4XX)

2.4 转写结束通知接口（需用户实现）

请求参数

请求示例

响应要求

2.5 转写结果格式 (aiResult 字段)

请求参数 (置于 `multipart/form-data` 中)

2.5 转写结果格式 (`aiResult` 字段)