> ## 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 端点。

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

<ParamField body="file" type="file" placeholder="myphone.png" required>
  使用 FormData。（multipart/form-data）
</ParamField>

<ParamField query="name" type="string" placeholder="File Name" required>
  表示文件名称的字符串。（不含扩展名）<br />必须符合 a 到 z、A 到 Z、0 到 9 以及 \_ 的模式。（3 到 32 个字符）
</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)">
  表示文件过期周期的数字，范围为 1 到 365 天。
</ParamField>

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

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

### 速率限制与并发

<Note>
  上传需要付费套餐。

  * **Hobby** 和 **Standard** 套餐限制为**每秒 1 次上传**。
  * **Pro** 和 **Enterprise** 套餐**不**受每秒限制约束，取而代之的是最多可**同时进行 4 次上传**。

  在所有付费套餐中，一个账户最多可**同时进行 4 次上传**。当已有 4 次上传仍在进行时再启动一次上传，将返回 `TOO_MANY_CONCURRENT_UPLOADS`（429）。
</Note>

<Info>
  出于安全考虑，`.html` 和 `.svg` 文件始终以下载方式提供（作为 `application/octet-stream` 提供），而不是内联渲染。
</Info>

### 响应

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

<ResponseField name="response" type="object">
  <Expandable title="展开对象">
    <ResponseField name="id" type="string">
      已上传文件的 ID。
    </ResponseField>

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

    <ResponseField name="prefix" type="string">
      文件所存储的前缀（回显自 `prefix` 查询参数；未发送时省略）。
    </ResponseField>

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

    <ResponseField name="url" type="string">
      已上传文件的 URL。（文件通过 Square Cloud CDN 分发）
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://blob.squarecloud.app/v1/objects?name=myfile&prefix=images&expire=30' \
    --header 'Authorization: YOUR_API_KEY' \
    --form 'file=@./myphone.png'
  ```

  ```javascript JavaScript theme={null}
  import fs from 'node:fs';

  const form = new FormData();
  form.append('file', new Blob([fs.readFileSync('./myphone.png')]), 'myphone.png');

  const params = new URLSearchParams({
    name: 'myfile',
    prefix: 'images',
    expire: '30',
  });

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

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

  with open('myphone.png', 'rb') as f:
      response = requests.post(
          'https://blob.squarecloud.app/v1/objects',
          headers={'Authorization': 'YOUR_API_KEY'},
          params={'name': 'myfile', 'prefix': 'images', 'expire': 30},
          files={'file': ('myphone.png', f, 'image/png')},
      )
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
      "status": "success",
      "response": {
          "id": "3155597145698959364/images/test_lxch4k7y-07ee.png",
          "name": "test",
          "prefix": "images",
          "size": 416230,
          "url": "https://public-blob.squarecloud.dev/3155597145698959364/images/test_lxch4k7y-07ee.png"
      }
  }
  ```
</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 1 to 365. (value in days).
      {
          "status": "error",
          "code": "INVALID_OBJECT_EXPIRE"
      }
      ```

      ```json SECURITY_HASH theme={null}
      // The provided security hash boolean is invalid.
      // Just set to true or false. 😅
      {
          "status": "error",
          "code": "INVALID_OBJECT_SECURITY_HASH"
      }
      ```

      ```json AUTO_DOWNLOAD theme={null}
      // The provided auto-download boolean is invalid.
      // Just set to true or false. 😅
      {
          "status": "error",
          "code": "INVALID_STORAGE_AUTO_DOWNLOAD"
      }
      ```
    </CodeGroup>

    ### 文件相关

    <Info>当前文件大小上限为 100MB。未来我们计划将其提升至 10GB。目前受技术和负载均衡的限制，上限为 100MB。</Info>

    <CodeGroup>
      ```json INVALID_FILE theme={null}
      // The provided file is invalid.
      {
          "status": "error",
          "code": "INVALID_FILE"
      }
      ```

      ```json FILETYPE theme={null}
      // The provided file type is invalid.
      {
          "status": "error",
          "code": "INVALID_FILETYPE"
      }
      ```

      ```json FILE_TOO_SMALL theme={null}
      // The file size is too small (< 1kb).
      {
          "status": "error",
          "code": "FILE_TOO_SMALL"
      }
      ```
    </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.
      // Also returned when the account is on the free plan — uploading requires a paid plan.
      {
          "status": "error",
          "code": "ACCESS_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="409 状态码">
    ### 无效的内容类型

    <CodeGroup>
      ```json INVALID_CONTENT_TYPE theme={null}
      // This route only accepts multipart/form-data requests.
      {
          "status": "error",
          "code": "INVALID_CONTENT_TYPE"
      }
      ```
    </CodeGroup>
  </Tab>

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

    <Info>当前文件大小上限为 100MB。</Info>

    <CodeGroup>
      ```json PAYLOAD_TOO_LARGE theme={null}
      // The uploaded file exceeds the maximum allowed size of 100 MB.
      {
          "status": "error",
          "code": "PAYLOAD_TOO_LARGE"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="429 状态码">
    ### 触发速率限制

    <CodeGroup>
      ```json RATELIMIT theme={null}
      // Per-second upload limit reached (Hobby/Standard: max 1 upload per second).
      {
          "status": "error",
          "code": "RATELIMIT"
      }
      ```

      ```json TOO_MANY_CONCURRENT_UPLOADS theme={null}
      // Too many simultaneous uploads (max 4 in progress at a time per account).
      {
          "status": "error",
          "code": "TOO_MANY_CONCURRENT_UPLOADS"
      }
      ```
    </CodeGroup>
  </Tab>

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

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