> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Blob 对象下载

> 通过 GET /v1/objects/download 获取任意文件的下载链接：私有文件获得最长 24 小时的临时链接，公开文件获得其公开 URL。

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  你账户的 API 密钥。你可以在[账户设置](https://squarecloud.app/zh/account/security)中找到它。
</ParamField>

对象下载会为你提供一个读取文件的链接。对于**私有**文件，它会签发一个有效期为 60 秒到 24 小时、无需任何凭证即可使用的临时链接。对于**公开**文件，它会返回公开 URL。默认情况下它以 `302` 重定向响应，因此你可以直接让浏览器或 `curl -L` 访问它；`redirect=false` 则以 JSON 形式返回链接。需要 `blob:read` scope。

临时链接（`https://files.squarecloud.dev/d/...`）无法撤销，支持 `Range` 和条件请求，并在过期或文件被删除、移动或可见性改变时失效。如需可撤销、可限制次数或受密码保护的链接，请使用[分享链接](/zh/blob-reference/endpoint/shares-create)。参见[链接与分享](/zh/blob-reference/links-and-sharing)。

<ParamField query="object" type="string" required>
  文件的 id。
</ParamField>

<ParamField query="expires" type="number" default="3600">
  临时链接的有效时长，范围为 60 到 86400 秒（24 小时）。
</ParamField>

<ParamField query="redirect" type="boolean" default="true">
  `false` 以 JSON 形式返回链接，而不是重定向。
</ParamField>

<ParamField query="disposition" type="string">
  `inline`（在浏览器中打开）或 `attachment`（下载）。设置该参数后始终生成临时链接，即使是公开文件也是如此。
</ParamField>

<ParamField query="filename" type="string" placeholder="report-september.pdf">
  浏览器保存文件时使用的名称。除非 `disposition` 另有指定，否则隐含 `attachment`，并且始终生成临时链接。
</ParamField>

### 速率限制

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

### 响应

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

<ResponseField name="status" type="string">
  成功为 "success"，否则为 "error"。
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="展开对象">
    <ResponseField name="url" type="string">
      链接：位于 `files.squarecloud.dev` 上的临时链接，或公开 URL。
    </ResponseField>

    <ResponseField name="expires_at" type="ISO 8601 | null">
      临时链接的过期时间，公开 URL 为 `null`。
    </ResponseField>

    <ResponseField name="private" type="boolean">
      文件是否为私有。
    </ResponseField>

    <ResponseField name="size" type="number">
      文件大小，单位为字节。
    </ResponseField>

    <ResponseField name="content_type" type="string">
      分发文件时使用的 `Content-Type`。
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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'
  ```

  ```javascript JavaScript theme={null}
  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
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

### 错误

| 代码                           | 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 次请求。                            |