> ## 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 Storage API 快速入门

> 用 Blob Storage API 上传并下载第一个文件：v1 基础 URL、Authorization 请求头、curl 上传、响应内容和下载链接。

Blob Storage 用于保存你的文件，通过 CDN 提供公开文件，并为私有文件生成链接。本页使用 `curl`，带你从 API 密钥开始，完成一次文件上传并获得下载链接。所有套餐都包含存储空间：套餐、价格和常见问题见 [Blob Storage](/zh/services/blob)。

## 基础 URL

本参考中的每个端点都相对于：

```bash theme={"system"}
https://blob.squarecloud.app/v1
```

## 身份验证

Blob Storage 在 `Authorization` 请求头中使用与 [Square Cloud API](/zh/api-reference/introduction) 相同的 API 密钥。上传需要 `blob:write` scope，列出和下载需要 `blob:read`，并且该密钥不能限定到特定应用。请在[账户安全设置](https://squarecloud.app/zh/account/security)中创建密钥，并保存在环境变量中：

```bash theme={"system"}
export SQUARECLOUD_API_KEY="your-api-key"
```

关于 scope 和上传令牌的更多信息，请参阅[身份验证](/zh/blob-reference/authentication)。

## 上传文件

[对象上传](/zh/blob-reference/endpoint/post)以 `multipart/form-data` 接收文件，并在查询参数中接收不含扩展名的文件名：

```bash theme={"system"}
curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --form 'file=@./logo.png'
```

```json theme={"system"}
{
  "status": "success",
  "response": {
    "id": "pub/3155597145698959364/images/logo.png",
    "private": false,
    "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo.png",
    "size": 416230,
    "name": "logo",
    "prefix": "images",
    "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
    "replaced": false
  }
}
```

文件默认是公开的：`url` 可以直接在浏览器或 `<img>` 标签中使用。请原样保存 `id`，因为其他所有路由都需要它。

单个请求可接收 512 字节到 100 MB 的文件。更大的文件（最大 10 GiB）请使用[分块上传](/zh/blob-reference/endpoint/chunked-init)或 [S3 网关](/zh/blob-reference/s3-compatibility)。

## 上传私有文件

添加 `private=true`，文件就不会有公开 URL（`url` 为 `null`）：

```bash theme={"system"}
curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=invoice&prefix=invoices&private=true' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --form 'file=@./invoice.pdf'
```

## 下载文件

公开文件可通过其 `url` 下载。对于私有文件，[对象下载](/zh/blob-reference/endpoint/download)会签发一个无需凭证即可使用的临时链接并重定向到该链接，因此 `curl -L` 会直接保存文件：

```bash theme={"system"}
curl -L --output invoice.pdf \
  --url 'https://blob.squarecloud.app/v1/objects/download?object=<id>' \
  --header "Authorization: $SQUARECLOUD_API_KEY"
```

将 `<id>` 替换为上传返回的 `id`。添加 `redirect=false` 可以以 JSON 形式获取链接并转交给他人。如需可吊销或可设置密码的链接，请创建[分享链接](/zh/blob-reference/endpoint/shares-create)。

## 列出和删除文件

[对象列表](/zh/blob-reference/endpoint/list)会分页返回你的文件：

```bash theme={"system"}
curl --url 'https://blob.squarecloud.app/v1/objects?prefix=images/' \
  --header "Authorization: $SQUARECLOUD_API_KEY"
```

[对象删除](/zh/blob-reference/endpoint/delete)可删除一个文件，或在一个请求中删除最多 100 个文件：

```bash theme={"system"}
curl --request DELETE \
  --url 'https://blob.squarecloud.app/v1/objects' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{ "object": "<id>" }'
```

## 出错时

错误以 `{ "status": "error", "code": "..." }` 的形式返回。你最可能首先遇到的是：

| 代码 | HTTP | 解决方法 |
| - | - | - |
| `ACCESS_DENIED` | 401 | 密钥缺失或无法识别。请检查 `Authorization` 请求头。 |
| `PERMISSION_DENIED` | 401 | 账户没有有效套餐，因此无法上传。 |
| `MISSING_SCOPE` | 403 | 密钥缺少 `blob:write` 或 `blob:read`。请创建具有该 scope 的密钥。 |
| `RESOURCE_NOT_ALLOWED` | 403 | 密钥被限定到了特定应用。请使用没有该限制的密钥。 |
| `FILE_TOO_LARGE` | 413 | 文件超过 100 MB。请使用分块上传。 |

所有代码见[错误](/zh/blob-reference/errors)。

## 后续步骤

<CardGroup cols={2}>
  <Card title="Blob SDK" icon="js" href="/zh/sdks/blob/client">
    在 JavaScript 中上传和管理文件，分块上传会自动处理。
  </Card>

  <Card title="S3 兼容性" icon="bucket" href="/zh/blob-reference/s3-compatibility">
    使用 aws-cli、boto3、rclone 或任意 AWS SDK。
  </Card>

  <Card title="链接与分享" icon="share-nodes" href="/zh/blob-reference/links-and-sharing">
    临时链接、分享链接以及各自的适用场景。
  </Card>

  <Card title="从浏览器上传" icon="upload" href="/zh/blob-reference/endpoint/upload-tokens">
    让访客上传文件，而不暴露你的 API 密钥。
  </Card>
</CardGroup>