认证
StarDots 通过读取客户端发起的 http 请求中的 headers 字段,对相关字段进行验证来完成鉴权,因此所有的开放 API 请求都应该携带这些鉴权字段信息,并且需要注意这些字段区分大小写,所有字段都应该小写。
| 名称 | 描述 |
|---|---|
x-stardots-timestamp | 当前时间戳(秒)。与 StarDots 服务器的差异不能超过 60 秒。注意:StarDots 的时区为 Asia/Singapore,即 UTC+8。 |
x-stardots-nonce | 4~20个字符的随机字符串,只能包含大写字母、小写字母和数字,注意此值在60秒内必须是唯一的。 |
x-stardots-key | StarDots发布的key信息。 |
x-stardots-sign | 签名字段是将以上字段按照一定的签名算法组合生成的字符串,具体的签名算法接下来会介绍。 |
x-stardots-timestamp- 描述
- 当前时间戳(秒)。与 StarDots 服务器的差异不能超过 60 秒。注意:StarDots 的时区为 Asia/Singapore,即 UTC+8。
x-stardots-nonce- 描述
- 4~20个字符的随机字符串,只能包含大写字母、小写字母和数字,注意此值在60秒内必须是唯一的。
x-stardots-key- 描述
- StarDots发布的key信息。
x-stardots-sign- 描述
- 签名字段是将以上字段按照一定的签名算法组合生成的字符串,具体的签名算法接下来会介绍。
签名算法
我们假设以下字段值
key2dcded8e-f231-4d0a-8498-d10ef0639eb3secretEy1JNRCiJOzaIOIilcyJvteTn5YXykFXUwmiHLymK8LHkITfGPo5mTUdLlg0jPHST9fMwMZKxIKUBvSsT5uxrq0lXuerll3eRW2tbMOsvySRY539L8cR6iRFV2DQqdlzbseyq7k9N0U5pZgj6f43e3MngbIttgSDl1G44IBOwqsI2HVXE5H6mf1bHlvWw6Ziuk8Xcw18AioG47SFBLIatrq6E9yEBJgFgcYysCH8JvY659hhqI3Ii1CA5zVtyNpx-stardots-timestamp1728958751x-stardots-noncefQvDmMLnKEx-stardots-key2dcded8e-f231-4d0a-8498-d10ef0639eb3
然后我们组装上述字段值
needSignStr = x-stardots-timestamp + "|" + secret + "|" + x-stardots-nonce接下来,我们计算上面组装的字符串的 MD5 摘要
signStrAfterMD5 = md5("1728958751|Ey1JNRCiJOzaIOIilcyJvteTn5YXykFXUwmiHLymK8LHkITfGPo5mTUdLlg0jPHST9fMwMZKxIKUBvSsT5uxrq0lXuerll3eRW2tbMOsvySRY539L8cR6iRFV2DQqdlzbseyq7k9N0U5pZgj6f43e3MngbIttgSDl1G44IBOwqsI2HVXE5H6mf1bHlvWw6Ziuk8Xcw18AioG47SFBLIatrq6E9yEBJgFgcYysCH8JvY659hhqI3Ii1CA5zVtyNp|fQvDmMLnKE")
signStrAfterMD5 = "51dabfe4b47e73d4a3b85fe29c4f1e82"最后我们将摘要字符串转换为大写
sign = signStrAfterMD5.toUpperCase()
sign = "51DABFE4B47E73D4A3B85FE29C4F1E82"因此,x-stardots-sign 字段的最终值为 51DABFE4B47E73D4A3B85FE29C4F1E82
通用的HTTP响应主体
所有接口响应都保持统一的数据结构
| 名称 | 数据类型 | 是否必须 | 描述 |
|---|---|---|---|
code | number | 是 | 服务响应代码。200 表示成功。 |
message | string | 是 | 操作结果的消息提示。 |
requestId | string | 是 | 请求的唯一编号,可用于故障排除。 |
success | boolean | 是 | 业务操作是否成功。 |
ts | number | 是 | 服务器毫秒时间戳。 |
data | any | 是 | 业务数据字段,该字段可以为任意数据类型,具体数据类型请参考对应接口。 |
code- 数据类型
number- 是否必须
- 是
- 描述
- 服务响应代码。200 表示成功。
message- 数据类型
string- 是否必须
- 是
- 描述
- 操作结果的消息提示。
requestId- 数据类型
string- 是否必须
- 是
- 描述
- 请求的唯一编号,可用于故障排除。
success- 数据类型
boolean- 是否必须
- 是
- 描述
- 业务操作是否成功。
ts- 数据类型
number- 是否必须
- 是
- 描述
- 服务器毫秒时间戳。
data- 数据类型
any- 是否必须
- 是
- 描述
- 业务数据字段,该字段可以为任意数据类型,具体数据类型请参考对应接口。
功能接口
注意所有接口都会有请求速率限制,所有接口共用一套速率限制规则。目前,StarDots 的速率限制为每分钟 300 次。
请求端点
https://api.stardots.io空间列表
获取空间列表数据。
- 请求方法
GET- 请求路径
/openapi/space/list- 请求的内容类型
application/json- 响应内容类型
application/json
请求参数
| 名称 | 数据类型 | 是否必须 | 描述 |
|---|---|---|---|
page | number | 否 | 页码,默认值为1。 |
pageSize | number | 否 | 每页显示条数,范围为1至100,默认值为20。 |
page- 数据类型
number- 是否必须
- 否
- 描述
- 页码,默认值为1。
pageSize- 数据类型
number- 是否必须
- 否
- 描述
- 每页显示条数,范围为1至100,默认值为20。
请求示例
/openapi/space/list?page=1&pageSize=50响应字段
| 名称 | 数据类型 | 是否必须 | 描述 |
|---|---|---|---|
name | string | 是 | 空间名称 |
public | boolean | 是 | 空间的可访问性是否为公开。 |
createdAt | number | 是 | 空间创建时的系统时间戳(以秒为单位)。时区为 UTC+8。 |
fileCount | number | 是 | 空间内的文件数量。 |
name- 数据类型
string- 是否必须
- 是
- 描述
- 空间名称
public- 数据类型
boolean- 是否必须
- 是
- 描述
- 空间的可访问性是否为公开。
createdAt- 数据类型
number- 是否必须
- 是
- 描述
- 空间创建时的系统时间戳(以秒为单位)。时区为 UTC+8。
fileCount- 数据类型
number- 是否必须
- 是
- 描述
- 空间内的文件数量。
响应示例
{
"code": 200,
"data": [
{
"createdAt": 1723789637,
"fileCount": 2,
"name": "star",
"public": true
}
],
"message": "SUCCESS",
"requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
"success": true,
"ts": 1670899688591
}创建空间
创建新的空间。
- 请求方法
PUT- 请求路径
/openapi/space/create- 请求内容类型
application/json- 响应内容类型
application/json
请求参数
| 名称 | 数据类型 | 是否必须 | 描述 |
|---|---|---|---|
space | string | 是 | 空间名称,只能为字母或数字组合,长度为4~15个字符。 |
public | boolean | 否 | 指定空间是否可公开访问。默认值为false。 |
space- 数据类型
string- 是否必须
- 是
- 描述
- 空间名称,只能为字母或数字组合,长度为4~15个字符。
public- 数据类型
boolean- 是否必须
- 否
- 描述
- 指定空间是否可公开访问。默认值为false。
请求示例
{
"public": false,
"space": "stardots"
}响应字段
无字段
响应示例
{
"code": 200,
"data": null,
"message": "SUCCESS",
"requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
"success": true,
"ts": 1670899688591
}删除空间
删除一个已有的空间,注意必须保证该空间中没有文件,否则删除会失败。
- 请求方法
DELETE- 请求路径
/openapi/space/delete- 请求内容类型
application/json- 响应内容类型
application/json
请求参数
| 名称 | 数据类型 | 是否必须 | 描述 |
|---|---|---|---|
space | string | 是 | 空间名称,只能为字母或数字组合,长度为4~15个字符。 |
space- 数据类型
string- 是否必须
- 是
- 描述
- 空间名称,只能为字母或数字组合,长度为4~15个字符。
请求示例
{
"space": "stardots"
}响应字段
无字段
响应示例
{
"code": 200,
"data": null,
"message": "SUCCESS",
"requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
"success": true,
"ts": 1670899688591
}空间可访问性
切换空间的可访问性。
- 请求方法
POST- 请求路径
/openapi/space/accessibility/toggle- 请求内容类型
application/json- 响应内容类型
application/json
请求参数
| 名称 | 数据类型 | 是否必须 | 描述 |
|---|---|---|---|
space | string | 是 | 空间名称,只能为字母或数字组合,长度为4~15个字符。 |
public | boolean | 否 | 指定空间是否可公开访问。默认值为false。 |
space- 数据类型
string- 是否必须
- 是
- 描述
- 空间名称,只能为字母或数字组合,长度为4~15个字符。
public- 数据类型
boolean- 是否必须
- 否
- 描述
- 指定空间是否可公开访问。默认值为false。
请求示例
{
"public": false,
"space": "stardots"
}响应字段
无字段
响应示例
{
"code": 200,
"data": null,
"message": "SUCCESS",
"requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
"success": true,
"ts": 1670899688591
}空间内的文件列表
获取空间内文件列表,列表按照文件上传时间降序排列。
- 请求方法
GET- 请求路径
/openapi/file/list- 请求内容类型
application/json- 响应内容类型
application/json
请求参数
| 名称 | 数据类型 | 是否必须 | 描述 |
|---|---|---|---|
space | string | 是 | 空间名称,只能为字母或数字组合,长度为4~15个字符。 |
page | number | 否 | 页码,默认值为1。 |
pageSize | number | 否 | 每页显示条数范围为1至100,默认值为20。 |
space- 数据类型
string- 是否必须
- 是
- 描述
- 空间名称,只能为字母或数字组合,长度为4~15个字符。
page- 数据类型
number- 是否必须
- 否
- 描述
- 页码,默认值为1。
pageSize- 数据类型
number- 是否必须
- 否
- 描述
- 每页显示条数范围为1至100,默认值为20。
请求示例
{
"space": "stardots",
"page": 1,
"pageSize": 20
}响应字段
| 名称 | 数据类型 | 是否必须 | 描述 |
|---|---|---|---|
page | number | 是 | 页码,默认值为1。 |
pageSize | number | 是 | 每页显示条数范围为1至100,默认值为20。 |
totalCount | number | 是 | 总的文件数量。 |
list | array<object> | 是 | 文件列表数组。 |
list.name | string | 是 | 文件名称 |
list.byteSize | number | 是 | 文件的字节大小。 |
list.size | string | 是 | 文件大小,已格式化以便于阅读。 |
list.uploadedAt | number | 是 | 文件上传的时间戳(以秒为单位)。时区为 UTC+8。 |
list.url | string | 是 | 文件的访问地址,注意如果该空间的可访问性为private,则该字段值会携带访问票据,有效期为20秒。 |
page- 数据类型
number- 是否必须
- 是
- 描述
- 页码,默认值为1。
pageSize- 数据类型
number- 是否必须
- 是
- 描述
- 每页显示条数范围为1至100,默认值为20。
totalCount- 数据类型
number- 是否必须
- 是
- 描述
- 总的文件数量。
list- 数据类型
array<object>- 是否必须
- 是
- 描述
- 文件列表数组。
list.name- 数据类型
string- 是否必须
- 是
- 描述
- 文件名称
list.byteSize- 数据类型
number- 是否必须
- 是
- 描述
- 文件的字节大小。
list.size- 数据类型
string- 是否必须
- 是
- 描述
- 文件大小,已格式化以便于阅读。
list.uploadedAt- 数据类型
number- 是否必须
- 是
- 描述
- 文件上传的时间戳(以秒为单位)。时区为 UTC+8。
list.url- 数据类型
string- 是否必须
- 是
- 描述
- 文件的访问地址,注意如果该空间的可访问性为private,则该字段值会携带访问票据,有效期为20秒。
响应示例
{
"code": 0,
"data": {
"list": [
{
"byteSize": 3600000,
"name": "star",
"size": "35KB",
"uploadedAt": 1723789637,
"url": "https://....."
}
],
"page": 1,
"pageSize": 10,
"totalCount": 1
},
"message": "SUCCESS",
"requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
"success": true,
"ts": 1670899688591
}文件临时访问票据
获取文件的访问票,当空间的可访问性为私密时,需要携带访问票才能访问该空间下的文件,否则请求将被拒绝。
- 请求方法
POST- 请求路径
/openapi/file/ticket- 请求内容类型
application/json- 响应内容类型
application/json
请求参数
| 名称 | 数据类型 | 是否必须 | 描述 |
|---|---|---|---|
space | string | 是 | 空间名称,只能为字母或数字组合,长度为4~15个字符。 |
filename | string | 是 | 文件的名称,不超过170个字符。 |
space- 数据类型
string- 是否必须
- 是
- 描述
- 空间名称,只能为字母或数字组合,长度为4~15个字符。
filename- 数据类型
string- 是否必须
- 是
- 描述
- 文件的名称,不超过170个字符。
请求示例
{
"filename": "1.jpg",
"space": "stardots"
}响应内容
| 名称 | 数据类型 | 是否必须 | 描述 |
|---|---|---|---|
ticket | string | 是 | 临时访问票据 |
ticket- 数据类型
string- 是否必须
- 是
- 描述
- 临时访问票据
响应示例
{
"code": 200,
"data": {
"ticket": "a312.."
},
"message": "SUCCESS",
"requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
"success": true,
"ts": 1670899688591
}文件上传
将文件上传到空间。注意,此请求需要你以表单的形式发起请求。
- 请求方法
PUT- 请求路径
/openapi/file/upload- 请求内容类型
multipart/form-data- 响应内容类型
application/json
请求参数
| 名称 | 数据类型 | 是否必须 | 描述 |
|---|---|---|---|
space | string | 是 | 空间名称,只能为字母或数字组合,长度为4~15个字符。 |
file | binary | 是 | 文件的二进制流。注意,文件名称不得超过170个字符。文件大小不能超过10MB。 |
space- 数据类型
string- 是否必须
- 是
- 描述
- 空间名称,只能为字母或数字组合,长度为4~15个字符。
file- 数据类型
binary- 是否必须
- 是
- 描述
- 文件的二进制流。注意,文件名称不得超过170个字符。文件大小不能超过10MB。
响应字段
| 名称 | 数据类型 | 是否必须 | 描述 |
|---|---|---|---|
space | string | 是 | 空间名称,只能为字母或数字组合,长度为4~15个字符。 |
filename | string | 是 | 文件的名称。 |
url | string | 是 | 文件的访问链接,如果空间的可访问性为私密,则访问链接会携带访问票。 |
space- 数据类型
string- 是否必须
- 是
- 描述
- 空间名称,只能为字母或数字组合,长度为4~15个字符。
filename- 数据类型
string- 是否必须
- 是
- 描述
- 文件的名称。
url- 数据类型
string- 是否必须
- 是
- 描述
- 文件的访问链接,如果空间的可访问性为私密,则访问链接会携带访问票。
响应示例
{
"code": 200,
"data": {
"filename": "1.png",
"space": "space",
"url": "https://i.stardots.io/space/1.png"
},
"message": "SUCCESS",
"requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
"success": true,
"ts": 1670899688591
}删除文件
删除空间内的文件。此接口支持批量操作。
- 请求方法
DELETE- 请求路径
/openapi/file/delete- 请求内容类型
application/json- 响应内容类型
application/json
请求参数
| 名称 | 数据类型 | 是否必须 | 描述 |
|---|---|---|---|
space | string | 是 | 空间名称,只能为字母或数字组合,长度为4~15个字符。 |
filenameList | array<string> | 是 | 文件名称字符串数组。 |
space- 数据类型
string- 是否必须
- 是
- 描述
- 空间名称,只能为字母或数字组合,长度为4~15个字符。
filenameList- 数据类型
array<string>- 是否必须
- 是
- 描述
- 文件名称字符串数组。
请求示例
{
"filenameList": ["1.jpg", "2.jpg"],
"space": "stardots"
}响应字段
无字段
响应示例
{
"code": 0,
"data": null,
"message": "SUCCESS",
"requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
"success": true,
"ts": 1670899688591
}服务器响应代码
服务器响应代码是服务器返回给客户端的响应代码,用于表示服务器处理请求的结果。
| 代码 | 描述 |
|---|---|
200 | 成功 |
504 | 请求超时 |
999999 | 服务器内部错误 |
100000 | 请求参数错误 |
100001 | 访问凭证失效 |
100002 | 人机验证不通过 |
100003 | 验证码不正确 |
100004 | 账号不存在 |
100005 | 账号密码不匹配 |
100006 | 订阅计划不存在 |
100007 | 短信/邮件发送过于频繁 |
100008 | 短信/邮件发送次数超出限制 |
100009 | 空间/存储桶不存在 |
100010 | 空间/存储桶已存在 |
100011 | 空间/存储桶不为空 |
100012 | 操作过于频繁 |
100013 | 空间/存储桶数量配额已达到数量上限 |
100014 | 文件数量配额已达到数量上限 |
100015 | 流量传输配额已耗尽 |
100016 | 订阅计划不匹配 |
100017 | 空间/存储桶文件访问受限 |
100018 | 文件超出大小限制 |
100019 | 文件格式不受支持 |
100020 | Referer不允许 |
100021 | 功能仅对Pro或Premium用户开放 |
100022 | 功能仅对Premium用户开放 |
100023 | 证书内容无效 |
100024 | 证书和私钥不匹配 |
100025 | 无效的图像MIME类型 |
100026 | 文件访问链接已失效 |
100027 | API调用次数已达到上限 |
100028 | 批量操作仅对付费用户开放 |
100029 | 图像链接无效 |
100030 | 账号涉嫌违规,已被禁止登录 |
200- 描述
- 成功
504- 描述
- 请求超时
999999- 描述
- 服务器内部错误
100000- 描述
- 请求参数错误
100001- 描述
- 访问凭证失效
100002- 描述
- 人机验证不通过
100003- 描述
- 验证码不正确
100004- 描述
- 账号不存在
100005- 描述
- 账号密码不匹配
100006- 描述
- 订阅计划不存在
100007- 描述
- 短信/邮件发送过于频繁
100008- 描述
- 短信/邮件发送次数超出限制
100009- 描述
- 空间/存储桶不存在
100010- 描述
- 空间/存储桶已存在
100011- 描述
- 空间/存储桶不为空
100012- 描述
- 操作过于频繁
100013- 描述
- 空间/存储桶数量配额已达到数量上限
100014- 描述
- 文件数量配额已达到数量上限
100015- 描述
- 流量传输配额已耗尽
100016- 描述
- 订阅计划不匹配
100017- 描述
- 空间/存储桶文件访问受限
100018- 描述
- 文件超出大小限制
100019- 描述
- 文件格式不受支持
100020- 描述
- Referer不允许
100021- 描述
- 功能仅对Pro或Premium用户开放
100022- 描述
- 功能仅对Premium用户开放
100023- 描述
- 证书内容无效
100024- 描述
- 证书和私钥不匹配
100025- 描述
- 无效的图像MIME类型
100026- 描述
- 文件访问链接已失效
100027- 描述
- API调用次数已达到上限
100028- 描述
- 批量操作仅对付费用户开放
100029- 描述
- 图像链接无效
100030- 描述
- 账号涉嫌违规,已被禁止登录
SDK
StarDots 为各种编程语言提供了 SDK,以帮助您快速集成我们的 API。您可以在以下链接中找到 SDK:
GoJavaC#PythonTypescriptC++RustPHPRubyVSwiftKotlinDart