小影API 小影API

File Upload

General-purpose upload for images/videos/audio/documents: whitelist validation, stored under local /media, accessible URL returned.

/api/upload/

Service Description

The file upload service provides four entry points — images, videos, audio and documents — writing files to the site's /media directory and returning directly usable URLs, making it a unified attachment channel for business systems.

All endpoints use multipart/form-data with the file field fixed as file. The server validates the extension against a whitelist and checks magic bytes; file types that can be rendered inline or executed (such as svg, html and scripts) are rejected outright, so uploads cannot be abused as stored XSS.

Size limits: images and audio up to 20MB; videos and documents up to 100MB. Audio must be between 3 and 60 seconds; browser recording formats such as WebM / OGG are transcoded to MP3 before being returned. This service requires the project signature.

Response Format

Every endpoint returns the same JSON envelope; the payload is always inside data: 

{
  "code": 10000,
  "msg": "成功",
  "data": { ... }
}
  • code: business status code. 10000 means success; anything else is an error — see the Error Codes page for the full list.
  • msg: a human-readable message you can show to end users, but never use it for program logic.
  • data: the payload; usually null on error. Each endpoint's Response section lists its data fields.

Judge success by code, not by the HTTP status code. View all error codes

Local File Upload

Local storage (/media/uploads/...) Signature Required

All use multipart/form-data with the file field fixed to file; only whitelisted types are supported and file headers are validated (to prevent masquerading/script uploads).

POST /api/upload/image Total calls: 0

Upload Image

Upload an image and return a directly referenceable image URL.

multipart/form-data file field file: just use the "Select File" button below to upload.

  • Supported types: jpg/jpeg/png/gif/bmp/webp/ico/tiff; Size limit 20MB.
  • svg is disabled because it can embed scripts.
Response Common envelope
Field Type Description
filename string Stored file name
original_name string Original file name
size int File size (bytes)
size_mb float File size (MB, 2 decimals)
ext string Extension
type string Type: image/video/file/audio
relative_path string Path relative to media
url string Accessible URL (/media/...)
Example response 
{"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 Total calls: 0

Upload Video

Upload a video file.

multipart/form-data file field file: just use the "Select File" button below to upload.

  • Size limit 100MB; returns type=video.
Response Common envelope
Field Type Description
filename string Stored file name
original_name string Original file name
size int File size (bytes)
size_mb float File size (MB, 2 decimals)
ext string Extension
type string Type: image/video/file/audio
relative_path string Path relative to media
url string Accessible URL (/media/...)
Example response 
{"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 Total calls: 0

Upload Generic File

Upload a generic file (whitelist: zip/pdf/docx/xlsx/txt, etc.).

multipart/form-data file field file: just use the "Select File" button below to upload.

  • Size limit 100MB; whitelist-based with file header validation; returns type=file.
Response Common envelope
Field Type Description
filename string Stored file name
original_name string Original file name
size int File size (bytes)
size_mb float File size (MB, 2 decimals)
ext string Extension
type string Type: image/video/file/audio
relative_path string Path relative to media
url string Accessible URL (/media/...)
Example response 
{"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 Total calls: 0

Upload Voice

Upload a 3-60 second voice file and get an online playback link with the real duration.

multipart/form-data file field file: supports mp3/wav/m4a/aac/ogg/flac/webm/amr/wma, up to 20MB, duration must be between 3 and 60 seconds.

  • The server reads the audio stream with ffprobe; clips shorter than 3 seconds or longer than 60 seconds return 20003 and the file is deleted.
  • WebM / OGG / FLAC / AMR / WMA are transcoded to MP3 (128kbps) so they play directly in WeChat, Safari and other environments; MP3 / M4A / WAV / AAC are kept as-is.
  • The returned url is a complete online link: it uses XYAPI_SITE_URL when configured, otherwise it is derived from the current request's domain.
  • Audio files play inline directly (HTTP Range requests needed for seeking in the browser are supported).
  • If you prefer not to write code, click "Web Recorder" below to record, preview and upload right in the browser (sign-in required); recordings prefer MP4/AAC so both Chrome and Safari can preview them normally.
Response Common envelope
Field Type Description
filename string Stored file name
original_name string Original file name
size int File size (bytes)
size_mb float File size (MB, 2 decimals)
ext string Extension
type string Type, always audio
duration float Real voice duration (seconds, 2 decimals)
relative_path string Path relative to media
url string Online playback link (complete address, ready for <audio src>)
Example response 
{"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"}
XiaoYingAPI · Unified API Aggregation Service