Cópia de Objeto Blob

POST

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
  }
}

string

obrigatório

A chave da API para sua conta. Você pode encontrá-la nas configurações da conta.

A Cópia de Objeto duplica um arquivo com um novo nome, prefixo ou visibilidade, inteiramente no servidor: nenhum byte passa pela sua aplicação. Com move: true a origem é removida em seguida, e é assim que você renomeia ou move um arquivo. Exige o escopo blob:write e um plano pago.

A cópia mantém a extensão, o content type, o cache, a disposition e os metadados da origem.
Uma cópia conta na sua cota de armazenamento; uma movimentação não.
O destino sempre usa o armazenamento atual, então mover também é a forma de levar um arquivo legado, armazenado antes da atualização de setembro de 2026, para o novo formato (veja Atualização de Objeto).

string

obrigatório

O id do arquivo a copiar.

object

obrigatório

Para onde vai a cópia.

Mostrar propriedades

string

obrigatório

O novo nome, sem extensão. Mesmo padrão do Envio de Objeto.

string

O novo prefixo. Omita para armazenar a cópia na raiz.

boolean

A visibilidade da cópia. Por padrão, a mesma da origem.

string | null

Uma nova expiração contada a partir de agora (30d, 6h). null a remove. Omita para manter a data de expiração da origem.

boolean

padrão:"false"

Adiciona um sufixo aleatório ao novo nome. Cópias privadas sempre o recebem.

boolean

padrão:"false"

true remove a origem depois que a cópia tem sucesso.

boolean

padrão:"false"

true substitui um arquivo existente no destino. Caso contrário, a requisição responde 409 OBJECT_ALREADY_EXISTS.

Limites de taxa

10 requisições a cada 10 segundos (RATE_LIMITED, 429).

Resposta

string

“success” se bem-sucedida, “error” caso contrário.

object

Mostrar Alternar objeto

string

O id do novo arquivo.

boolean

Se o novo arquivo é privado.

string | null

A URL pública do novo arquivo, ou null quando privado.

ISO 8601

Quando o novo arquivo será excluído. Presente apenas quando ele expira.

number

O tamanho do arquivo, em bytes.

string

O id da origem.

boolean

Se a origem foi removida.

boolean

Se um arquivo existente no destino foi substituído.

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
  }
}

Erros

Código	HTTP	Quando
`INVALID_OBJECT`	400	`source` está ausente, malformado ou não é seu.
`INVALID_OBJECT_NAME` / `INVALID_OBJECT_PREFIX`	400	O nome ou o prefixo do destino não corresponde ao padrão.
`INVALID_DESTINATION`	400	`private` ou `security_hash` não é um booleano.
`INVALID_OBJECT_EXPIRE`	400	`expire` não é uma duração de 1 hora a 1825 dias.
`INVALID_OBJECT_SECURITY_HASH`	400	`security_hash: false` em uma cópia privada.
`SAME_OBJECT`	400	O destino é a própria origem.
`PERMISSION_DENIED`	401	A conta não tem um plano pago ativo.
`UPGRADE_REQUIRED`	403	A expiração exige um plano superior.
`STORAGE_QUOTA_EXCEEDED`	403	A cópia ultrapassaria o armazenamento incluído.
`OBJECT_NOT_FOUND`	404	A origem não existe.
`OBJECT_ALREADY_EXISTS`	409	Já existe um arquivo no destino e `overwrite` não é `true`.
`RATE_LIMITED`	429	Mais de 10 requisições em 10 segundos.
`COPY_FAILED`	500	A cópia falhou. Tente novamente.
`PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE`	503	O armazenamento está temporariamente indisponível. Tente novamente.

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
  }
}

Primeiros Passos

Objetos

Uploads em Partes

Conta

Links de Compartilhamento

S3

Limites de taxa

Resposta

Erros

​Limites de taxa

​Resposta

​Erros

Limites de taxa

Resposta

Erros