Blob 创建分享

POST

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/shares' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
    "expires_in": 604800,
    "max_downloads": 5
  }'

const response = await fetch('https://blob.squarecloud.app/v1/shares', {
  method: 'POST',
  headers: {
    Authorization: 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    object: 'prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf',
    expires_in: 7 * 24 * 60 * 60,
    max_downloads: 5,
  }),
});

{
  "status": "success",
  "response": {
    "id": "q8Zr2LwX7nT0vKc4Hs1YbA",
    "url": "https://files.squarecloud.dev/s/q8Zr2LwX7nT0vKc4Hs1YbA",
    "expires_at": "2026-10-02T12:00:00.000Z",
    "max_downloads": 5,
    "password": false,
    "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
    "object_is_public": false
  }
}

string

必填

你账户的 API 密钥。你可以在账户设置中找到它。

创建分享会生成一个链接（https://files.squarecloud.dev/s/...），用于把一个文件交给他人：客户、团队、测试人员。它适用于公开和私有文件，有效期最长 30 天，可以随时撤销，并且可以限制文件被下载的次数。在 Pro 和 Enterprise 计划上，它还可以要求输入密码。需要 blob:write scope。打开链接即可下载文件。受密码保护的链接会先显示一个以访问者语言呈现的页面，要求输入密码。该链接绑定文件当前的 id：删除、移动文件或更改其可见性都会使链接立即返回 404，且不会消耗下载次数。它与临时链接的对比请参见链接与分享。

string

必填

要分享的文件的 id。

number

默认值:"86400"

链接的有效时长，范围为 60 到 2592000 秒（30 天）。

number

链接允许的下载次数，范围为 1 到 10000。用尽后返回 410。不设置则没有上限。

string

访问者在下载前必须输入的 8 到 128 个字符的密码。仅限 Pro 和 Enterprise。

对于公开文件，链接会重定向到其永久公开 URL，任何打开链接的人都可以继续使用该 URL。密码、下载次数上限和有效期只能真正保护私有文件。

限制

每分钟 30 个链接（RATE_LIMITED，429），每个账户最多 1000 个有效链接（TOO_MANY_SHARES，409）。
每个链接对每个 IP 每分钟接受 120 次访问。错误密码按 IP 和按链接进行限制。
下载私有文件会经过一个临时链接：每个 IP 每分钟 60 次请求，外加你账户的总体限制。要把文件交给很多人，请将其设为公开。

响应

返回 201 Created。

string

成功为 “success”，否则为 “error”。

object

显示展开对象

string

分享 id。用于删除分享。

string

要分发的链接。

ISO 8601

链接的过期时间。

number | null

下载次数上限，或 null。

boolean

链接是否要求输入密码。

string

被分享文件的 id。

boolean

当文件为公开时为 true：任何拥有其公开 URL 的人仍可下载它，因此撤销、限制或保护分享并不会限制对文件本身的访问。

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/shares' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
    "expires_in": 604800,
    "max_downloads": 5
  }'

const response = await fetch('https://blob.squarecloud.app/v1/shares', {
  method: 'POST',
  headers: {
    Authorization: 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    object: 'prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf',
    expires_in: 7 * 24 * 60 * 60,
    max_downloads: 5,
  }),
});

{
  "status": "success",
  "response": {
    "id": "q8Zr2LwX7nT0vKc4Hs1YbA",
    "url": "https://files.squarecloud.dev/s/q8Zr2LwX7nT0vKc4Hs1YbA",
    "expires_at": "2026-10-02T12:00:00.000Z",
    "max_downloads": 5,
    "password": false,
    "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
    "object_is_public": false
  }
}

错误

代码	HTTP	触发情况
`INVALID_OBJECT`	400	`object` 缺失、格式错误或不属于你。
`INVALID_EXPIRES_IN`	400	`expires_in` 不是 60 到 2592000 之间的整数。
`INVALID_MAX_DOWNLOADS`	400	`max_downloads` 不是 1 到 10000 之间的整数。
`INVALID_PASSWORD`	400	密码不在 8 到 128 个字符之间。
`UPGRADE_REQUIRED`	403	密码需要 Pro 或 Enterprise。
`OBJECT_NOT_FOUND`	404	文件不存在。
`TOO_MANY_SHARES`	409	账户已有 1000 个有效链接。请先撤销一些。
`RATE_LIMITED`	429	一分钟内超过 30 个链接。

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/shares' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
    "expires_in": 604800,
    "max_downloads": 5
  }'

const response = await fetch('https://blob.squarecloud.app/v1/shares', {
  method: 'POST',
  headers: {
    Authorization: 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    object: 'prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf',
    expires_in: 7 * 24 * 60 * 60,
    max_downloads: 5,
  }),
});

{
  "status": "success",
  "response": {
    "id": "q8Zr2LwX7nT0vKc4Hs1YbA",
    "url": "https://files.squarecloud.dev/s/q8Zr2LwX7nT0vKc4Hs1YbA",
    "expires_at": "2026-10-02T12:00:00.000Z",
    "max_downloads": 5,
    "password": false,
    "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
    "object_is_public": false
  }
}

入门

对象

分块上传

账户

分享链接

S3

限制

响应

错误

​限制

​响应

​错误

限制

响应

错误