> ## 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 创建分享

> 通过 POST /v1/shares 创建分享链接：有效期最长 30 天，可撤销，可选下载次数上限，在 Pro 和 Enterprise 计划上还可设置密码。

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

创建分享会生成一个链接（`https://files.squarecloud.dev/s/...`），用于把一个文件交给他人：客户、团队、测试人员。它适用于公开和私有文件，有效期最长 30 天，可以随时撤销，并且可以限制文件被下载的次数。在 **Pro 和 Enterprise** 计划上，它还可以要求输入密码。需要 `blob:write` scope。

打开链接即可下载文件。受密码保护的链接会先显示一个以访问者语言呈现的页面，要求输入密码。该链接绑定文件当前的 id：删除、移动文件或更改其可见性都会使链接立即返回 `404`，且不会消耗下载次数。它与临时链接的对比请参见[链接与分享](/zh/blob-reference/links-and-sharing)。

<ParamField body="object" type="string" required>
  要分享的文件的 id。
</ParamField>

<ParamField body="expires_in" type="number" default="86400">
  链接的有效时长，范围为 60 到 2592000 秒（30 天）。
</ParamField>

<ParamField body="max_downloads" type="number">
  链接允许的下载次数，范围为 1 到 10000。用尽后返回 `410`。不设置则没有上限。
</ParamField>

<ParamField body="password" type="string">
  访问者在下载前必须输入的 8 到 128 个字符的密码。仅限 Pro 和 Enterprise。
</ParamField>

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

### 限制

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

### 响应

返回 `201 Created`。

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

<ResponseField name="response" type="object">
  <Expandable title="展开对象">
    <ResponseField name="id" type="string">
      分享 id。用于[删除分享](/zh/blob-reference/endpoint/shares-delete)。
    </ResponseField>

    <ResponseField name="url" type="string">
      要分发的链接。
    </ResponseField>

    <ResponseField name="expires_at" type="ISO 8601">
      链接的过期时间。
    </ResponseField>

    <ResponseField name="max_downloads" type="number | null">
      下载次数上限，或 `null`。
    </ResponseField>

    <ResponseField name="password" type="boolean">
      链接是否要求输入密码。
    </ResponseField>

    <ResponseField name="object" type="string">
      被分享文件的 id。
    </ResponseField>

    <ResponseField name="object_is_public" type="boolean">
      当文件为公开时为 `true`：任何拥有其公开 URL 的人仍可下载它，因此撤销、限制或保护分享并不会限制对文件本身的访问。
    </ResponseField>
  </Expandable>
</ResponseField>

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

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

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

### 错误

| 代码                      | 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 个链接。                      |