Blob 对象下载

GET

objects

download

curl --request GET \
  --url 'https://blob.squarecloud.app/v1/objects/download?object=prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf&expires=600&redirect=false' \
  --header 'Authorization: YOUR_API_KEY'

const params = new URLSearchParams({
  object: 'prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf',
  expires: '600',
  filename: 'invoice-september.pdf',
  redirect: 'false',
});

const res = await fetch(`https://blob.squarecloud.app/v1/objects/download?${params}`, {
  headers: { Authorization: 'YOUR_API_KEY' },
});
const { response } = await res.json();
// hand response.url to the user; it works without credentials for 10 minutes

{
  "status": "success",
  "response": {
    "url": "https://files.squarecloud.dev/d/Rb7nKq2WvX9sLp4TzYc1Hm8JdF0gUe6AoNiQ3tVwBk5Sy.Pj3Lx9Qe2Rw7Ty4Uo",
    "expires_at": "2026-09-25T12:10:00.000Z",
    "private": true,
    "size": 88412,
    "content_type": "application/pdf"
  }
}

string

必填

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

对象下载会为你提供一个读取文件的链接。对于私有文件，它会签发一个有效期为 60 秒到 24 小时、无需任何凭证即可使用的临时链接。对于公开文件，它会返回公开 URL。默认情况下它以 302 重定向响应，因此你可以直接让浏览器或 curl -L 访问它；redirect=false 则以 JSON 形式返回链接。需要 blob:read scope。临时链接（https://files.squarecloud.dev/d/...）无法撤销，支持 Range 和条件请求，并在过期或文件被删除、移动或可见性改变时失效。如需可撤销、可限制次数或受密码保护的链接，请使用分享链接。参见链接与分享。

string

必填

文件的 id。

number

默认值:"3600"

临时链接的有效时长，范围为 60 到 86400 秒（24 小时）。

boolean

默认值:"true"

false 以 JSON 形式返回链接，而不是重定向。

string

inline（在浏览器中打开）或 attachment（下载）。设置该参数后始终生成临时链接，即使是公开文件也是如此。

string

浏览器保存文件时使用的名称。除非 disposition 另有指定，否则隐含 attachment，并且始终生成临时链接。

速率限制

该路由每分钟 60 次请求（RATE_LIMITED，429）。
每个临时链接对每个 IP 每分钟接受 60 次请求，此外你账户的所有链接还共享一个总体限制。超出后该链接以纯文本返回 429。要把一个文件交给很多人，请将其设为公开：公开文件由 CDN 分发，不受此限制。已过期或无效的链接返回 404。

响应

redirect=true（默认）时：返回 302，链接位于 Location 中，并带有 Cache-Control: no-store。redirect=false 时：

string

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

object

显示展开对象

string

链接：位于 files.squarecloud.dev 上的临时链接，或公开 URL。

ISO 8601 | null

临时链接的过期时间，公开 URL 为 null。

boolean

文件是否为私有。

number

文件大小，单位为字节。

string

分发文件时使用的 Content-Type。

curl --request GET \
  --url 'https://blob.squarecloud.app/v1/objects/download?object=prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf&expires=600&redirect=false' \
  --header 'Authorization: YOUR_API_KEY'

const params = new URLSearchParams({
  object: 'prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf',
  expires: '600',
  filename: 'invoice-september.pdf',
  redirect: 'false',
});

const res = await fetch(`https://blob.squarecloud.app/v1/objects/download?${params}`, {
  headers: { Authorization: 'YOUR_API_KEY' },
});
const { response } = await res.json();
// hand response.url to the user; it works without credentials for 10 minutes

{
  "status": "success",
  "response": {
    "url": "https://files.squarecloud.dev/d/Rb7nKq2WvX9sLp4TzYc1Hm8JdF0gUe6AoNiQ3tVwBk5Sy.Pj3Lx9Qe2Rw7Ty4Uo",
    "expires_at": "2026-09-25T12:10:00.000Z",
    "private": true,
    "size": 88412,
    "content_type": "application/pdf"
  }
}

错误

代码	HTTP	触发情况
`INVALID_OBJECT`	400	`object` 缺失、格式错误或不属于你。
`INVALID_DOWNLOAD_EXPIRES`	400	`expires` 不是 60 到 86400 之间的整数。
`INVALID_OBJECT_DISPOSITION`	400	`disposition` 不是 `inline` 或 `attachment`。
`INVALID_FILENAME`	400	去除无效字符后 `filename` 为空。
`OBJECT_NOT_FOUND`	404	文件不存在。
`RATE_LIMITED`	429	一分钟内超过 60 次请求。

curl --request GET \
  --url 'https://blob.squarecloud.app/v1/objects/download?object=prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf&expires=600&redirect=false' \
  --header 'Authorization: YOUR_API_KEY'

const params = new URLSearchParams({
  object: 'prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf',
  expires: '600',
  filename: 'invoice-september.pdf',
  redirect: 'false',
});

const res = await fetch(`https://blob.squarecloud.app/v1/objects/download?${params}`, {
  headers: { Authorization: 'YOUR_API_KEY' },
});
const { response } = await res.json();
// hand response.url to the user; it works without credentials for 10 minutes

{
  "status": "success",
  "response": {
    "url": "https://files.squarecloud.dev/d/Rb7nKq2WvX9sLp4TzYc1Hm8JdF0gUe6AoNiQ3tVwBk5Sy.Pj3Lx9Qe2Rw7Ty4Uo",
    "expires_at": "2026-09-25T12:10:00.000Z",
    "private": true,
    "size": 88412,
    "content_type": "application/pdf"
  }
}

入门

对象

分块上传

账户

分享链接

S3

速率限制

响应

错误

​速率限制

​响应

​错误

速率限制

响应

错误