上传文件到 Blob Storage

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images&security_hash=true' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./logo.png'

import fs from 'node:fs';

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

const params = new URLSearchParams({
  name: 'logo',
  prefix: 'images',
  security_hash: 'true',
});

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

import requests

with open('logo.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'logo', 'prefix': 'images', 'security_hash': 'true'},
        files={'file': ('logo.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "private": false,
        "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "size": 416230,
        "name": "logo",
        "prefix": "images",
        "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
        "replaced": false
    }
}

{
    "status": "success",
    "response": {
        "id": "prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf",
        "private": true,
        "url": null,
        "size": 88412,
        "name": "2026-09",
        "prefix": "invoices",
        "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
        "replaced": false
    }
}

string

必填

你账户的 API 密钥。你可以在账户设置中找到它。

对象上传会上传一个文件，并返回其 id，对于公开文件还会返回一个可直接嵌入或分享的 CDN url。它为托管在平台上的应用提供附件、生成的导出文件和用户上传媒体的存储支撑。单个请求接受 512 字节到 100 MB 的文件。更大的文件（最大 10 GiB）请走分块上传流程或 S3 网关。需要 blob:write scope，或在 Authorization 中发送的上传令牌，以及有效计划。

请将返回的 id 视为不透明值：原样保存，并在调用其他路由时原样传回。它以 pub/ 或 prv/ 开头，并可能在文件的可见性或过期时间改变时发生变化。2026 年 9 月更新之前存储的旧版文件保留不带该前缀的 id，所有路由都同时接受这两种形式。

参数

file

必填

使用 FormData（multipart/form-data），每个请求恰好一个文件。
请发送真实的文件名：存储的扩展名来自文件名（reads.fastq.gz 保持为 .fastq.gz）。

string

必填

文件名，不含扩展名。1 到 128 个字符：字母、数字、_、. 和 -，并以字母、数字或 _ 开头。不能包含 ..。

string

文件所在的文件夹路径，最多 8 个以 / 分隔的路径段，总长不超过 256 个字符。每个路径段遵循与 name 相同的模式，最多 64 个字符。末尾的 / 会被忽略。

boolean

默认值:"false"

true 表示存储的文件没有公开 URL。可通过对象下载、分享链接或 S3 网关读取。省略时由该前缀的规则决定。

string

在此时间后自动删除文件：30 或 30d 表示天数，6h 表示小时数。范围为 1 小时到 1825 天（5 年）。7 天以内的过期时间需要 Enterprise 计划。省略时由该前缀的规则决定。

boolean

默认值:"false"

true 会在名称后添加一个随机后缀，使 URL 无法被猜到，且新的上传永远不会替换旧文件。私有文件始终带有该后缀（false 与 private=true 同时使用会被拒绝）。

boolean

默认值:"true"

没有安全哈希时，名称和前缀相同的新上传会替换原文件。设为 false 则会拒绝上传并返回 409 OBJECT_ALREADY_EXISTS。

string

inline（在浏览器中打开）或 attachment（以原始文件名下载）。

boolean

默认值:"false"

true 会让浏览器下载该文件而不是打开它，无论文件类型如何。

string

CDN 和浏览器保留该文件的时长：immutable（1 年）、max-age=N（N 为 60 到 31536000 秒），或 no-cache（每次读取都访问存储；仅限 Enterprise）。带有安全哈希的文件默认为 immutable。缓存时长绝不会超过文件的过期时间。

string

一个值为字符串的 JSON 对象，由对象信息返回。键使用 a-z、0-9 和 -（最多 64 个字符）。最多 5 个键，总共 512 字节。仅限 Pro 和 Enterprise。

string

文件的 SHA-256。不匹配时，上传会被拒绝并返回 CHECKSUM_MISMATCH，不会存储任何内容。

速率限制与并发

每个账户同一时间最多可有 4 个正在进行的上传（TOO_MANY_CONCURRENT_UPLOADS，429）。
Hobby 和 Standard 计划限制为每秒 1 次上传（RATE_LIMITED，429）。Pro 和 Enterprise 不受此限制。
超出账户内置存储配额的上传会被拒绝并返回 STORAGE_QUOTA_EXCEEDED。

文件类型

实际上任何扩展名都可以接受，包括没有注册 MIME 类型的格式（.bam、.vcf、.fasta、.parquet、.h5、.npy 等）。

分发时的 Content-Type 由服务器端根据扩展名推导。未知格式以 application/octet-stream 分发。
浏览器会渲染的格式（.html、.svg、.xml 及类似格式）始终以下载方式分发。
可执行文件和安装程序会被拒绝并返回 BLOCKED_FILE_TYPE：exe、msi、dll、bat、cmd、com、scr、cpl、pif、hta、vbs、vbe、jse、wsf、wsh、msc、reg、lnk、sys、drv、ps1、apk、xpi。
该前缀的规则或上传令牌可以限制可接受的扩展名和大小。

响应

string

成功为 “success”，否则为 “error”。

object

显示展开对象

string

对象 id：pub/<user_id>/<path> 或 prv/<user_id>/<path>。请将其视为不透明值。

boolean

文件是否为私有。

string | null

公开 CDN URL（https://blob.squarecloud.dev/pub/...），私有文件为 null。

ISO 8601

文件将被删除的时间。仅当文件会过期时出现。

number

文件大小，单位为字节。

string

请求中发送的名称。

string

前缀，仅当请求中发送了前缀时出现。

string

已存储文件的 SHA-256，十六进制表示。

boolean

当本次上传替换了同名的现有文件时为 true。

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images&security_hash=true' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./logo.png'

import fs from 'node:fs';

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

const params = new URLSearchParams({
  name: 'logo',
  prefix: 'images',
  security_hash: 'true',
});

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

import requests

with open('logo.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'logo', 'prefix': 'images', 'security_hash': 'true'},
        files={'file': ('logo.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "private": false,
        "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "size": 416230,
        "name": "logo",
        "prefix": "images",
        "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
        "replaced": false
    }
}

{
    "status": "success",
    "response": {
        "id": "prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf",
        "private": true,
        "url": null,
        "size": 88412,
        "name": "2026-09",
        "prefix": "invoices",
        "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
        "replaced": false
    }
}

错误

代码	HTTP	触发情况
`INVALID_OBJECT_NAME` / `INVALID_OBJECT_PREFIX`	400	`name` 或 `prefix` 不符合模式。
`INVALID_OBJECT_EXPIRE`	400	`expire` 不是 1 小时到 1825 天之间的时长。
`INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_OVERWRITE` / `INVALID_STORAGE_AUTO_DOWNLOAD`	400	该标志不是 `true` 或 `false`。
`INVALID_OBJECT_SECURITY_HASH`	400	不是布尔值，或在私有文件上为 `false`。
`INVALID_OBJECT_DISPOSITION` / `INVALID_OBJECT_CACHE_CONTROL` / `INVALID_OBJECT_METADATA` / `INVALID_CHECKSUM`	400	值不属于可接受的形式。
`INVALID_FILE` / `INVALID_FILE_TYPE` / `BLOCKED_FILE_TYPE` / `FILE_TYPE_NOT_ALLOWED`	400	文件部分缺失，其扩展名格式错误或被屏蔽，或者规则或令牌不允许该扩展名。
`FILE_TOO_SMALL`	400	文件小于 512 字节。
`CHECKSUM_MISMATCH`	400	文件与 `checksum_sha256` 不匹配。未存储任何内容。
`PERMISSION_DENIED`	401	账户没有有效计划。
`UPLOAD_TOKEN_USED`	401	上传令牌已没有剩余使用次数。已过期的令牌返回 `ACCESS_DENIED`。
`STORAGE_QUOTA_EXCEEDED`	403	本次上传将超出内置存储配额。
`PREFIX_NOT_ALLOWED`	403	上传令牌绑定的是另一个前缀。
`UPGRADE_REQUIRED`	403	某个选项需要更高级别的计划。`message` 会说明是哪个计划。
`ACCOUNT_BLOCKED`	403	该账户已被禁止存储文件。
`INVALID_CONTENT_TYPE`	409	请求不是 `multipart/form-data`。
`OBJECT_ALREADY_EXISTS`	409	该名称已存在，且 `overwrite=false`。
`FILE_TOO_LARGE`	413	超过 100 MB，或超过规则或令牌允许的大小。
`RATE_LIMITED` / `TOO_MANY_CONCURRENT_UPLOADS`	429	每秒 1 次上传（Hobby 和 Standard），或已有 4 个上传正在进行。
`UPLOAD_FAILED`	500	存储失败。请重试。
`PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE`	503	存储暂时不可用。请重试。

完整列表请参见错误。

入门

对象

分块上传

账户

分享链接

S3

上传文件到 Blob Storage

参数

速率限制与并发

文件类型

响应

错误

相关内容

​参数

​速率限制与并发

​文件类型

​响应

​错误

​相关内容

参数

速率限制与并发

文件类型

响应

错误

相关内容