超级智体

超级智体-图片暂存系统

本系统用于图片和内容的临时暂存、链接生成、自动清理和后台维护。公开页面仅作为接口说明入口，不提供前端上传组件。

最大体积 50MB 上传无需密钥 自动保留策略由后台控制

详细 API 说明

以下内容可直接发送给第三方开发者。除特别说明外，接口返回均为 JSON，上传限制以后台当前设置为准。

API Base URL https://oss.chaojizhiti.com/api
单次上传上限 50MB
上传密钥 当前不需要
图片转换 不自动转换，按原文件类型保存

一、接入概览

上传接口 POST https://oss.chaojizhiti.com/api/upload
删除接口 https://oss.chaojizhiti.com/api/delete/{delete_code}/{hash}
文件信息 GET https://oss.chaojizhiti.com/api/info/{hash}
推荐请求格式 文件上传使用 multipart/form-data；Base64 和 URL 上传使用 application/x-www-form-urlencoded。
错误判断 业务成功或失败以 JSON 里的 status 字段为准；不要只依赖 HTTP 状态码。
允许格式 mp4, url, md, markdown, mp3, wav, ogg, flac, m4a, album, txt, text, csv, png, bmp, gif, jpg, jpeg, x-png, webp, ico

二、上传接口

POST https://oss.chaojizhiti.com/api/upload

参数 位置 必填 说明
file multipart/form-data 三选一 直接上传本地文件，推荐用于大文件和图片原图。
base64 form 三选一 提交 Base64 内容，支持 data:image/jpeg;base64,... 或纯 Base64。系统会在解码前后检查 50MB 上限。
url form 或 query 三选一 让服务器从远程 HTTP/HTTPS 地址拉取文件。私有 IP、无效 URL 和超过大小限制的远程文件会被拒绝。
uploadcode form 或 query 否 当前后台未启用上传密钥；如后续启用，调用方需要同步增加此参数。
hash form 或 query 否 可选自定义文件标识。通常建议不传，由系统自动生成，避免冲突。
同一次请求只需要选择 file、base64、url 中的一种上传方式。大文件优先使用 file，Base64 会比原二进制体积更大。远程 URL 拉取不跟随跳转，目标地址必须能直接返回文件内容。

三、请求示例

直接文件上传：

curl -s -X POST \
  -F "file=@image.jpg" \
  "https://oss.chaojizhiti.com/api/upload"

Base64 上传：

curl -s -X POST \
  --data-urlencode "base64=data:image/jpeg;base64,/9j/4AAQ..." \
  "https://oss.chaojizhiti.com/api/upload"

远程 URL 上传：

curl -s -X POST \
  --data-urlencode "url=https://example.com/image.jpg" \
  "https://oss.chaojizhiti.com/api/upload"

四、成功返回

新文件上传成功：

{
  "status": "ok",
  "hash": "7eli4d.jpg",
  "filetype": "image/jpeg",
  "url": "https://oss.chaojizhiti.com/7eli4d.jpg",
  "delete_code": "delete-code",
  "delete_url": "https://oss.chaojizhiti.com/delete_delete-code/7eli4d.jpg"
}

重复文件返回：

{
  "status": "ok",
  "duplicate": true,
  "hash": "7eli4d.jpg",
  "filetype": "image/jpeg",
  "url": "https://oss.chaojizhiti.com/7eli4d.jpg"
}
hash 系统保存后的文件标识，访问、删除和查询信息时都需要使用。
url 可直接访问的公开链接。
delete_code 删除凭证。只在新上传成功时返回，调用方必须自行保存。
delete_url 删除链接。只在新上传成功时返回，后续可用于删除该文件。
duplicate 为 true 时表示系统已存在相同内容，返回的是已有文件链接。

五、删除与查询

删除时推荐直接保存并调用上传返回里的 delete_url。如需拼接 API 地址，可使用：

curl -s "https://oss.chaojizhiti.com/api/delete/{delete_code}/{hash}"

查询文件元信息：

curl -s "https://oss.chaojizhiti.com/api/info/{hash}"

信息接口成功时直接返回 metadata，不额外包一层 status=ok：

{
  "mime": "image/jpeg",
  "size": 204800,
  "size_human": "200 KB",
  "original_filename": "image.jpg",
  "hash": "7eli4d.jpg",
  "sha1": "40-character-sha1",
  "uploaded": 1782810000
}
删除凭证无法从公开信息接口反查。第三方系统需要在首次上传成功后保存 hash、url、delete_code 和 delete_url。

六、错误格式与常见原因

{
  "status": "err",
  "reason": "File too big. 50MB max"
}
reason 含义 处理建议
Access denied 来源 IP 不在允许范围内。 联系管理员放行调用方出口 IP。
Incorrect upload code specified - Access denied 上传密钥缺失或错误。 提交正确的 uploadcode。
File too big. 50MB max 文件、远程文件或 Base64 解码后内容超过后台上限。 压缩文件或联系管理员调整上传上限。
Unsupported mime type: ... 文件类型不在当前允许范围内。 使用允许格式，或由管理员在后台启用对应类型。
Invalid base64 payload Base64 内容无法严格解码。 确认编码完整，建议使用 data:*;base64,... 格式。
Private IP range / Invalid URL 远程 URL 不合法，或指向内网地址。 使用公开可访问的 HTTP/HTTPS 文件地址。
No file uploaded 没有提交 file、base64 或 url。 按三种上传方式之一提交参数。
Upload error: ... PHP 接收上传文件失败，例如超过 PHP 环境限制或临时目录异常。 检查客户端文件大小、网络连接和服务器环境状态。
Hash not found 查询或删除的 hash 不存在，可能已过期清理。 确认保存的是上传返回的完整 hash。
Invalid delete code 删除凭证不匹配。 使用首次上传返回的 delete_code 或 delete_url。

七、接入注意事项

  • Base64 会比原始二进制更大；接近 50MB 的文件建议使用 multipart/form-data 直接上传。
  • 如果后台启用 PNG 转 JPG，返回的 hash 和 url 可能使用 .jpg 后缀，调用方应以返回值为准。
  • 系统会按内容 SHA1 做重复检测，相同文件再次上传可能返回 duplicate=true。
  • 保留策略由后台控制，超过管理员设置的保留时间后，文件可能被自动清理。
  • 公开页面不提供上传测试组件；第三方系统请直接调用 API。
  • 项目内可能保留旧版 /src/api/*.php 文件；第三方新接入统一使用本文档中的 /api/... 路径。