Blob 对象复制
通过 POST /v1/objects/copy 在 Blob Storage 内部复制、移动或重命名文件，在服务器端完成，无需下载。
POST
/
v1
/
objects
/
copy
curl --request POST \
--url 'https://blob.squarecloud.app/v1/objects/copy' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"source": "pub/3155597145698959364/uploads/IMG_2041.png",
"destination": { "name": "cover", "prefix": "posts/launch" },
"move": true
}'
const response = await fetch('https://blob.squarecloud.app/v1/objects/copy', {
method: 'POST',
headers: {
Authorization: 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
source: 'pub/3155597145698959364/uploads/IMG_2041.png',
destination: { name: 'cover', prefix: 'posts/launch' },
move: true,
}),
});
{
"status": "success",
"response": {
"id": "pub/3155597145698959364/posts/launch/cover.png",
"private": false,
"url": "https://blob.squarecloud.dev/pub/3155597145698959364/posts/launch/cover.png",
"size": 416230,
"source": "pub/3155597145698959364/uploads/IMG_2041.png",
"moved": true,
"replaced": false
}
}
对象复制会以新的名称、前缀或可见性复制一个文件，完全在服务器上完成：没有任何字节经过你的应用。设置
move: true 时，源文件会在之后被删除，这就是重命名或移动文件的方式。需要 blob:write scope 和付费计划。
- 副本会保留源文件的扩展名、内容类型、缓存、disposition 和元数据。
- 复制会计入你的存储配额；移动则不会。
- 目标始终使用当前的存储，因此移动也是将 2026 年 9 月更新之前存储的旧版文件转换为新格式的方式（参见对象更新）。
string
必填
要复制的文件的 id。
object
必填
boolean
默认值:"false"
true 会在复制成功后删除源文件。boolean
默认值:"false"
true 会替换目标位置已存在的文件。否则请求返回 409 OBJECT_ALREADY_EXISTS。速率限制
每 10 秒 10 次请求（
RATE_LIMITED，429）。响应
string
成功为 “success”，否则为 “error”。
object
curl --request POST \
--url 'https://blob.squarecloud.app/v1/objects/copy' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"source": "pub/3155597145698959364/uploads/IMG_2041.png",
"destination": { "name": "cover", "prefix": "posts/launch" },
"move": true
}'
const response = await fetch('https://blob.squarecloud.app/v1/objects/copy', {
method: 'POST',
headers: {
Authorization: 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
source: 'pub/3155597145698959364/uploads/IMG_2041.png',
destination: { name: 'cover', prefix: 'posts/launch' },
move: true,
}),
});
{
"status": "success",
"response": {
"id": "pub/3155597145698959364/posts/launch/cover.png",
"private": false,
"url": "https://blob.squarecloud.dev/pub/3155597145698959364/posts/launch/cover.png",
"size": 416230,
"source": "pub/3155597145698959364/uploads/IMG_2041.png",
"moved": true,
"replaced": false
}
}
错误
| 代码 | HTTP | 触发情况 |
|---|---|---|
INVALID_OBJECT | 400 | source 缺失、格式错误或不属于你。 |
INVALID_OBJECT_NAME / INVALID_OBJECT_PREFIX | 400 | 目标名称或前缀不符合模式。 |
INVALID_DESTINATION | 400 | private 或 security_hash 不是布尔值。 |
INVALID_OBJECT_EXPIRE | 400 | expire 不是 1 小时到 1825 天之间的时长。 |
INVALID_OBJECT_SECURITY_HASH | 400 | 在私有副本上设置了 security_hash: false。 |
SAME_OBJECT | 400 | 目标就是源文件。 |
PERMISSION_DENIED | 401 | 账户没有有效的付费计划。 |
UPGRADE_REQUIRED | 403 | 该过期时间需要更高级别的计划。 |
STORAGE_QUOTA_EXCEEDED | 403 | 本次复制将超出内置存储配额。 |
OBJECT_NOT_FOUND | 404 | 源文件不存在。 |
OBJECT_ALREADY_EXISTS | 409 | 目标位置已存在文件，且 overwrite 不为 true。 |
RATE_LIMITED | 429 | 10 秒内超过 10 次请求。 |
COPY_FAILED | 500 | 复制失败。请重试。 |
PRIVATE_STORAGE_UNAVAILABLE / PUBLIC_STORAGE_UNAVAILABLE | 503 | 存储暂时不可用。请重试。 |
⌘I
curl --request POST \
--url 'https://blob.squarecloud.app/v1/objects/copy' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"source": "pub/3155597145698959364/uploads/IMG_2041.png",
"destination": { "name": "cover", "prefix": "posts/launch" },
"move": true
}'
const response = await fetch('https://blob.squarecloud.app/v1/objects/copy', {
method: 'POST',
headers: {
Authorization: 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
source: 'pub/3155597145698959364/uploads/IMG_2041.png',
destination: { name: 'cover', prefix: 'posts/launch' },
move: true,
}),
});
{
"status": "success",
"response": {
"id": "pub/3155597145698959364/posts/launch/cover.png",
"private": false,
"url": "https://blob.squarecloud.dev/pub/3155597145698959364/posts/launch/cover.png",
"size": 416230,
"source": "pub/3155597145698959364/uploads/IMG_2041.png",
"moved": true,
"replaced": false
}
}