API文档

通过简单的 JSON REST API 以编程方式自动上传和管理文件。 所有请求和响应都是 application/json。基本 URL 是：

https://api.fast2share.com

登录以创建令牌

验证

在您的面板中创建一个令牌 设置 → API 令牌。根据中的每个请求发送它 Authorization 标头。令牌在创建时显示一次 - 存储它们 安全地。每个令牌都代表您的帐户，并且只能看到您自己的文件。

标头
Authorization: Bearer f2s_YOUR_TOKEN

错误

错误使用标准 HTTP 状态代码并返回带有以下内容的 JSON 正文 error 信息。常用代码： 401 （令牌丢失/无效）， 403 （配额或计划限制）， 404 （未找到文件）， 409 （冲突 - 例如文件已在您的帐户中，请参阅 POST /v1/uploads), 422 （错误的请求主体）， 503 （没有可用的存储服务器）。

{
  "error": "Invalid or revoked API token."
}

端点

得到 /v1/用户
获取当前用户

返回令牌所有者的帐户、活动计划和当前存储使用情况。

要求
curl https://api.fast2share.com/v1/user \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"
回复
{
  "id": 42,
  "email": "[email protected]",
  "display_name": "You",
  "plan": {
    "name": "premium-monthly",
    "max_file_size": 5368709120,
    "storage_quota": 107374182400
  },
  "usage": {
    "used_bytes": 2147483648,
    "file_count": 12,
    "remaining_bytes": 105226698752
  }
}
得到 /v1/文件
列出文件

列出您已完成的文件，最新的在前。游标分页：传递返回的 next_before 作为 ?before= 为下一页。按名称过滤 ?q=.

要求
curl "https://api.fast2share.com/v1/files?before=0&q=report" \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"
回复
{
  "data": [
    {
      "uuid": "3f1c…-…-…",
      "name": "report.pdf",
      "size": 184320,
      "mime": "application/pdf",
      "sha256": "9f86d0…",
      "status": "completed",
      "downloads": 3,
      "share_url": "https://…/f/3f1c…",
      "created_at": "2026-07-01T10:00:00+00:00",
      "expires_at": null
    }
  ],
  "next_before": 1057
}
得到 /v1/文件夹
列出文件夹

您帐户上的每个文件夹，首先是顶级文件夹。使用 id 作为 folder_id 移动或复制文件时。

要求
curl https://api.fast2share.com/v1/folders \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"
回复
{
  "data": [
    { "id": 12, "name": "Invoices", "parent_id": null, "created_at": "2026-06-02T09:12:00+00:00" },
    { "id": 19, "name": "2026",     "parent_id": 12,   "created_at": "2026-06-02T09:13:00+00:00" }
  ]
}
邮政 /v1/文件夹
创建文件夹

创建一个文件夹。 name 是必需的，并且在您的帐户中必须是唯一的（不区分大小写） - 冲突答案 409。经过 parent_id 嵌套它：文件夹去 仅一层深，并且父文件夹最多拥有一个子文件夹，因此本身嵌套（或已经有子文件夹）的父文件夹会回答 422.

要求
curl -X POST https://api.fast2share.com/v1/folders \
  -H "Authorization: Bearer f2s_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Invoices","parent_id":null}'
回复
{
  "id": 12,
  "name": "Invoices",
  "parent_id": null,
  "created_at": "2026-07-31T08:20:00+00:00"
}
邮政 /v1/上传
创建上传

上传演练 - 上传有两个步骤 因为字节去 直接到存储服务器 （通过可恢复的 特斯 协议）;他们从不通过这个API。此调用验证您的计划/配额并返回 tus 端点以及签名的 upload_token.

1. POST /v1/uploads 文件名和大小 → 返回 upload_url, upload_token 和 uuid （这个端点）。
2.执行tus上传到 upload_url，添加元数据 token <upload_token>。任何 tus 客户端都可以工作（例如 tus-js-client, tusc). 以块的形式发送字节 （建议 8 MB）：携带整个文件的单个 tus 请求被拒绝 413 一旦主体超过约 100 MB，就会由存储 CDN 进行处理。
3. 民意调查 GET /v1/files/{uuid}/status 直到报告为止 completed，然后使用返回的 share_url.

使用重复数据删除（可选）跳过传输。 如果已经存储了相同的字节，则可以立即创建文件 - 不会上传任何内容：
• fingerprint = 前 8 MB 与最后 8 MB 连接的 SHA-256（读取 ≤ 16 MB；如果文件≤ 8 MB，则它只是整个文件的 SHA-256，在 8 到 16 MB 之间，两个范围覆盖一次，不重叠）。 总是发送这个 当您需要重复数据删除时 — API 就是通过它知道您确实保存了该文件，因此另一个帐户拥有的字节永远不会在裸校验和上共享。
• sha256 = 完整文件 SHA-256，十六进制。将其与指纹一起发送，立即得到答复：如果 您的帐户已经有该文件 什么都没有被创建，你得到 409 和 {"status":"exists","uuid":…,"share_url":…} 指向您现有的副本；如果另一个帐户拥有这些字节，它们会立即与您共享： {"status":"completed","deduped":true,"share_url":…} - 完成，没有上传任何内容。
• 对于大文件，则采用惰性散列方式：仅发送 fingerprint。的回复 {"status":"need_hash"} 意味着存在可能的匹配 - 对文件进行完整哈希并调用 POST /v1/uploads/{uuid}/confirm。任何其他回复均为正常票据；像往常一样上传。
省略这两个字段即可始终上传。

要求
curl -X POST https://api.fast2share.com/v1/uploads \
  -H "Authorization: Bearer f2s_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filename":"report.pdf","size":184320,"type":"application/pdf","fingerprint":"5b41e3…","sha256":"9f86d0…"}'
回复
{
  "uuid": "3f1c…-…-…",
  "status": "pending",
  "upload_url": "https://storage1.example.com/files/",
  "upload_token": "eyJ1d….<sig>",
  "protocol": "tus",
  "metadata_key": "token"
}

// deduped instead — the bytes were already stored, nothing to upload:
{
  "uuid": "3f1c…-…-…",
  "status": "completed",
  "deduped": true,
  "size": 184320,
  "sha256": "9f86d0…",
  "share_url": "https://…/f/3f1c…"
}
⚠ 对上传的内容进行分块 — 对于超过 100 MB 的文件来说是必需的。 存储 服务器位于 CDN 后面，该 CDN 会拒绝任何正文超出的单个请求 〜100MB 和 413 Request Entity Too Large。阿图斯 PATCH 携带着 所有的 因此 file 在处理大文件时会失败。保留 每个块都很小—— 8MB 是一个很好的默认值——这也使得上传 连接断开后可恢复。

常见错误： tus-js-client 默认为 chunkSize: Infinity （一次请求整个文件），因此上传超过约 100 MB 失败与 413。你 必须 设置一个明确的 chunkSize: 
import * as tus from "tus-js-client";

// upload_url + upload_token come from POST /v1/uploads
const upload = new tus.Upload(file, {
  endpoint:  upload_url,
  chunkSize: 8 * 1024 * 1024,      // 8 MB — REQUIRED, keep well under 100 MB
  metadata:  { token: upload_token },
  onError:   (err) => console.error(err),
  onSuccess: () => console.log("done — poll /v1/files/{uuid}/status"),
});
upload.start();
邮政 /v1/上传/{uuid}/确认
确认重复数据删除

第二步 fingerprint flow：仅在之后调用此函数 POST /v1/uploads 回答了 {"status":"need_hash"}，与完整文件 sha256。指纹和大小是您在创建上传时发送的信息 - 不会从此请求中重新读取它们。与上面相同的三个结果：已在您的帐户中 → 409 exists （没有存储任何内容）；其他地方拥有 → 立即完成（deduped）；否则指纹只是碰撞，你会得到正常的结果 upload_url / upload_token 票证 — 按照上述步骤 2 上传。

要求
curl -X POST https://api.fast2share.com/v1/uploads/3f1c…-…-…/confirm \
  -H "Authorization: Bearer f2s_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sha256":"9f86d0…"}'
回复
{
  "uuid": "3f1c…-…-…",
  "status": "completed",
  "deduped": true,
  "size": 184320,
  "sha256": "9f86d0…",
  "share_url": "https://…/f/3f1c…"
}
得到 /v1/文件/{uuid}
获取文件信息

返回您拥有的单个文件的元数据。

要求
curl https://api.fast2share.com/v1/files/3f1c…-…-… \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"
回复
{
  "uuid": "3f1c…-…-…",
  "name": "report.pdf",
  "size": 184320,
  "mime": "application/pdf",
  "sha256": "9f86d0…",
  "status": "completed",
  "downloads": 3,
  "share_url": "https://…/f/3f1c…",
  "created_at": "2026-07-01T10:00:00+00:00",
  "expires_at": null
}
得到 /v1/文件/{uuid}/状态
检查上传状态

用于上传状态的轻量级探针： pending, completed 或者 failed。一旦完成，它还会返回 share_url.

要求
curl https://api.fast2share.com/v1/files/3f1c…-…-…/status \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"
回复
{
  "uuid": "3f1c…-…-…",
  "status": "completed",
  "size": 184320,
  "share_url": "https://…/f/3f1c…"
}
得到 /v1/files/{uuid}/download
获取直接下载链接

为您拥有的文件创建一个随时可用的直接下载 URL。该链接立即传输字节 无需浏览器会话 （从脚本/curl 使用它）并在大约 5 分钟后过期。需要有效的高级订阅（始终允许管理员）。

要求
curl https://api.fast2share.com/v1/files/3f1c…-…-…/download \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"
回复
{
  "uuid": "3f1c…-…-…",
  "name": "report.pdf",
  "size": 184320,
  "download_url": "https://…/d/9xA2…",
  "expires_in": 300
}
邮政 /v1/文件/{uuid}/重命名
重命名文件

更改您拥有的文件的显示名称。分享链接（uuid）不会改变，因此您已经分发的链接仍然有效 - 只有共享页面上显示并随下载更改一起发送的名称。路径分隔符和控制字符被去除；该名称的长度上限为 512 个字符。

要求
curl -X POST https://api.fast2share.com/v1/files/3f1c…-…-…/rename \
  -H "Authorization: Bearer f2s_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"invoice-july.pdf"}'
回复
{
  "uuid": "3f1c…-…-…",
  "name": "invoice-july.pdf",
  "size": 184320,
  "status": "completed",
  "share_url": "https://…/f/3f1c…"
}
邮政 /v1/文件/{uuid}/移动
移动文件

将您拥有的文件归档到您的文件夹之一。发送 {"folder_id": 0} （或省略它）将其移回根。该文件夹必须是你的，否则 404.

要求
curl -X POST https://api.fast2share.com/v1/files/3f1c…-…-…/move \
  -H "Authorization: Bearer f2s_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder_id":12}'
回复
{
  "uuid": "3f1c…-…-…",
  "name": "invoice-july.pdf",
  "status": "completed",
  "share_url": "https://…/f/3f1c…",
  "folder_id": 12
}
邮政 /v1/files/{uuid}/copy
复制共享文件

放置一个文件 别人 通过您自己的共享链接与您共享到您自己的帐户 - 此处 {uuid} 是 来源 文件的共享段，而不是您的共享段。 不传输任何字节： 副本指向同一个存储对象，因此它会立即完成，并像任何其他文件一样计入您的存储配额。

来源必须是公开的、已完成的，并且其所有者必须允许复制 - 否则你会得到 403. 409 意味着它已经是您的文件（或已经在您的帐户中），并且 403 还涵盖“没有足够的存储空间”。可选的正文字段： folder_id, is_public （默认 true）和 free_download （默认为 false）。

要求
curl -X POST https://api.fast2share.com/v1/files/3f1c…-…-…/copy \
  -H "Authorization: Bearer f2s_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder_id":12,"is_public":true}'
回复
{
  "uuid": "8b2e…-…-…",
  "name": "report.pdf",
  "size": 184320,
  "status": "completed",
  "share_url": "https://…/f/8b2e…",
  "copied": true
}
邮政 /v1/文件/{uuid}/删除
删除文件

软删除您拥有的文件；它立即停止下载，并且其字节不久后被回收。

要求
curl -X POST https://api.fast2share.com/v1/files/3f1c…-…-…/delete \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"
回复
{ "ok": true, "uuid": "3f1c…-…-…" }