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

# Blob オブジェクトのコピー

> POST /v1/objects/copy で、ダウンロードせずにサーバー側で Blob Storage 内のファイルをコピー、移動、名前変更します。

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  アカウントの API キーです。これは[アカウント設定](https://squarecloud.app/ja/account/security)で確認できます。
</ParamField>

オブジェクトのコピーは、ファイルを新しい名前、プレフィックス、または公開範囲で複製します。処理はすべてサーバー上で行われ、アプリケーションを経由するバイトはありません。`move: true` を指定するとその後コピー元が削除されます。これがファイルの**名前変更**や**移動**の方法です。`blob:write` スコープと有料プランが必要です。

* コピーはコピー元の拡張子、コンテンツタイプ、キャッシュ、disposition、メタデータを保持します。
* コピーはストレージ枠にカウントされますが、移動はカウントされません。
* コピー先は常に現在のストレージを使用するため、移動は2026年9月のアップデート以前に保存されたレガシーファイルを新しい形式に移行する方法でもあります ([オブジェクトの更新](/ja/blob-reference/endpoint/update#レガシーファイル)を参照)。

<ParamField body="source" type="string" required>
  コピーするファイルの id。
</ParamField>

<ParamField body="destination" type="object" required>
  コピー先。

  <Expandable title="properties">
    <ParamField body="name" type="string" required>
      拡張子を除いた新しい名前。[オブジェクトのアップロード](/ja/blob-reference/endpoint/post)と同じパターンです。
    </ParamField>

    <ParamField body="prefix" type="string">
      新しいプレフィックス。省略するとコピーはルートに保存されます。
    </ParamField>

    <ParamField body="private" type="boolean">
      コピーの公開範囲。デフォルトはコピー元と同じです。
    </ParamField>

    <ParamField body="expire" type="string | null">
      現在時刻から数えた新しい有効期限 (`30d`、`6h`)。`null` にすると有効期限が削除されます。省略するとコピー元の有効期限の日時が保持されます。
    </ParamField>

    <ParamField body="security_hash" type="boolean" default="false">
      新しい名前にランダムな接尾辞を追加します。プライベートなコピーには常に付与されます。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="move" type="boolean" default="false">
  `true` にすると、コピーが成功した後にコピー元が削除されます。
</ParamField>

<ParamField body="overwrite" type="boolean" default="false">
  `true` にすると、コピー先の既存ファイルを置き換えます。それ以外の場合、リクエストは `409 OBJECT_ALREADY_EXISTS` を返します。
</ParamField>

### レート制限

<Note>10 秒間に 10 リクエスト (`RATE_LIMITED`、429)。</Note>

### レスポンス

<ResponseField name="status" type="string">
  成功した場合は "success"、失敗した場合は "error" です。
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="オブジェクトを切り替え">
    <ResponseField name="id" type="string">
      新しいファイルの id。
    </ResponseField>

    <ResponseField name="private" type="boolean">
      新しいファイルがプライベートかどうか。
    </ResponseField>

    <ResponseField name="url" type="string | null">
      新しいファイルの公開 URL。プライベートの場合は `null`。
    </ResponseField>

    <ResponseField name="expires_at" type="ISO 8601">
      新しいファイルが削除される日時。有効期限がある場合のみ含まれます。
    </ResponseField>

    <ResponseField name="size" type="number">
      ファイルのサイズ (バイト)。
    </ResponseField>

    <ResponseField name="source" type="string">
      コピー元の id。
    </ResponseField>

    <ResponseField name="moved" type="boolean">
      コピー元が削除されたかどうか。
    </ResponseField>

    <ResponseField name="replaced" type="boolean">
      コピー先の既存ファイルが置き換えられたかどうか。
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash 名前変更 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>

### エラー

| コード                                                          | 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  | ストレージが一時的に利用できない。再試行してください。                |