Blob 上传令牌

POST

upload-tokens

// Your backend: mint a token for the signed-in user and return it to the page.
const res = await fetch('https://blob.squarecloud.app/v1/upload-tokens', {
  method: 'POST',
  headers: {
    Authorization: process.env.SQUARE_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prefix: `avatars/${userId}`,
    allowed_extensions: ['png', 'jpg', 'webp'],
    max_size: 2 * 1024 * 1024,
    expires_in: 300,
  }),
});
const { response } = await res.json();
// send response.token to the browser

const form = new FormData();
form.append('file', input.files[0]);

const res = await fetch('https://blob.squarecloud.app/v1/objects?name=avatar', {
  method: 'POST',
  headers: { Authorization: token },
  body: form,
});
const { response } = await res.json();
// response.url is the public URL of the new file

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/upload-tokens' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "prefix": "avatars", "allowed_extensions": ["png", "jpg"], "max_size": 2097152 }'

{
  "status": "success",
  "response": {
    "token": "squp_Tq7xLm2Vb9Rk4Wz1Nc8Hy5Js0Gd3Fp6Ae.Hq3mZ8vT1kLw9xRb",
    "expires_at": "2026-09-25T12:15:00.000Z",
    "max_uses": 1
  }
}

string

必填

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

上传令牌让你的服务器签发一个短期令牌，供浏览器或移动应用直接上传到 Blob Storage。文件永远不会经过你的服务器，你的 API key 也永远不会离开服务器。需要 blob:write scope 和付费计划。该令牌放在对象上传或分块上传路由的 Authorization 请求头中，在其他任何地方都无法使用（403 UPLOAD_TOKEN_NOT_ALLOWED）。签发时设置的所有内容都会被锁定：浏览器无法更改名称、前缀、可见性、过期时间或元数据，也无法发送更大的文件或使用其他文件类型。

每次上传消耗一次使用次数：一次对象上传调用，或开启一次分块上传（其分块和完成操作不会额外消耗）。
未指定 name 时，由浏览器选择名称，且名称始终带有安全哈希，因此泄露的令牌永远无法替换你已有的文件。
当使用次数用尽（401 UPLOAD_TOKEN_USED）、令牌过期或签发它的 API key 被撤销（401 ACCESS_DENIED）时，令牌即失效。

string

锁定文件名。未指定时，由浏览器在查询参数中发送 name。

string

锁定前缀。发送了不同前缀的浏览器会收到 403 PREFIX_NOT_ALLOWED。

boolean

锁定可见性。

boolean

仅与 name 一起使用：false 允许上传替换该名称的文件。否则名称始终带有哈希。

string | null

锁定过期时间（30d、6h），null 表示不过期。7 天以内需要 Enterprise。

number

最大文件大小（字节），范围为 512 到 10737418240（10 GiB）。

string[]

可接受的扩展名，1 到 20 个，小写且不带点（png、tar.gz）。

object

添加到通过该令牌上传的每个文件上的元数据。仅限 Pro 和 Enterprise。

number

默认值:"900"

令牌的有效时长，范围为 60 到 3600 秒。

number

默认值:"1"

令牌允许的上传次数，范围为 1 到 100。

速率限制

每分钟 120 个令牌（RATE_LIMITED，429）。签发令牌不会存储任何内容，因此为每个终端用户的每次上传签发一个令牌完全没有问题。

响应

string

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

object

显示展开对象

string

上传令牌（squp_...）。将它交给浏览器。

ISO 8601

令牌的过期时间。

number

令牌允许的上传次数。

// Your backend: mint a token for the signed-in user and return it to the page.
const res = await fetch('https://blob.squarecloud.app/v1/upload-tokens', {
  method: 'POST',
  headers: {
    Authorization: process.env.SQUARE_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prefix: `avatars/${userId}`,
    allowed_extensions: ['png', 'jpg', 'webp'],
    max_size: 2 * 1024 * 1024,
    expires_in: 300,
  }),
});
const { response } = await res.json();
// send response.token to the browser

const form = new FormData();
form.append('file', input.files[0]);

const res = await fetch('https://blob.squarecloud.app/v1/objects?name=avatar', {
  method: 'POST',
  headers: { Authorization: token },
  body: form,
});
const { response } = await res.json();
// response.url is the public URL of the new file

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/upload-tokens' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "prefix": "avatars", "allowed_extensions": ["png", "jpg"], "max_size": 2097152 }'

{
  "status": "success",
  "response": {
    "token": "squp_Tq7xLm2Vb9Rk4Wz1Nc8Hy5Js0Gd3Fp6Ae.Hq3mZ8vT1kLw9xRb",
    "expires_at": "2026-09-25T12:15:00.000Z",
    "max_uses": 1
  }
}

错误

代码	HTTP	触发情况
`INVALID_BODY`	400	请求体不是 JSON 对象。
`INVALID_OBJECT_NAME` / `INVALID_OBJECT_PREFIX` / `INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_SECURITY_HASH` / `INVALID_OBJECT_EXPIRE` / `INVALID_OBJECT_METADATA`	400	某个锁定的值无效。
`INVALID_MAX_SIZE` / `INVALID_ALLOWED_EXTENSIONS` / `INVALID_EXPIRES_IN` / `INVALID_MAX_USES`	400	某个限制超出范围。
`UPLOAD_TOKEN_TOO_LARGE`	400	单个令牌的选项过多。请缩短元数据或扩展名列表。
`PERMISSION_DENIED`	401	账户没有有效的付费计划。
`UPGRADE_REQUIRED`	403	该过期时间或元数据需要更高级别的计划。
`RATE_LIMITED`	429	一分钟内超过 120 个令牌。

浏览器上传时可能出现：401 UPLOAD_TOKEN_USED（次数用尽）、401 ACCESS_DENIED（已过期或已撤销）、403 PREFIX_NOT_ALLOWED（前缀不同）、400 FILE_TYPE_NOT_ALLOWED（扩展名不被允许）以及 413 FILE_TOO_LARGE（超过 max_size）。

// Your backend: mint a token for the signed-in user and return it to the page.
const res = await fetch('https://blob.squarecloud.app/v1/upload-tokens', {
  method: 'POST',
  headers: {
    Authorization: process.env.SQUARE_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prefix: `avatars/${userId}`,
    allowed_extensions: ['png', 'jpg', 'webp'],
    max_size: 2 * 1024 * 1024,
    expires_in: 300,
  }),
});
const { response } = await res.json();
// send response.token to the browser

const form = new FormData();
form.append('file', input.files[0]);

const res = await fetch('https://blob.squarecloud.app/v1/objects?name=avatar', {
  method: 'POST',
  headers: { Authorization: token },
  body: form,
});
const { response } = await res.json();
// response.url is the public URL of the new file

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/upload-tokens' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "prefix": "avatars", "allowed_extensions": ["png", "jpg"], "max_size": 2097152 }'

{
  "status": "success",
  "response": {
    "token": "squp_Tq7xLm2Vb9Rk4Wz1Nc8Hy5Js0Gd3Fp6Ae.Hq3mZ8vT1kLw9xRb",
    "expires_at": "2026-09-25T12:15:00.000Z",
    "max_uses": 1
  }
}

入门

对象

分块上传

账户

分享链接

S3

速率限制

响应

错误

​速率限制

​响应

​错误

速率限制

响应

错误