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 日間だけ保存すればよい場合は、6 か月のティアより大幅に安価な short-* ティアを使用してください。

ティア	最大サイズ	保持期間	料金
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 の範囲です。後続サービス用に出力枠を確保する場合に限り、長い TTL を使用してください

レスポンス：

{
  "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 を使用して、返された uploadUrl にファイルを PUT します。

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

重要： バイナリーコンテンツを保持するため、-d ではなく --data-binary を使用してください。絶対パスを指定してください。

レスポンスには、すぐに使える curlExample が含まれています。uploadMethod が "post" の場合は PUT ではなく、postFields を使用して postUrl にマルチパートフォームをアップロードしてください。

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} が返されます。すぐに SSL を利用できるよう、ドメインを関連付ける前にこれらの DNS レコードを設定してください。

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 倍延長します（例：デフォルトのティアでは6か月 × 4）。料金 = ティアの価格 × count（$0.005～$20.00）。

注意事項

• 1サイトあたり最大500ファイル
• ティアの上限は非圧縮サイズに適用されます
• サイトは short-5gb を除くすべてのティアに対応しています。POST /api/site で指定するのは filename と tier のみです（contentType は指定しません）
• カスタムドメインでは Cloudflare による HTTPS が自動的に有効になります

エラー処理

• 残高不足：npx agentcash@latest accounts を実行して、入金リンクとウォレットアドレスを表示します
• ファイルがティアの上限を超えている：1つ上のティアを提案します
• アップロード URL の有効期限切れ：新しいスロットを購入します（前回の支払いは返金されません）
• curl が失敗する：ファイルパスが存在すること、および uploadUrl が正しく引用符で囲まれていることを確認します