> ## 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 的 PUT /v1/objects/chunked 端点。

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

Chunked Part 用于发送通过[分块初始化](/zh/blob-reference/endpoint/chunked-init)开启的上传中的一个分块。请求体是该分块的**原始字节**，而不是 multipart/form-data。分块编号从 1 到 `max_parts`（205），并且可以按**任意顺序**发送；失败的分块只需用相同编号重新发送即可，由于分块是幂等的，重发是安全的。

除最后一个分块外，每个分块必须在 **5 MB 到 32 MB** 之间；最后一个可以更小。最多同时并行发送 **6 个分块**：第 7 个在途分块会返回 `TOO_MANY_CONCURRENT_CHUNKS`，此时请等待某个分块完成后再重试该分块。在 6 个分块并行的情况下，对浏览器而言 16 MB 的分块大小是一个不错的默认值。

该路由不计入账户级 API 配额（`plan.rate`），因此一次耗时较长的上传不会耗尽你在平台其他部分的 API 配额。它自身的限流器允许每 10 秒发送 60 个分块，超出后封锁 10 秒。

<ParamField query="upload" type="string" placeholder="Upload token" required>
  由分块初始化返回的不透明 `upload` 令牌。
</ParamField>

<ParamField query="part" type="number" placeholder="1..205" required>
  分块编号，从 1 到 205。分块可以按任意顺序发送。
</ParamField>

<ParamField body="body" type="binary" required>
  分块的原始字节（`Content-Type: application/octet-stream`）。**不是** multipart/form-data。
</ParamField>

### 响应

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

<ResponseField name="response" type="object">
  <Expandable title="展开对象">
    <ResponseField name="part" type="number">
      已存储的分块编号。
    </ResponseField>

    <ResponseField name="size" type="number">
      已存储分块的大小，单位为字节。
    </ResponseField>

    <ResponseField name="etag" type="string">
      该分块的存储 ETag。仅供参考：完成时会从存储端读回分块列表，因此你永远不需要把它传回。
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request PUT \
    --url 'https://blob.squarecloud.app/v1/objects/chunked?upload=UPLOAD_TOKEN&part=1' \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'Content-Type: application/octet-stream' \
    --data-binary '@./chunk-1.bin'
  ```

  ```javascript JavaScript theme={null}
  const chunk = file.slice(0, 16 * 1024 * 1024); // first 16 MB

  const params = new URLSearchParams({ upload: uploadToken, part: '1' });

  const response = await fetch(`https://blob.squarecloud.app/v1/objects/chunked?${params}`, {
    method: 'PUT',
    headers: {
      Authorization: 'YOUR_API_KEY',
      'Content-Type': 'application/octet-stream',
    },
    body: chunk,
  });
  ```

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

  with open('./bigfile.bin', 'rb') as f:
      chunk = f.read(16 * 1024 * 1024)

  response = requests.put(
      'https://blob.squarecloud.app/v1/objects/chunked',
      headers={'Authorization': 'YOUR_API_KEY', 'Content-Type': 'application/octet-stream'},
      params={'upload': upload_token, 'part': 1},
      data=chunk,
  )
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "response": {
      "part": 1,
      "size": 16777216,
      "etag": "\"9bb58f26192e4ba00f01e2e7b136bbd8\""
    }
  }
  ```
</ResponseExample>

### 故障排查

<Tabs>
  <Tab title="400 状态码">
    ### 分块相关

    <CodeGroup>
      ```json INVALID_UPLOAD_TOKEN theme={null}
      // The upload token is missing, malformed, or does not belong to your account.
      {
          "status": "error",
          "code": "INVALID_UPLOAD_TOKEN"
      }
      ```

      ```json INVALID_CHUNK_PART theme={null}
      // The part number must be an integer between 1 and 205.
      {
          "status": "error",
          "code": "INVALID_CHUNK_PART"
      }
      ```

      ```json EMPTY_CHUNK theme={null}
      // The chunk body was empty.
      {
          "status": "error",
          "code": "EMPTY_CHUNK"
      }
      ```
    </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="404 状态码">
    ### 未找到

    <CodeGroup>
      ```json UPLOAD_NOT_FOUND theme={null}
      // The upload was already completed, aborted, or expired.
      {
          "status": "error",
          "code": "UPLOAD_NOT_FOUND"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="413 状态码">
    ### 载荷过大

    <CodeGroup>
      ```json CHUNK_TOO_LARGE theme={null}
      // Each chunk accepts up to 32 MB.
      {
          "status": "error",
          "code": "CHUNK_TOO_LARGE"
      }
      ```
    </CodeGroup>
  </Tab>

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

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

      ```json TOO_MANY_CONCURRENT_CHUNKS theme={null}
      // At most 6 chunks may be in flight at a time. Wait for one to finish, then retry this part.
      {
          "status": "error",
          "code": "TOO_MANY_CONCURRENT_CHUNKS"
      }
      ```
    </CodeGroup>
  </Tab>

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

    <CodeGroup>
      ```json UPLOAD_FAILED theme={null}
      // Failed to upload the chunk. Retry this part.
      {
          "status": "error",
          "code": "UPLOAD_FAILED"
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>