文件管理

文件属性

属性名	说明	类型
id	图片ID	number
category_id	分类ID	number
title	文件名	string
path	S3 key	string
cover_url	封面完整url	string
file_type	文件大小	number
created_at_gmt	创建时间	string
updated_at_gmt	更新时间	string
url	文件完整url	string
show_size	文件大小展示	string

获取文件列表

GET /openapi/2025-04/files

权限：read_files

Query Parameters

Name	Type	Description
file_name	string	文件名
category_id	string	分类ID
ids	String	文件id串，用,隔开，格式:1,2,3；当设置ids时分类失效
exclude_ids	String	排除的文件id串，用,隔开，格式:1,2,3；

200: OK

{
    "data": [
        {
            "id": 62596,
            "category_id": 0,
            "title": "WechatIMG5328.jpeg",
            "alt": "",
            "path": "image/2022/08/e0a5c5d82bf274a853c7645126d9a93cea1a6380fa897092558c9d28e9832e4a.jpeg",
            "cover_url": "https://cdn.com/image/2022/08/e0a5c5d82bf274a853c7645126d9a93cea1a6380fa897092558c9d28e9832e4a.jpeg",
            "file_type": "image/jpeg",
            "size": 164343,
            "created_at_gmt": "2022-09-01 08:52:45",
            "updated_at_gmt": "2022-09-01 08:52:45",
            "post_id": 33211,
            "cover_width": 1702,
            "cover_height": 1276,
            "oss_url": "https://cdn.com/image/2022/08/e0a5c5d82bf274a853c7645126d9a93cea1a6380fa897092558c9d28e9832e4a.jpeg",
            "is_hide": 0,
            "hash": "",
            "re_created_at_gmt": "2022-09-01 08:52:45",
            "url": "https://cdn.com/image/2022/08/e0a5c5d82bf274a853c7645126d9a93cea1a6380fa897092558c9d28e9832e4a.jpeg",
            "show_size": "160.49 KB",
            "created_time": "2022-08-31 20:52:45",
            "media_content_type": "image",
            "post": {
                "ID": 33211,
                "url": "https://cdn.com/image/2022/08/e0a5c5d82bf274a853c7645126d9a93cea1a6380fa897092558c9d28e9832e4a.jpeg",
                "thumbnail": "https://cdn.com/image/2022/08/e0a5c5d82bf274a853c7645126d9a93cea1a6380fa897092558c9d28e9832e4a.jpeg",
                "media_content_type": "image",
                "alt": "",
                "width": null,
                "height": null,
                "aspect_ratio": null,
                "slug": "e0a5c5d82bf274a853c7645126d9a93cea1a6380fa897092558c9d28e9832e4ajpeg",
                "file_id": 62596
            }
        }
    ],
    "links": {
        "first": "https://shop.com/openapi/2025-04/files?page=1",
        "last": "https://shop.com/openapi/2025-04/files?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://shop.com/openapi/2025-04/files",
        "per_page": 25,
        "to": 1,
        "total": 1
    }
}

获取文件预授权

POST /openapi/2025-04/files/sign

权限：write_files

Request Body

Name	Type	Description
filename*	String	文件名
mime_type*	String	文件类型 image/jpeg 默认值 image/jpg image/gif image/png image/webp video/mp4 video/quicktime
resource*	String	资源类型 image 默认值 video

200: OK

{
	"action": "https://test-s3.s3.us-east-2.amazonaws.com",
	"method": "POST",
	"enctype": "multipart/form-data",
	"parameters": {
		"acl": "public-read",
		"key": "image/2021/10/43d2ae22fdb8b25ada2c709c85e6ff07ef174f9599d66cdd8af693a2310b8415.jpg",
		"X-Amz-Credential": "AKIAUEHNTHTUXGUMQ3TN/20211018/us-east-2/s3/aws4_request",
		"X-Amz-Algorithm": "AWS4-HMAC-SHA256",
		"X-Amz-Date": "20211018T034356Z",
		"Policy": "eyJleHBpcmIyMS0xMC0xOFQwMzo1Mzo1NloiLCJjb25kaXRpb25zIjpbeyJhY2wiOiJwdWJsaWMtcmVhZCJ9LHsiYnVja2V0Ijoid3Nob3AtczMifSxbInN0YXJ0cy13aXRoIiwiJGtleSIsImltYWdlXC8yMDIxXC8xMFwvNDNkMmFlMjJmZGI4YjI1YWRhMmM3MDljODVlNmZmMDdlZjE3NGY5NTk5ZDY2Y2RkOGFmNjkzYTIzMTBiODQxNS5qcGciXSxbImNvbnRlbnQtbGVuZ3RoLXJhbmdlIiwwLDMxNDU3MjgwXSx7IlgtQW16LURhdGUiOiIyMDIxMTAxOFQwMzQzNTZaIn0seyJYLUFtei1DcmVkZW50aWFsIjoiQUtJQVVFSE5USFRVWEdVTVEzVE5cLzIwMjExMDE4XC91cy1lYXN0LTJcL3MzXC9hd3M0X3JlcXVlc3QifSx7IlgtQW16LUFsZ29yaXRobSI6IkFXUzQtSE1BQy1TSEEyNTYifV19",
		"X-Amz-Signature": "7ace522db95c6a0e8eef15b4eb86a23f1aeafeb57c114b",
		"bucket": "bucket-test"
	}
}

保存文件

POST /openapi/2025-04/files

权限：write_files

Request Body

Name	Type	Description
key	String	S3 Key，由预签名接口下发，当file_content_type为image时必传
file_name	String	文件原始名，用于文件管理展示，当file_content_type为image时必传
mime_type	String	具体类型，当file_content_type为image必传 image/jpeg 默认值 image/jpg image/gif image/png image/webp video/mp4 video/quicktime
file_content_type*	String	文件类型 image 默认值 external_image 外部图 video 视频
category_id*	number	分类id
url	String	外部文件地址，当file_content_type为external_image时必传
is_hide	String	是否隐藏，1是，0否

获取文件分类列表

GET /openapi/2025-04/file_categories

权限：read_files

Query Parameters

Name	Type	Description
type	String	文件类型，非必传（不传默认全部）

200: OK

{
    "data": [{
        "id": 1,
        "title": "未分类",
        "files_count": 7
    }]
}