小影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 累计调用 0 次

上传图片

上传图片，返回可直接引用的图片 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 累计调用 0 次

上传视频

上传视频文件。

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 累计调用 0 次

上传通用文件

上传通用文件（白名单：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 · 通用 API 聚合服务