录音上传系统 · 接口文档

API 接口文档

基础地址:http://app.bd(局域网内把 app.bd 换成服务器 IP 或域名)。所有接口返回 JSON,业务结果看 code 字段,0 表示成功。

鉴权

在后台「系统设置」页获取 API Token,请求时任选以下一种方式携带:

 X-Api-Token: 你的Token
Authorization: Bearer 你的Token
或 URL 参数:?token=你的Token

1. GET /api/ping — 连通性测试

curl -H "X-Api-Token: TOKEN" http://app.bd/api/ping

{"code":0,"msg":"pong","data":{"server_time":1763270000}}

2. GET /api/config — 获取上传限制

App 启动时调用,读取服务端允许的后缀与大小限制。不会返回 OSS 密钥。

{"code":0,"msg":"ok","data":{
  "storage":"oss",
  "max_size":52428800,
  "allowed_ext":["mp3","m4a","wav","aac","ogg","flac","amr","wma","mp4"],
  "server_time":1763270000
}}

3. POST /api/upload — 上传录音

Content-Type: multipart/form-data,文件字段名 file。多文件重复该字段(file[])。可选字段 duration(秒,数组与文件顺序对应)。

curl -X POST http://app.bd/api/upload \
  -H "X-Api-Token: TOKEN" \
  -F "file=@/sdcard/DCIM/voice/录音001.m4a" \
  -F "file=@/sdcard/DCIM/voice/录音002.mp3" \
  -F "duration[0]=125" -F "duration[1]=68"

返回示例:

{"code":0,"msg":"上传成功","data":{
  "uploaded":2,
  "files":[
    {"id":12,"name":"录音001.m4a","size":2048000,"duration":"125",
     "storage":"oss","url":"https://bucket.oss-cn-shanghai.aliyuncs.com/recordings/20261116/ab12.mp3"}
  ],
  "errors":[]
}}

全部失败时 code=500,msg 给出原因;部分失败时 code=0,失败明细在 data.errors。

4. GET /api/files — 文件列表

参数:page(默认1)、limit(默认20,最大100)

{"code":0,"msg":"ok","data":{
  "total":35,"page":1,"limit":20,
  "list":[{"id":12,"original_name":"录音001.m4a","size":2048000,
           "size_text":"1.95 MB","storage":"oss","url":"...","create_time":1763270000}]
}}

5. POST /api/delete — 删除文件

参数:id = 文件记录ID

curl -X POST -H "X-Api-Token: TOKEN" -d "id=12" http://app.bd/api/delete

{"code":0,"msg":"已删除","data":[]}

安卓端接入要点(Kotlin)

这部分供后续做 App 时参考,当前交付仅包含后端接口。

权限(AndroidManifest.xml)

<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
    android:maxSdkVersion="32" />
<uses-permission android:name="android.permission.INTERNET" />

扫描手机录音文件(MediaStore)

fun queryRecordings(context: Context): List<Audio> {
    val list = mutableListOf<Audio>()
    val uri = MediaStore.Audio.Media.EXTERNAL_CONTENT_URI
    val projection = arrayOf(
        MediaStore.Audio.Media._ID,
        MediaStore.Audio.Media.DISPLAY_NAME,
        MediaStore.Audio.Media.DURATION,
        MediaStore.Audio.Media.SIZE,
        MediaStore.Audio.Media.DATE_ADDED
    )
    // Android 10+ 只扫描 Music/ 与 Recordings/ 目录,可按需放宽
    val selection = "${MediaStore.Audio.Media.IS_MUSIC} != 0"
    context.contentResolver.query(uri, projection, selection, null,
        "${MediaStore.Audio.Media.DATE_ADDED} DESC")?.use { c ->
        val idCol = c.getColumnIndexOrThrow(MediaStore.Audio.Media._ID)
        val nameCol = c.getColumnIndexOrThrow(MediaStore.Audio.Media.DISPLAY_NAME)
        val durCol = c.getColumnIndexOrThrow(MediaStore.Audio.Media.DURATION)
        while (c.moveToNext()) {
            val contentUri = ContentUris.withAppendedId(uri, c.getLong(idCol))
            list.add(Audio(contentUri, c.getString(nameCol), c.getLong(durCol) / 1000))
        }
    }
    return list
}

用 OkHttp 上传(content:// Uri 直接作为请求体)

fun upload(context: Context, audio: Audio, token: String) {
    val bytes = context.contentResolver.openInputStream(audio.uri)!!.use { it.readBytes() }
    val body = MultipartBody.Builder().setType(MultipartBody.FORM)
        .addFormDataPart("file", audio.name,
            bytes.toRequestBody("audio/*".toMediaType()))
        .addFormDataPart("duration", audio.duration.toString())
        .build()
    val request = Request.Builder()
        .url("http://app.bd/api/upload")
        .header("X-Api-Token", token)
        .post(body).build()
    OkHttpClient().newCall(request).execute().use { resp ->
        val json = JSONObject(resp.body!!.string())
        // code == 0 即成功,data.files[0].url 为访问地址
    }
}

真机上大录音建议改成流式上传,避免 readBytes() 占用过多内存;同时注意 Android 9+ 明文 HTTP 限制,可用 android:usesCleartextTraffic="true" 或配置 network_security_config。

阿里云 OSS 配置提示

1. Bucket 所在地域的 Endpoint,例如华东1(杭州)为 oss-cn-hangzhou.aliyuncs.com。

2. RAM 子账号授权 AliyunOSSFullAccess(或仅授予目标 Bucket 的读写权限),使用其子账号 AK/SK。

3. 如需公网加速或自定义域名,填写「自定义域名 / CDN」;AK/SK 只保存在服务端数据库,接口不会下发。

4. 保存前可点击「测试 OSS 连接」验证 Bucket 是否可访问。