> ## 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 分块上传初始化

> 本文档全面介绍 SquareCloud Blob API 的 POST /v1/objects/chunked 端点。

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

Chunked Init 用于开启一次分块上传，即针对超过 100 MB 单请求上限、最大 **1 GiB** 文件的上传流程。它会预留对象的键，并返回一个不透明的 `upload` 令牌，供你在后续三个调用中携带：[分块发送](/zh/blob-reference/endpoint/chunked-part)用于发送每个分块，[分块完成](/zh/blob-reference/endpoint/chunked-complete)用于封存对象，[分块中止](/zh/blob-reference/endpoint/chunked-abort)用于取消。

服务端**不保存会话**：该令牌就是上传的全部状态，因此如果上传会跨越页面刷新，请持久化保存它。丢失令牌的客户端将无法取消上传，已存储的分块会一直计入账户 **8 个未完成上传**的限制，直到服务回收它们为止（约 24 小时）。

查询参数契约与[对象上传](/zh/blob-reference/endpoint/post)相同，另加 `filename`：这里没有 multipart 封装，因此存储的扩展名必须来自查询字符串。上传需要付费套餐。

<ParamField query="name" type="string" placeholder="File Name" required>
  表示文件名称的字符串。（不含扩展名）<br />必须符合 a 到 z、A 到 Z、0 到 9 以及 \_ 的模式。（3 到 32 个字符）
</ParamField>

<ParamField query="filename" type="string" placeholder="Original filename">
  原始文件名，包含扩展名（例如 `reads.fastq.gz`）。存储的扩展名由它推导得出，其次回退到 `mime_type` 参数，最后回退到 `bin`。
</ParamField>

<ParamField query="prefix" type="string" placeholder="File Prefix">
  表示文件前缀的字符串。<br />必须符合 a 到 z、A 到 Z、0 到 9 以及 \_ 的模式。（3 到 32 个字符）
</ParamField>

<ParamField query="expire" type="number" placeholder="Expiration (days)">
  表示文件过期周期的数字，范围为 7 到 1825 天（5 年）。
</ParamField>

<ParamField query="security_hash" type="boolean" placeholder="Security Hash">
  如果需要安全哈希，请设为 true。
</ParamField>

<ParamField query="auto_download" type="boolean" placeholder="Auto Download">
  如果文件应设为自动下载，请设为 true。
</ParamField>

### 限制

<Note>
  * 对象大小：最大 **1 GiB**（1,073,741,824 字节）。
  * 分块大小：**最小 5 MB**，**最大 32 MB**（最后一个分块可以更小）。
  * 每个对象的分块数：**205**（分块编号从 1 到 205）。
  * 每个账户的未完成上传数：**8** 个并存（`TOO_MANY_OPEN_UPLOADS`，429）。
  * 速率限制：每 10 秒可开启 5 次，超出后封锁 10 秒。

  请从响应中的 `chunk` 对象读取这些限制，而不要将其硬编码。
</Note>

### 响应

<ResponseField name="status" type="string">
  指示调用是否成功。成功为 "success"，否则为 "error"。
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="展开对象">
    <ResponseField name="upload" type="string">
      不透明的上传令牌。请在该流程后续的每次调用中携带它；它是此次上传的唯一句柄。
    </ResponseField>

    <ResponseField name="id" type="string">
      对象将要存储在其下的 ID（键）。
    </ResponseField>

    <ResponseField name="name" type="string">
      文件的名称。
    </ResponseField>

    <ResponseField name="prefix" type="string">
      文件将要存储的前缀（未发送时为 `null`）。
    </ResponseField>

    <ResponseField name="url" type="string">
      对象完成后对外提供服务的公开 CDN URL。
    </ResponseField>

    <ResponseField name="chunk" type="object">
      分块流程的限制：`min_size` 和 `max_size`（分块字节数）、`max_parts`，以及 `max_object_size`（总字节数）。
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://blob.squarecloud.app/v1/objects/chunked?name=myfile&filename=reads.fastq.gz&expire=30' \
    --header 'Authorization: YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    name: 'myfile',
    filename: 'reads.fastq.gz',
    expire: '30',
  });

  const response = await fetch(`https://blob.squarecloud.app/v1/objects/chunked?${params}`, {
    method: 'POST',
    headers: { Authorization: 'YOUR_API_KEY' },
  });

  const { response: upload } = await response.json();
  // persist upload.upload — it is the only handle to this upload
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://blob.squarecloud.app/v1/objects/chunked',
      headers={'Authorization': 'YOUR_API_KEY'},
      params={'name': 'myfile', 'filename': 'reads.fastq.gz', 'expire': 30},
  )
  upload = response.json()['response']
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "response": {
      "upload": "MzE1NTU5NzE0NTY5ODk1OTM2NC9teWZpbGUtZXgzMC5mYXN0cS5negoyfjQ4WXcuLi4KMzA",
      "id": "3155597145698959364/myfile-ex30.fastq.gz",
      "name": "myfile",
      "prefix": null,
      "url": "https://public-blob.squarecloud.dev/3155597145698959364/myfile-ex30.fastq.gz",
      "chunk": {
        "min_size": 5242880,
        "max_size": 33554432,
        "max_parts": 205,
        "max_object_size": 1073741824
      }
    }
  }
  ```
</ResponseExample>

### 故障排查

<Tabs>
  <Tab title="400 状态码">
    ### 对象相关

    <CodeGroup>
      ```json NAME theme={null}
      // The provided object name is invalid.
      // Must adhere to the a to z, A to Z, 0 to 9, and _ pattern.
      {
          "status": "error",
          "code": "INVALID_OBJECT_NAME"
      }
      ```

      ```json PREFIX theme={null}
      // The provided object prefix is invalid.
      // Must adhere to the a to z, A to Z, 0 to 9, and _ pattern.
      {
          "status": "error",
          "code": "INVALID_OBJECT_PREFIX"
      }
      ```

      ```json EXPIRE theme={null}
      // The provided expiration value for the object is invalid.
      // Must be a number ranging from 7 to 1825. (value in days).
      {
          "status": "error",
          "code": "INVALID_OBJECT_EXPIRE"
      }
      ```

      ```json FILETYPE theme={null}
      // The file extension is malformed or too long.
      {
          "status": "error",
          "code": "INVALID_FILE_TYPE"
      }
      ```

      ```json BLOCKED_FILE_TYPE theme={null}
      // Executable/installer extensions (exe, msi, bat, apk, ...) are not accepted.
      {
          "status": "error",
          "code": "BLOCKED_FILE_TYPE"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="401 状态码">
    ### 未授权

    <CodeGroup>
      ```json ACCESS_DENIED theme={null}
      // The API key is missing or invalid. Set a valid key in the Authorization header.
      {
          "status": "error",
          "code": "ACCESS_DENIED"
      }
      ```

      ```json PERMISSION_DENIED theme={null}
      // The account has no active paid plan. Uploading to Blob Storage requires a paid plan.
      {
          "status": "error",
          "code": "PERMISSION_DENIED"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="403 状态码">
    ### 存储配额超限

    <CodeGroup>
      ```json STORAGE_QUOTA_EXCEEDED theme={null}
      // You have exceeded your storage quota. Delete some files or upgrade your plan.
      {
          "status": "error",
          "code": "STORAGE_QUOTA_EXCEEDED"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="429 状态码">
    ### 速率受限

    <CodeGroup>
      ```json RATE_LIMITED theme={null}
      // Init rate limit reached (5 opens per 10s window, blocked for 10s).
      {
          "status": "error",
          "code": "RATE_LIMITED"
      }
      ```

      ```json TOO_MANY_OPEN_UPLOADS theme={null}
      // 8 chunked uploads already open. Complete or abort one first.
      {
          "status": "error",
          "code": "TOO_MANY_OPEN_UPLOADS"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="500 状态码">
    ### 上传失败

    <CodeGroup>
      ```json UPLOAD_FAILED theme={null}
      // Failed to open the chunked upload. Please try again later.
      {
          "status": "error",
          "code": "UPLOAD_FAILED"
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>