小影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 聚合服務