小影API 小影API

文件上传

通用文件上传能力：图片/视频/声音/普通文件，白名单校验并存储到本地 /media，返回可访问 URL。

/api/upload/

服务说明

文件上传服务提供图片、视频、声音与通用文件四类上传入口，文件落盘到站点 /media 目录并返回可直接引用的 URL，适合作为业务系统的统一附件通道。

全部接口使用 multipart/form-data，文件字段名固定为 file。服务端按白名单校验扩展名并校验文件头（magic bytes），可内联渲染或执行的文件类型（如 svg、html、脚本）一律拒绝，避免上传文件被当作存储型 XSS 利用。

体积限制：图片与声音最大 20MB，视频与通用文件最大 100MB。声音时长须在 3-60 秒之间，WebM / OGG 等浏览器录音格式会自动转成 MP3 后再返回。本服务需项目签名。

响应格式

所有接口返回同一个 JSON 信封，业务数据都在 data 里： 

{
  "code": 10000,
  "msg": "成功",
  "data": { ... }
}
  • code：业务状态码，10000 表示成功；其余为各类错误，完整清单见「错误码」页。
  • msg：给人看的提示文案，可直接展示给终端用户，但不要用它做逻辑判断。
  • data：业务数据；出错时通常为 null。各接口 data 的具体字段见该接口的「响应说明」。

判断成功与否请看 code，不要依赖 HTTP 状态码。 查看完整错误码

本地文件上传

本地存储（/media/uploads/…） 需签名

全部使用 multipart/form-data，文件字段固定为 file；仅支持白名单类型并校验文件头（防伪装/防脚本上传）。

POST /api/upload/image 累计调用 17 次

上传图片

上传图片，返回可直接引用的图片 URL。

multipart/form-data 文件字段 file：直接用下方“选择文件”上传即可。

  • 支持类型：jpg/jpeg/png/gif/bmp/webp/ico/tiff；最大 20MB。
  • svg 因可内嵌脚本已禁用。
响应说明 外层统一格式
字段 类型 说明
filename string 存储后的文件名
original_name string 原始文件名
size int 文件大小（字节）
size_mb float 文件大小（MB，2 位小数）
ext string 扩展名
type string 类型：image/video/file/audio
relative_path string 相对 media 的路径
url string 可访问地址（/media/...）
返回示例 
{"filename": "a1b2c3d4_20260627120000.jpg", "original_name": "photo.jpg", "size": 123456, "size_mb": 0.12, "ext": "jpg", "type": "image", "relative_path": "uploads/images/a1b2c3d4_20260627120000.jpg", "url": "/media/uploads/images/a1b2c3d4_20260627120000.jpg"}
POST /api/upload/video 累计调用 5 次

上传视频

上传视频文件。

multipart/form-data 文件字段 file：直接用下方“选择文件”上传即可。

  • 最大 100MB；返回 type=video。
响应说明 外层统一格式
字段 类型 说明
filename string 存储后的文件名
original_name string 原始文件名
size int 文件大小（字节）
size_mb float 文件大小（MB，2 位小数）
ext string 扩展名
type string 类型：image/video/file/audio
relative_path string 相对 media 的路径
url string 可访问地址（/media/...）
返回示例 
{"filename": "a1b2c3d4_20260627120000.mp4", "original_name": "clip.mp4", "size": 5242880, "size_mb": 5.0, "ext": "mp4", "type": "video", "relative_path": "uploads/videos/a1b2c3d4_20260627120000.mp4", "url": "/media/uploads/videos/a1b2c3d4_20260627120000.mp4"}
POST /api/upload/file 累计调用 9 次

上传通用文件

上传通用文件（白名单：zip/pdf/docx/xlsx/txt 等）。

multipart/form-data 文件字段 file：直接用下方“选择文件”上传即可。

  • 最大 100MB；白名单制并校验文件头；返回 type=file。
响应说明 外层统一格式
字段 类型 说明
filename string 存储后的文件名
original_name string 原始文件名
size int 文件大小（字节）
size_mb float 文件大小（MB，2 位小数）
ext string 扩展名
type string 类型：image/video/file/audio
relative_path string 相对 media 的路径
url string 可访问地址（/media/...）
返回示例 
{"filename": "a1b2c3d4_20260627120000.pdf", "original_name": "report.pdf", "size": 204800, "size_mb": 0.2, "ext": "pdf", "type": "file", "relative_path": "uploads/files/a1b2c3d4_20260627120000.pdf", "url": "/media/uploads/files/a1b2c3d4_20260627120000.pdf"}
POST /api/upload/voice 累计调用 0 次

上传声音

上传 3-60 秒的声音文件，返回在线播放链接与真实时长。

multipart/form-data 文件字段 file：支持 mp3/wav/m4a/aac/ogg/flac/webm/amr/wma，最大 20MB，时长须在 3-60 秒之间。

  • 时长由服务端用 ffprobe 读取音频流，短于 3 秒或长于 60 秒返回 20003 并删除文件。
  • WebM / OGG / FLAC / AMR / WMA 会自动转成 MP3（128kbps）再返回，保证微信、Safari 等环境也能直接播放；MP3 / M4A / WAV / AAC 原样保存。
  • 返回的 url 为完整在线链接：配置了 XYAPI_SITE_URL 时用该域名，否则按当前请求的域名推导。
  • 音频文件可直接以内联方式播放（支持浏览器拖动进度条所需的 Range 请求）。
  • 不想写代码时，可点下方「网页录音」直接在浏览器里录制、试听并上传（需登录）；录音优先使用 MP4/AAC，Chrome / Safari 都能正常试听。
响应说明 外层统一格式
字段 类型 说明
filename string 存储后的文件名
original_name string 原始文件名
size int 文件大小（字节）
size_mb float 文件大小（MB，2 位小数）
ext string 扩展名
type string 类型，固定为 audio
duration float 声音真实时长（秒，2 位小数）
relative_path string 相对 media 的路径
url string 在线播放链接（完整地址，可直接用于 <audio src>）
返回示例 
{"filename": "a1b2c3d4_20260627120000.m4a", "original_name": "my_voice.m4a", "size": 204800, "size_mb": 0.2, "ext": "m4a", "type": "audio", "duration": 12.35, "relative_path": "uploads/voices/a1b2c3d4_20260627120000.m4a", "url": "https://example.com/media/uploads/voices/a1b2c3d4_20260627120000.m4a"}

文件上传 API 常见问题

上传接口有哪几个？
图片、视频、声音、通用文件四个入口，都返回可直接访问的 URL，表单字段统一为 multipart 文件。
有格式与大小限制吗？
有白名单校验：按接口类型限制扩展名与 MIME，超出即报参数错误；具体上限见文档页各端点的参数说明。
文件存在哪里？
存本站 /media 目录并返回可访问链接，适合没有对象存储的小项目临时托管；大流量或商用场景建议接自己的 OSS / CDN，避免占用本站带宽。
文件上传接口怎么接入？需要签名吗？
文件上传挂在 /api/upload/ 前缀下：需签名的端点按 app_id + timestamp + nonce + sign（HMAC-SHA256，密钥为 APPSECRET）调用，开放端点直接请求即可。拿不准时用本页右侧的「在线调试」—— 它会代签并把你实际发出的请求与真实响应都回显出来。
文件上传的返回结构和错误码怎么看？
全部接口统一返回 {code, msg, data}：code=10000 表示成功，2xxxx 为业务错误，3xxxx / 4xxxx / 5xxxx 分别为外部依赖、客户端与系统错误。完整含义与处理建议见「错误码总表」（/docs/errors/）。
小影API · 通用 API 聚合服务