跳到正文
联系我们 开始接入
文件上传 API

文件上传 API 总览

把用户在 S1 上录制的音频分片上传到 iKho 存储,合并后拿到下载地址,作为 file_url 交给转写 API。

开发者平台处于内测阶段,接口契约以联调时提供的正式文档为准。当前 base URL 为 https://ikho.cn/developer/api,凭证由对接工程师开通,见联系我们。

上传流程

音频以分片方式上传,分三步完成:

1
生成预签名上传地址
调用 generate-presigned-urls,按文件大小返回一组预签名地址,每个地址对应一个分片。
2
逐片 PUT 上传
把每个分片的原始字节带上用户令牌直接 PUT 到对应的本平台分片直传端点(PresignedUrl),本平台代理写入存储。保存每次响应头里的 ETag。
3
合并分片完成上传
把收集到的 ETag 列表提交给 complete-upload,拿到可下载地址 DownloadUrl,作为 file_url 交给转写 API。

支持格式与限制

  • 支持音频格式:mp3、m4a、wav。
  • 单文件大小与分片大小上限:内测期以联调口径为准。

鉴权

文件上传全程使用用户令牌鉴权(见获取用户令牌):生成预签名地址、逐片 PUT 直传、合并分片、下载文件,都要带上 Bearer 用户令牌。逐片 PUT 的目标是本平台分片直传端点(PresignedUrl),字节经本平台代理写入存储,不直接暴露对象存储地址;该端点由生成预签名地址时返回,不在此单列。

断点续传与重试

分片上传天然支持断点续传:每个分片独立 PUT,某一片失败或中断,只需重传该分片,已成功的分片不受影响。实践建议:

  • 逐片记录已拿到的 ETag;失败的分片按原 PartNumber 重传到原预签名地址即可,重传成功后以最新一次响应的 ETag 为准。
  • 网络类失败做有限次数的重试(例如 3 次),每次间隔递增,避免对存储侧形成突发压力。
  • UploadId 在有效期内持续可用:中断后无需从头再来,直接续传剩余分片,再调用 complete-upload 合并。有效期过后,该上传会话失效,需要重新调用 generate-presigned-urls 发起一次新的上传。有效期长度内测期以联调口径为准。
  • 单个 PresignedUrl 同样有时效;若重传时地址已过期,重新生成一组预签名地址后再续传。

文件上传 API 是可选的。如果你已有可公网访问的音频地址,可跳过上传,直接把地址作为 file_url 交给转写 API。

错误结构与错误码见错误码参考。