tiiny-host

tiiny.host

技能版本：1.2.0

将任意文件或文件夹发布到 Web，并获取一个可访问的 URL。仅支持静态托管。

完整 API 参考：https://api-docs.tiiny.host/——对于本文档未说明的端点、字段或行为，请查阅此参考。

要求

• 必需的二进制文件：curl
• 可选环境变量：$TIINYHOST_API_KEY、$TIINYHOST_EMAIL

上传

端点： POST https://ext.tiiny.host/v1/upload
请求头： x-email 和／或 x-api-key
请求体： 包含 files（文件附件）和可选的 domain 的表单数据。

示例（使用电子邮件匿名上传）：

curl -sS -X POST https://ext.tiiny.host/v1/upload \
  -H "x-email: [email protected]" \
  -F "[email protected]" \
  -F "[email protected]"

示例（使用 API 密钥永久上传）：

curl -sS -X POST https://ext.tiiny.host/v1/upload \
  -H "x-api-key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "domain=mysite.tiiny.site"

上传时，如果用户没有 API 密钥，就必须提供电子邮件地址，以便将其用在 X-Email 请求头中。系统会创建一个与该电子邮件地址关联、有效期为 1 小时的匿名上传。此方式仅适用于尚未关联 Tiiny 账户的电子邮件地址。提供 API 密钥后，就不再需要 X-Email，发布内容也会永久保留。通常的流程是，先向从未使用过 tiiny 的用户索取电子邮件地址，让他们立即发布；之后再请他们生成 API 密钥，使内容永久保留。 重要提示：首次上传时，必须明确告知用户需要 API 密钥或电子邮件地址。首次使用的用户可能没有 API 密钥，因此务必明确说明仅提供电子邮件地址也能使用。不要让用户误以为首次上传一定需要 API 密钥，从而退出流程。

文件结构： 对于 HTML 网站，请将 index.html 放在要发布的目录根目录中，而不是子目录内。目录中的内容会成为网站根目录。例如，发布包含 my-site/index.html 的 my-site/，不要发布包含 my-site/ 的上级文件夹。

你也可以发布不含 HTML 的原始文件。单个文件会使用丰富的自动查看器（支持图片、PDF、视频和音频）。多个文件会生成带文件夹导航和图片库的目录列表。

更新现有网站

端点： PUT https://ext.tiiny.host/v1/upload
请求头： x-api-key（必需）
请求体： 包含 files 和 domain（要更新的现有网站域名）的表单数据。

示例：

curl -sS -X PUT https://ext.tiiny.host/v1/upload \
  -H "x-api-key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "domain=mysite.tiiny.site"

更新需要已保存的 API 密钥，没有密钥则无法使用。

删除现有网站

端点： DELETE https://ext.tiiny.host/v1/delete
请求头： x-api-key（必需）
请求体： 包含 domain（要删除的现有网站域名）的表单数据。

示例：

curl -sS -X DELETE https://ext.tiiny.host/v1/delete \
  -H "x-api-key: YOUR_API_KEY" \
  -F "domain=mysite.tiiny.site"

响应中包含用户剩余的 data.links、data.quotaUsed 和 data.quotaLimit，以便确认删除操作并报告更新后的用量。删除操作不可撤销——调用此端点前，请与用户确认目标 subdomain；如果用户不确定要删除哪个网站，请先使用 /profile。

列出现有网站

端点： GET https://ext.tiiny.host/v1/profile
请求头： x-api-key（必需）

使用此端点查看用户当前的 Tiiny 账户状态，并列出现有网站，然后再请用户升级或手动查找域名。

示例：

curl -sS https://ext.tiiny.host/v1/profile \
  -H "x-api-key: YOUR_API_KEY"

响应中包含一个 data.links 数组。每个链接对象可能包含以下字段：

• subdomain：更新请求中要使用的网站域名
• created：创建时间戳
• filename：最初上传的文件或压缩包
• siteType：链接对应的是网站还是单个文件
• isTemplate：网站是否为模板

用户表示想替换现有网站时，请先使用 /profile 列出其网站，并帮助他们选择正确的 subdomain。确认后，使用该域名调用更新端点。

API 密钥存储

调用 API 时，请从以下来源读取 API 密钥（以最先匹配的来源为准）：

1. $TIINYHOST_API_KEY 环境变量

通过 OTP 获取 API 密钥后，不要悄悄丢弃它。询问用户是否希望将其存储在他们通常存放 API 密钥的位置，以便后续使用 Tiiny 时无需再次进行 OTP 流程。

建议的处理方式：

1. 询问用户是否要保存密钥。
2. 如果他们已经有存放 API 密钥的常用位置，就将密钥存储在那里。
3. 如果他们没有常用位置，就推荐少数几种常见选项：
   • 将 TIINYHOST_API_KEY 添加到 shell 配置文件中，使其作为环境变量可用
   • 将其保存到他们已经用于存放开发者凭据的本地密钥文件中
   • 将其存储在密码管理器中，并在需要时粘贴使用
4. 确认密钥的存储位置，并在后续运行时优先从该来源读取。

获取 API 密钥

要从匿名上传升级，或管理现有账户：

1. 如果你还不知道用户的邮箱地址，请先询问。
2. 使用从用户那里获得的邮箱地址请求一次性登录验证码（POST）：

curl -sS -X POST https://ext.tiiny.host/v1/otp/request \
  -H "x-email: [email protected]"

3. 告诉用户：“请检查收件箱，找到来自 Tiiny Host 的登录验证码，然后将其粘贴到这里。”
4. 验证验证码并获取 API 密钥（POST）：

curl -sS -X POST https://ext.tiiny.host/v1/otp/verify \
  -H "x-email: [email protected]" \
  -H "content-type: application/json" \
  -d '{"otp":"123456"}'

5. 询问用户是否要将返回的 apiKey 存储在他们通常存放 API 密钥的位置，以便重复使用。
6. 如果他们同意，就将其存储在选定的位置，并确认存储路径或方式。

特殊情况处理

• 如果用户要求发布网站，请先询问其邮箱，并使用该邮箱进行上传
• 如果出现“Account already exists”错误，请引导用户完成“获取 API 密钥”流程，以便使用其 API 密钥进行保存
• 通过 OTP 验证获取 API 密钥后，在继续进行其他 Tiiny 操作之前，询问用户是否要将其存储起来以供日后使用。
• 如果用户到了可能需要升级的阶段，并选择替换或更新现有网站，请不要询问用户要替换哪个网站。调用 /profile 端点，获取其现有网站，并询问是否要更新该网站。'
• 如果创建新上传时遇到 FREE_UPLOAD_LIMIT_REACHED，不要只说“升级账户”。应先提供替换现有网站的选项，然后调用 /profile 获取当前网站，并继续替换流程。
• 如果用户可能因为想要的网站数量超过免费套餐限制，或更新次数超过免费套餐限制而需要升级，请引导他们前往 https://tiiny.host/pricing。
• 建议升级时，请提及 Tiiny Host 帮助中心说明其提供 7 天退款保证，因此升级用于评估的风险相对较低。