upload-and-share

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Upload and Share via StableUpload

借助StableUpload上传并分享文件

Upload any local file to S3-backed cloud storage via x402 micropayments. Returns a public URL. No API keys needed.

通过x402微支付将任意本地文件上传至基于S3的云存储，返回一个公共URL，无需API密钥。

Setup

设置

See rules/getting-started.md for installation and wallet setup.

如需了解安装和钱包设置，请查看rules/getting-started.md。

Quick Reference

快速参考

Tier	Max Size	Cost
`10mb`	10 MB	$0.02
`100mb`	100 MB	$0.20
`1gb`	1 GB	$2.00

All uploads expire after 6 months.

Task	Endpoint	Price
Buy upload slot	`https://stableupload.dev/api/upload`	Tier-based
List uploads	`GET https://stableupload.dev/api/uploads`	Free (auth)
Get upload details	`GET https://stableupload.dev/api/download/:uploadId`	Free (auth)

套餐	最大文件大小	费用
`10mb`	10 MB	$0.02
`100mb`	100 MB	$0.20
`1gb`	1 GB	$2.00

所有上传的文件将在6个月后过期。

任务	接口	价格
购买上传额度	`https://stableupload.dev/api/upload`	按套餐计费
查看历史上传记录	`GET https://stableupload.dev/api/uploads`	免费（需验证）
获取上传详情	`GET https://stableupload.dev/api/download/:uploadId`	免费（需验证）

Workflow

操作流程

1. Check wallet balance

1. 检查钱包余额

bash

npx agentcash wallet info

Ensure sufficient USDC balance for the chosen tier. If balance is low, show the deposit link.

bash

npx agentcash wallet info

确保钱包中有足够的USDC余额用于所选套餐。如果余额不足，请显示充值链接。

2. Determine the tier

2. 选择合适的套餐

Pick the smallest tier that fits the file. Check file size first with

ls -la

wc -c

Tier	Max Size	Cost
`10mb`	10 MB	$0.02
`100mb`	100 MB	$0.20
`1gb`	1 GB	$2.00

选择能容纳文件的最小套餐。先使用

ls -la

或

wc -c

检查文件大小。

套餐	最大文件大小	费用
`10mb`	10 MB	$0.02
`100mb`	100 MB	$0.20
`1gb`	1 GB	$2.00

3. Buy the upload slot

3. 购买上传额度

bash

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

Parameters:

```
filename
```
— name for the uploaded file (required)
```
contentType
```
— MIME type (required, advisory for browser)
```
tier
```
—
```
"10mb"
```
,
```
"100mb"
```
, or
```
"1gb"
```
(required)

Response:

json

{
  "uploadId": "k7gm3nqp2",
  "uploadUrl": "https://f.stableupload.dev/k7gm3nqp2/report.pdf?t=...",
  "publicUrl": "https://f.stableupload.dev/k7gm3nqp2/report.pdf",
  "expiresAt": "2026-08-19T00:00:00.000Z",
  "maxSize": 10485760
}

bash

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

参数说明：

```
filename
```
— 上传文件的名称（必填）
```
contentType
```
— MIME类型（必填，供浏览器识别参考）
```
tier
```
—
```
"10mb"
```
、
```
"100mb"
```
或
```
"1gb"
```
（必填）

响应示例：

json

{
  "uploadId": "k7gm3nqp2",
  "uploadUrl": "https://f.stableupload.dev/k7gm3nqp2/report.pdf?t=...",
  "publicUrl": "https://f.stableupload.dev/k7gm3nqp2/report.pdf",
  "expiresAt": "2026-08-19T00:00:00.000Z",
  "maxSize": 10485760
}

4. Upload the file via curl

4. 通过curl上传文件

Use Bash to PUT the file to the returned

uploadUrl

bash

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

Critical: Use

--data-binary

(not

-d

) to preserve binary content. Use the absolute path.

使用Bash将文件PUT到返回的

uploadUrl

：

bash

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

注意事项： 使用

--data-binary

（而非

-d

）以保留二进制内容。请使用文件的绝对路径。

5. Share the public URL

5. 分享公共URL

Present the

publicUrl

to the user. This URL is publicly accessible immediately and remains live for 6 months.

将

publicUrl

提供给用户。该URL可立即公开访问，且有效期为6个月。

Common MIME Types

常见MIME类型

File Type	Content Type
PDF	`application/pdf`
PNG image	`image/png`
JPEG image	`image/jpeg`
CSV	`text/csv`
JSON	`application/json`
Plain text	`text/plain`
ZIP archive	`application/zip`
Excel	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
Unknown	`application/octet-stream`

文件类型	内容类型
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`

Listing Previous Uploads

查看历史上传记录

To list uploads for the current wallet:

bash

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

要查看当前钱包下的所有上传记录：

bash

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

Get Upload Details

获取上传详情

bash

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

bash

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

Key Details

关键说明

No API keys required — payment is the authentication
Upload URLs expire in 1 hour — upload promptly after buying the slot
Public URLs last 6 months from purchase date
Any file type accepted — contentType is advisory for the browser, not a restriction
S3-backed — files stored on AWS S3 with public read access
Discovery endpoint:
```
npx agentcash discover https://stableupload.dev
```
if you need to verify endpoints

无需API密钥 — 支付即为验证方式
上传URL有效期1小时 — 购买额度后请及时上传文件
公共URL有效期6个月 — 从购买日期开始计算
支持任意文件类型 — contentType仅为浏览器识别参考，并非限制条件
基于S3存储 — 文件存储在AWS S3中，支持公共读取权限
发现接口：如果需要验证接口，可使用
```
npx agentcash discover https://stableupload.dev
```

Common Patterns

常见使用场景

Upload a file the user just created: Skip discovery, go straight to wallet check + buy slot + upload.

Upload multiple files: Buy separate slots for each file. Slots can be purchased in parallel but uploads must use the correct uploadUrl for each.

User asks to "share" or "send" a file: Upload it and present the public URL. The URL can be shared anywhere.

Host images for emails: Upload the image, then reference the

publicUrl

in email HTML:

html

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

上传用户刚创建的文件： 跳过发现步骤，直接检查钱包余额 → 购买额度 → 上传文件。

上传多个文件： 为每个文件单独购买额度。额度可并行购买，但每个文件必须使用对应的uploadUrl进行上传。

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

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

publicUrl

：

html

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

Error Handling

错误处理

Insufficient balance: Show the deposit link from
```
npx agentcash wallet info
```
File too large for tier: Suggest the next tier up
Upload URL expired: Buy a new slot (the previous payment is non-refundable)
curl fails: Verify the file path exists and the uploadUrl is correctly quoted

余额不足：显示
```
npx agentcash wallet info
```
中的充值链接
文件超出套餐大小限制：建议升级到更高套餐
上传URL过期：重新购买额度（之前的支付不予退款）
curl执行失败：验证文件路径是否存在，以及uploadUrl是否正确引用