让 Agent 直接传文件。

无需登录或 API Key。使用普通 HTTP 上传、取得取件码和分享链接，再交给接收者下载。

纯文本 Agent 说明OpenAPI 规范当前可用空间

上传一个文件

请求正文是文件原始字节，不是表单、JSON 或 Base64。文件名放在 URL 参数中并进行 URL 编码；必须提供准确的 Content-Length。

只提供文件名，不提供目录路径。文件名不能为空白、. 或 ..，不能包含斜杠、反斜杠和控制字符，UTF-8 长度不超过 240 字节。

curl --fail-with-body --request POST \
  --header "Content-Type: application/octet-stream" \
  --data-binary "@./my file.zip" \
  "https://drop.rosebeg.com/api/files?filename=my%20file.zip&ttl=3600"

该写法读取本地常规文件，curl 会自动设置文件长度。不要使用未知长度的管道输入。一次上传一个非空文件。

保存时间ttl（秒）
30 分钟1800
1 小时（默认）3600
12 小时43200
24 小时86400

保存时间从上传成功完成开始计算。单文件上限 300 MB（300,000,000 字节），服务总容量 1 GB（1,000,000,000 字节）。正在上传的文件会预留空间，容量不足时拒绝新的上传。

读取上传结果

成功返回 201 和 JSON：

{
  "id": "<secret-file-id>",
  "code": "0123",
  "name": "my file.zip",
  "size": 1024,
  "createdAt": "<ISO-8601 timestamp>",
  "expiresAt": "<ISO-8601 timestamp>",
  "shareUrl": "https://drop.rosebeg.com/f/<secret-file-id>",
  "downloadUrl": "https://drop.rosebeg.com/api/files/<secret-file-id>/download"
}

shareUrl 打开下载页面，downloadUrl 直接下载文件。将分享链接、四位取件码和到期时间发给用户。取件码须保留前导零；到期时间以返回的 expiresAt 为准。

使用 Python，无需第三方依赖

import http.client, json, pathlib, urllib.parse

path = pathlib.Path("my file.zip")
query = urllib.parse.urlencode({"filename": path.name, "ttl": 3600})
connection = http.client.HTTPSConnection("drop.rosebeg.com", timeout=90)
try:
    connection.putrequest("POST", "/api/files?" + query)
    connection.putheader("Content-Type", "application/octet-stream")
    connection.putheader("Content-Length", str(path.stat().st_size))
    connection.endheaders()
    with path.open("rb") as file:
        while chunk := file.read(1024 * 1024):
            connection.send(chunk)
    response = connection.getresponse()
    result = json.loads(response.read())
    if response.status != 201:
        raise RuntimeError(result)
    print(json.dumps(result, ensure_ascii=False, indent=2))
finally:
    connection.close()

取件与断点续传

curl --fail-with-body \
  --header "Content-Type: application/json" \
  --data '{"code":"0123"}' \
  "https://drop.rosebeg.com/api/resolve"

成功响应同样包含文件信息和两个链接。已知文件 ID 时可通过 GET /api/files/{id} 获取信息。

curl --fail --location --continue-at - \
  --output "my file.zip" \
  "https://drop.rosebeg.com/api/files/REPLACE_WITH_RETURNED_ID/download"

下载接口支持 GET、HEAD、单段 Range、ETag 和 If-Range。部分下载返回 206 和 Content-Range。到期后新的下载和续传请求都会被拒绝，尚未完成的传输也会停止，文件会自动清除并释放空间。

错误与重试

JSON 错误格式：{"error":{"code":"MACHINE_CODE","message":"说明"}}。416 返回空正文和 Content-Range；HEAD 响应不含正文。

状态含义
400请求、文件名、空文件、保存时间或取件码不合法。
404 / 410文件不存在或已经到期，停止下载。
411缺少准确的文件长度。
413文件超过 300 MB。
416下载字节范围无效或超出文件。
429请求过于频繁，遵循 Retry-After。
503服务暂时不可用、正在重启或临时取件码已用完。
507剩余容量不足，等待空间释放或减小文件。

网络中断后，上传结果可能不明确。不要立即重复上传，以免生成多份文件。上传前查询容量只是参考，最终以上传接口的空间预留结果为准。

Agent 使用约定