OSS 云存储
上新统一对象存储:用本站 API Key 签发后,文件直传阿里云,按用量从余额扣费。
客户端 sign 拿 upload_url,直传 OSS,再 confirm。本站不中转文件。
计费:存储按 GB·月、下行按 GB、请求按万次,按公示售价从余额扣。
余额低于 100 元停用。
计费:存储按 GB·月、下行按 GB、请求按万次,按公示售价从余额扣。
余额低于 100 元停用。
调用地址:https://api.ynlskj.com.cn/gateway/oss
请求方法:POST
在其他地方怎么调用
- 请求地址用上面的调用地址,把 JSON 放在请求体里
- 方法用
POST - API Key 只能放在请求头
X-API-Key,不要写进网址,也不要写进 Query 框 - Key 在「个人中心 → API Key」里复制,登录后会自动填入你自己的 Key
参数说明
| 参数 | 位置 | 必填 | 说明 |
|---|---|---|---|
action | Body JSON | 是 | sign / confirm / url / info / list / delete / usage。不再支持中转 put |
key | Body JSON | sign 时建议 | 你自己的对象路径,如 avatars/me.png 或中文名。支持中文、字母数字、点、下划线、中划线、斜杠、括号。真实存储路径仍是平台生成的 u{用户ID}/年/月/fileId.ext |
filename / mime / size | Body JSON | sign 时建议 | 文件名、MIME、字节数。直传 PUT 的 Content-Type 必须与返回 headers 一致 |
acl | Body JSON | 否 | private(默认)或 public。余额不足停用时 public 会被收回 |
file_id | Body JSON | confirm/url/info/delete 时 | 与 key 二选一。格式 of_xxx |
expire | Body JSON | 否 | url 时签名有效期秒数,默认 3600,最大 86400。每次 url 按文件大小计一次下行 |
prefix / page / per_page | Body JSON | 否 | list 时按 key 前缀筛选;每页 1–100,默认 20 |
X-API-Key | Header | 是 | 你的 API Key |
这个接口是干什么的?
你不用自己开通阿里云。用本站 API Key 换限时 upload_url,文件由客户端直接 PUT 到平台 Bucket。本站只签发、隔离、按用量扣余额,不中转文件字节。
计费说明
- 右侧预存档只是门槛参考:账户余额 ≥ 最低档即可直接用,不必再点开通。真正花钱是下面三笔,从账户余额扣
- 按量扣余额:存储 0.18 元/GB/月,下行 0.75 元/GB,请求 0.015 元/万次
- 什么时候扣、扣多少:文件还在桶里 → 按占用 GB×小时扣存储;每次
url→ 按该文件大小扣 1 次下行;confirm→ 记 1 次 PUT(通常不到 1 分,会先攒着) - 不足 1 分先记账,凑够 1 分再从余额划走,明细在余额变动里,备注以 OSS 开头
- 余额须 ≥ ¥100.00,否则停用签发与
url,并把已有 public 改为私有;持续低于该金额满 7 天,自动删除已上传文件
典型流程
| 步骤 | Body 示例 |
|---|---|
| 1. 签发 | {"action":"sign","key":"photos/a.jpg","filename":"a.jpg","mime":"image/jpeg","size":123456} |
| 2. 直传 | 对返回的 upload_url 发 PUT,Header 带返回的 Content-Type,Body 为文件二进制 |
| 3. 确认 | {"action":"confirm","file_id":"of_xxx"} |
| 取访问地址 | {"action":"url","key":"photos/a.jpg","expire":3600} |
| 列表 / 用量 | {"action":"list","prefix":"photos/"} {"action":"usage"} |
| 删除 | {"action":"delete","file_id":"of_xxx"} |
每次都返回同一套 JSON:ret / code / errmsg / data。业务值全在 data 里,例如签发取 data.upload_url,访问取 data.url。
{
"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 分钟后自动删除
- 个人中心「我的文件」也是浏览器直传,点打开会按下行计费
返回说明
| 字段 | 说明 |
|---|---|
ret | ok 成功,err 失败 |
data.file_id / data.key | 文件 ID 与你传入的对象路径。取值:json.data.file_id |
data.url / data.url_expire | url 返回限时 GET 地址(秒)。取值:json.data.url。confirm/info 仅 public 才带固定链接 |
data.upload_url / data.headers | sign 返回的 PUT 专用地址,不能当下载链接打开;PUT 时必须带返回的 Content-Type |
data.size / data.mime / data.acl / data.status | 字节数、MIME、private/public、active |
data.files | list 时的文件数组 |
data.bytes_used / data.max_bytes | usage / 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}}