> ## 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.

# Cópia de Objeto Blob

> Copie, mova ou renomeie um arquivo dentro do Blob Storage com POST /v1/objects/copy, no servidor e sem baixá-lo.

<ParamField header="Authorization" type="string" placeholder="Chave da API" required>
  A chave da API para sua conta. Você pode encontrá-la nas [configurações da conta](https://squarecloud.app/pt-br/account/security).
</ParamField>

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](/pt-br/blob-reference/endpoint/update#arquivos-legados)).

<ParamField body="source" type="string" required>
  O id do arquivo a copiar.
</ParamField>

<ParamField body="destination" type="object" required>
  Para onde vai a cópia.

  <Expandable title="propriedades">
    <ParamField body="name" type="string" required>
      O novo nome, sem extensão. Mesmo padrão do [Envio de Objeto](/pt-br/blob-reference/endpoint/post).
    </ParamField>

    <ParamField body="prefix" type="string">
      O novo prefixo. Omita para armazenar a cópia na raiz.
    </ParamField>

    <ParamField body="private" type="boolean">
      A visibilidade da cópia. Por padrão, a mesma da origem.
    </ParamField>

    <ParamField body="expire" type="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.
    </ParamField>

    <ParamField body="security_hash" type="boolean" default="false">
      Adiciona um sufixo aleatório ao novo nome. Cópias privadas sempre o recebem.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="move" type="boolean" default="false">
  `true` remove a origem depois que a cópia tem sucesso.
</ParamField>

<ParamField body="overwrite" type="boolean" default="false">
  `true` substitui um arquivo existente no destino. Caso contrário, a requisição responde `409 OBJECT_ALREADY_EXISTS`.
</ParamField>

### Limites de taxa

<Note>10 requisições a cada 10 segundos (`RATE_LIMITED`, 429).</Note>

### Resposta

<ResponseField name="status" type="string">
  "success" se bem-sucedida, "error" caso contrário.
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="Alternar objeto">
    <ResponseField name="id" type="string">
      O id do novo arquivo.
    </ResponseField>

    <ResponseField name="private" type="boolean">
      Se o novo arquivo é privado.
    </ResponseField>

    <ResponseField name="url" type="string | null">
      A URL pública do novo arquivo, ou `null` quando privado.
    </ResponseField>

    <ResponseField name="expires_at" type="ISO 8601">
      Quando o novo arquivo será excluído. Presente apenas quando ele expira.
    </ResponseField>

    <ResponseField name="size" type="number">
      O tamanho do arquivo, em bytes.
    </ResponseField>

    <ResponseField name="source" type="string">
      O id da origem.
    </ResponseField>

    <ResponseField name="moved" type="boolean">
      Se a origem foi removida.
    </ResponseField>

    <ResponseField name="replaced" type="boolean">
      Se um arquivo existente no destino foi substituído.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash Renomear theme={null}
  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
    }'
  ```

  ```javascript JavaScript theme={null}
  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,
    }),
  });
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "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
    }
  }
  ```
</ResponseExample>

### 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. |