upload-and-share

通过 StableUpload 上传和分享

通过 x402 微支付将任意本地文件上传到由 S3 提供支持的云存储。返回一个公开 URL。无需 API 密钥。

设置

安装和钱包设置请参阅 rules/getting-started.md。

快速参考

等级	最大大小	保留期限	费用
10mb	10 MB	6 个月	$0.02
100mb	100 MB	6 个月	$0.20
1gb	1 GB	6 个月	$2.00
short-10mb	10 MB	7 天	$0.005
short-100mb	100 MB	7 天	$0.02
short-1gb	1 GB	7 天	$0.10
short-5gb	5 GB	7 天	$0.50

默认等级在 6 个月后过期；short-* 等级在 7 天后过期。short-5gb 仅用于文件上传（不适用于网站）。

任务	端点	价格
购买上传名额	https://stableupload.dev/api/upload	按等级计价
列出上传内容	GET https://stableupload.dev/api/uploads	免费（需认证）
获取上传详情	GET https://stableupload.dev/api/download/:uploadId	免费（需认证）
购买网站名额	https://stableupload.dev/api/site	按等级计价
激活网站	POST https://stableupload.dev/api/site/activate	免费（需认证）
更新网站	PUT https://stableupload.dev/api/site	免费（需认证）
续订网站	https://stableupload.dev/api/site/renew	按等级计价
预览域名 DNS	GET https://stableupload.dev/api/site/domain/preview?hostname=...	免费（无需认证）
绑定域名	POST https://stableupload.dev/api/site/domain	免费（需认证）
解绑域名	DELETE https://stableupload.dev/api/site/domain	免费（需认证）
域名状态	GET https://stableupload.dev/api/site/domain/status?uploadId=...	免费（需认证）

工作流

1. 检查钱包余额

npx agentcash@latest balance

确保所选等级的 USDC 余额充足。 如果余额不足且用户需要充值详情，请运行 npx agentcash@latest accounts 获取存款链接和钱包地址。

2. 确定等级

选择能容纳文件的最小等级。先使用 ls -la 或 wc -c 检查文件大小。如果文件只需保留 7 天，请使用 short-* 等级——其费用仅为 6 个月等级的一小部分。

等级	最大大小	保留期限	费用
10mb	10 MB	6 个月	$0.02
100mb	100 MB	6 个月	$0.20
1gb	1 GB	6 个月	$2.00
short-10mb	10 MB	7 天	$0.005
short-100mb	100 MB	7 天	$0.02
short-1gb	1 GB	7 天	$0.10
short-5gb	5 GB	7 天	$0.50

3. 购买上传名额

npx agentcash@latest fetch https://stableupload.dev/api/upload -m POST -b '{"filename": "report.pdf", "contentType": "application/pdf", "tier": "10mb"}'

参数：

• filename — 上传文件的名称（必填）
• contentType — MIME 类型（必填，供浏览器参考）
• tier — "10mb"、"100mb"、"1gb"、"short-10mb"、"short-100mb"、"short-1gb" 或 "short-5gb"（必填）
• policyTtlSeconds — 可选的上传 URL 有效期（秒），范围为 60–86400；仅在为下游服务预留输出名额时使用较长的有效期

响应：

{
  "uploadId": "k7gm3nqp2",
  "uploadUrl": "https://f.stableupload.dev/k7gm3nqp2/report.pdf?t=...",
  "uploadMethod": "put",
  "uploadUrlExpiresAt": "2026-08-19T01:00:00.000Z",
  "publicUrl": "https://f.stableupload.dev/k7gm3nqp2/report.pdf",
  "expiresAt": "2027-02-19T00:00:00.000Z",
  "maxSize": 10485760,
  "curlExample": "curl -X PUT ..."
}

4. 使用 curl 上传文件

使用 Bash 将文件 PUT 到返回的 uploadUrl：

curl -s -X PUT "<uploadUrl>" -H "Content-Type: <mime>" --data-binary @/absolute/path/to/file

重要： 使用 --data-binary（而非 -d）以保留二进制内容。请使用绝对路径。

响应中包含现成的 curlExample。如果 uploadMethod 为 "post"，请使用 postFields 将多部分表单上传到 postUrl，而不是执行 PUT。

5. 分享公开 URL

向用户提供 publicUrl。该 URL 会立即公开访问，并在该等级的保留期限内保持有效（默认等级为 6 个月，short-* 等级为 7 天）——请参阅 expiresAt。

常见 MIME 类型

文件类型	内容类型
PDF	application/pdf
PNG 图片	image/png
JPEG 图片	image/jpeg
CSV	text/csv
JSON	application/json
纯文本	text/plain
ZIP 压缩包	application/zip
Excel	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
未知	application/octet-stream

列出之前上传的文件

列出当前钱包的上传文件：

npx agentcash@latest fetch https://stableupload.dev/api/uploads

获取上传详情

npx agentcash@latest fetch https://stableupload.dev/api/download/k7gm3nqp2

重要详情

• 无需 API 密钥——付款即为身份验证
• 上传 URL 会过期——请查看响应中的 uploadUrlExpiresAt；尽快上传，或在购买时设置 policyTtlSeconds（60–86400）以延长有效期
• 公共 URL 的有效期为购买日期起对应套餐的保留期限——默认套餐为 6 个月，short-* 套餐为 7 天
• 接受任何文件类型——contentType 仅供浏览器参考，不构成限制
• 基于 S3——文件存储在具有公共读取权限的 AWS S3 上
• 发现端点：如果需要验证端点，请运行 npx agentcash@latest discover https://stableupload.dev

常见模式

上传用户刚创建的文件： 跳过发现步骤，直接检查钱包 + 购买存储槽位 + 上传。

上传多个文件： 为每个文件单独购买槽位。可以并行购买槽位，但上传时必须为每个文件使用对应的 uploadUrl。

用户要求“分享”或“发送”文件： 上传文件并提供公共 URL。该 URL 可在任何地方分享。

为电子邮件托管图片： 上传图片，然后在电子邮件 HTML 中引用 publicUrl：

<img src="https://f.stableupload.dev/abc/photo.png" alt="Photo" />

静态网站托管

使用自定义域名和自动 HTTPS 托管静态网站（HTML/CSS/JS）。

部署网站

1. 购买网站槽位（付费，按套餐计费）：

npx agentcash@latest fetch https://stableupload.dev/api/site -m POST -b '{"filename": "my-site.zip", "tier": "100mb"}'

返回 {uploadId, uploadUrl}。

2. 上传 ZIP 文件：

curl -X PUT "$uploadUrl" -H "Content-Type: application/zip" --data-binary @site.zip

3. 激活网站（SIWX，免费）：

npx agentcash@latest fetch https://stableupload.dev/api/site/activate -m POST -b '{"uploadId": "..."}'

返回 {siteUrl, fileCount, files}。网站将在 https://{uploadId}.s.stableupload.dev/ 上线。

更新现有网站

免费更新：调用 PUT /api/site 获取新的上传 URL，上传新的 ZIP 文件，然后激活。

npx agentcash@latest fetch https://stableupload.dev/api/site -m PUT -b '{"uploadId": "...", "filename": "my-site.zip"}'

然后上传新的 ZIP 文件，并再次调用激活接口。

自定义域名

1. 预览所需的 DNS 记录（免费，无需身份验证）：

npx agentcash@latest fetch "https://stableupload.dev/api/site/domain/preview?hostname=www.example.com"

返回 {hostname, dnsRecords}。在绑定域名之前设置这些 DNS 记录，即可立即启用 SSL。

2. 绑定域名：

npx agentcash@latest fetch https://stableupload.dev/api/site/domain -m POST -b '{"uploadId": "...", "hostname": "www.example.com"}'

创建 TLS 证书并路由该主机名。检查状态：

npx agentcash@latest fetch "https://stableupload.dev/api/site/domain/status?uploadId=..."

轮询，直到 ssl 为 "active"。

解绑域名：

npx agentcash@latest fetch https://stableupload.dev/api/site/domain -m DELETE -b '{"uploadId": "...", "hostname": "www.example.com"}'

续期网站

npx agentcash@latest fetch https://stableupload.dev/api/site/renew -m POST -b '{"uploadId": "...", "count": 4}'

按原套餐的保留期限乘以 count 延长网站有效期（例如，默认套餐为 4 x 6 个月）。价格 = 套餐价格 x count（$0.005–$20.00）。

说明

• 每个网站最多 500 个文件
• 套餐限制适用于未压缩大小
• 网站支持除 short-5gb 以外的所有套餐；POST /api/site 仅接受 filename 和 tier（不接受 contentType）
• 自定义域名通过 Cloudflare 自动启用 HTTPS

错误处理

• 余额不足：运行 npx agentcash@latest accounts 以显示充值链接和钱包地址
• 文件超出套餐限制：建议升级到更高一级的套餐
• 上传 URL 已过期：购买新的槽位（之前的付款不予退款）
• curl 失败：确认文件路径存在，并且 uploadUrl 已正确加引号