OSS 云存储

统一对象存储:用本站 API Key 签发后,文件直传阿里云,按用量从余额扣费。

客户端 sign 拿 upload_url,直传 OSS,再 confirm。本站不中转文件。
计费:存储按 GB·月、下行按 GB、请求按万次,按公示售价从余额扣。
余额低于 100 元停用。

调用地址:https://api.ynlskj.com.cn/gateway/oss

请求方法:POST

在其他地方怎么调用

  1. 请求地址用上面的调用地址,把 JSON 放在请求体里
  2. 方法用 POST
  3. API Key 只能放在请求头 X-API-Key,不要写进网址,也不要写进 Query 框
  4. Key 在「个人中心 → API Key」里复制,登录后会自动填入你自己的 Key

参数说明

参数位置必填说明
action Body JSON 是 sign / confirm / url / info / list / delete / usage / folder_create/list/update/delete/callbacks
folder Body JSON sign / folder_* 时 文件夹路径,如 photos。别名 dir
keep_latest Body JSON folder_* 时 只保留最新 N 条;0 = 永久保留。别名 retain_count
callback_url Body JSON 否 文件夹回调,须公网 http/https
key Body JSON sign 时建议 对象路径,如 avatars/me.png
filename / mime / size Body JSON sign 时建议 文件名、MIME、字节数
acl Body JSON 否 private(默认)或 public
file_id Body JSON confirm/url/info/delete 时 与 key 二选一。格式 of_xxx
expire Body JSON 否 url 签名有效期秒数,默认 3600,最大 86400
prefix / page / per_page Body JSON 否 list 时按 key 前缀筛选;每页 1–100,默认 20
X-API-Key Header 是 你的 API Key(请求头,不要放进网址或 Query)

这个接口是干什么的?

你不用自己开通阿里云。用本站 API Key 换限时 upload_url,文件由客户端直接 PUT 到平台 Bucket。本站只签发、隔离、按用量扣余额,不中转文件字节。

计费说明

  • 右侧预存档只是门槛参考:账户余额 ≥ 最低档即可直接用,不必再点开通。真正花钱是下面三笔,从账户余额扣
  • 按量扣余额:存储 0.204 元/GB/月,下行 0.85 元/GB,请求 0.017 元/万次
  • 什么时候扣、扣多少:文件还在桶里 → 按占用 GB×小时扣存储;有人真正从 OSS 下载 → 按访问日志里的字节数扣下行和 GET(大约整点后入账);confirm → 记 1 次 PUT。复制链接、调用 url 本身不预扣流量
  • 不足 1 分先记账,凑够 1 分再从余额划走,明细在余额变动里,备注以 OSS 开头
  • 余额须 ≥ ¥100.00,否则停用签发与 url,并把已有 public 改为私有;持续低于该金额满 7 天,自动删除已上传文件

典型流程

步骤Body 示例
0. 创建文件夹(可选){"action":"folder_create","folder":"photos","keep_latest":10,"callback_url":"https://你的域名/api/oss-callback"};也可在 sign 时直接传纯英文数字 folder 自动创建
1. 签发{"action":"sign","folder":"photos","filename":"a.jpg","mime":"image/jpeg","size":123456}
2. 直传对返回的 upload_url 发 PUT,Header 带返回的 Content-Type,Body 为文件二进制
3. 确认(必做){"action":"confirm","file_id":"of_xxx"}。漏这一步会一直「未确认」、大小 0B;定时任务也会尝试自动确认。PUT 后调 url/info 同样会自动确认
取访问地址{"action":"url","key":"photos/a.jpg","expire":3600}
列表 / 用量{"action":"list","prefix":"photos/"} {"action":"usage"}
文件夹管理{"action":"folder_list"} {"action":"folder_update","folder":"photos","keep_latest":20,"callback_url":"https://你的域名/api/oss-callback"} {"action":"folder_delete","folder":"photos"} {"action":"folder_callbacks","folder":"photos"}
删除{"action":"delete","file_id":"of_xxx"}

每次都返回同一套 JSON:ret / code / errmsg / data。业务值全在 data 里,例如签发取 data.upload_url,访问取 data.url。文件夹 keep_latest 只保留最新 N 条;删除文件夹规则不会删文件。清理回调示例字段:event / folder / keep_latest / deleted。

{
  "ret": "ok",
  "code": 200,
  "errmsg": "成功",
  "data": {
    "file_id": "of_xxx",
    "key": "photos/a.jpg",
    "filename": "a.jpg",
    "mime": "image/jpeg",
    "size": 123456,
    "acl": "private",
    "status": "active",
    "url": "https://example.oss-cn-chengdu.aliyuncs.com/...",
    "url_expire": 3600
  }
}

说明与限制

  • 阿里云密钥不下发;真实路径 u{用户ID}/年/月/fileId.ext,账号隔离
  • 单文件默认 1 GB、单账号 10 GB,可在 config.php 调整
  • 禁止 php / exe / sh / bat / asp / jsp 等可执行后缀
  • 浏览器直传需 Bucket CORS(本站首次签发时会尝试自动写入允许 PUT/GET)
  • confirm 只入库:私有文件没有长期链接,必须再调 url 换限时 GET 地址。sign 返回的 upload_url 只能 PUT,用浏览器打开会报 SignatureDoesNotMatch
  • 接口只返回一份 JSON:ret / code / errmsg / data。业务字段都在 data 里,例如 data.upload_url、data.file_id、data.url
  • 详情页上传默认会长期保存,可在「个人中心 → 我的文件」查看;只有勾选「临时调试」才会约 3 分钟后自动删除
  • sign 传 folder 时:若目录不存在且路径仅英文数字(如 photos、logs/app1)会自动创建;含中文/特殊字符须先 folder_create。也可用 folder_create 预设 keep_latest(只保留最新 N 条,0=永久)与可选 callback_url。folder_create 幂等:目录已存在时仍返回成功(data.already_exists=true),不会记为失败。超出条数会在 confirm / 定时任务中删除并回调。folder_delete 只取消规则,不删已有文件
  • 个人中心「我的文件」也是浏览器直传;打开、复制链接不预扣,真实下载后自动计下行

返回说明

字段说明
retok 成功,err 失败
data.file_id / data.key文件 ID 与你传入的对象路径。取值:json.data.file_id
data.url / data.url_expireurl 返回限时 GET 地址(秒)。取值:json.data.url。confirm/info 仅 public 才带固定链接
data.cdn_url自定义域名访问地址(配置 OSS_CDN_HOST,当前为 oss.ynlskj.com.cn)。active 时返回,如 http://oss.ynlskj.com.cn/u2/2026/09/of_xxx.apk;与阿里云直链 url 并存
data.upload_url / data.headerssign 返回的 PUT 专用地址,不能当下载链接打开;PUT 时必须带返回的 Content-Type
data.size / data.mime / data.acl / data.status字节数、MIME、private/public、active
data.fileslist 时的文件数组
data.bytes_used / data.max_bytesusage / list 时的已用与上限容量
data.bill仅 usage 返回:余额、最低余额、是否可用、售价

可直接复制的代码

未登录时示例只显示「你的密钥」。登录后会自动填入你自己的 Key,不会展示别人的。

<?php
$ch = curl_init('https://api.ynlskj.com.cn/gateway/oss');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['X-API-Key: 你的密钥', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => '{
    "action": "sign",
    "key": "demo/hello.txt",
    "filename": "hello.txt",
    "mime": "text/plain",
    "size": 9
}',
]);
echo curl_exec($ch);

请求参数演示

{"action":"sign","key":"demo/hello.txt","filename":"hello.txt","mime":"text/plain","size":9}

响应演示

{"ret":"ok","code":200,"errmsg":"成功","data":{"file_id":"of_xxxxxxxxxxxxxxxxxxxx","key":"photos/a.jpg","filename":"a.jpg","mime":"image/jpeg","size":123456,"acl":"private","status":"active","url":"https://bucket.oss-cn-chengdu.aliyuncs.com/u1/...","url_expire":3600}}

在线调试

登录后可在线调试。OSS 调试会按用量扣余额。

去登录