> ## 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 オブジェクトのダウンロード

> GET /v1/objects/download で任意のファイルのダウンロードリンクを取得します: プライベートファイルには最大 24 時間の一時リンク、公開ファイルには公開 URL。

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

オブジェクトのダウンロードは、ファイルを読み取るためのリンクを返します。**プライベート**ファイルの場合は、60 秒から 24 時間有効で、認証情報なしで機能する一時リンクに署名します。**公開**ファイルの場合は公開 URL を返します。デフォルトでは `302` リダイレクトで応答するため、ブラウザや `curl -L` から直接アクセスできます。`redirect=false` を指定するとリンクを JSON で返します。`blob:read` スコープが必要です。

一時リンク (`https://files.squarecloud.dev/d/...`) は取り消すことができず、`Range` と条件付きリクエストに対応し、期限切れになったとき、またはファイルが削除、移動されたり公開範囲が変わったりしたときに機能しなくなります。取り消し、回数制限、パスワード保護が可能なリンクには、[共有リンク](/ja/blob-reference/endpoint/shares-create)を使用してください。[リンクと共有](/ja/blob-reference/links-and-sharing)を参照してください。

<ParamField query="object" type="string" required>
  ファイルの id。
</ParamField>

<ParamField query="expires" type="number" default="3600">
  一時リンクの有効期間。60〜86400 秒 (24 時間) です。
</ParamField>

<ParamField query="redirect" type="boolean" default="true">
  `false` にすると、リダイレクトせずにリンクを JSON で返します。
</ParamField>

<ParamField query="disposition" type="string">
  `inline` (ブラウザで開く) または `attachment` (ダウンロード)。指定すると、公開ファイルであっても常に一時リンクが生成されます。
</ParamField>

<ParamField query="filename" type="string" placeholder="report-september.pdf">
  ブラウザがファイルを保存する際の名前。`disposition` で別途指定しない限り `attachment` が適用され、常に一時リンクが生成されます。
</ParamField>

### レート制限

<Note>
  * このルートへのリクエストは 1 分間に 60 件 (`RATE_LIMITED`、429)。
  * 各一時リンクは IP あたり 1 分間に 60 リクエストを受け付けます。これに加えて、アカウントのすべてのリンクに全体の制限があります。超えるとリンクはプレーンテキストで `429` を返します。1 つのファイルを多くの人に渡すには、ファイルを公開してください: 公開ファイルは CDN から配信され、この制限はありません。期限切れまたは無効なリンクは `404` を返します。
</Note>

### レスポンス

`redirect=true` (デフォルト) の場合: `Location` にリンクを含み、`Cache-Control: no-store` を付けた `302`。`redirect=false` の場合:

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

<ResponseField name="response" type="object">
  <Expandable title="オブジェクトを切り替え">
    <ResponseField name="url" type="string">
      リンク: `files.squarecloud.dev` 上の一時リンク、または公開 URL。
    </ResponseField>

    <ResponseField name="expires_at" type="ISO 8601 | null">
      一時リンクの有効期限。公開 URL の場合は `null`。
    </ResponseField>

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

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

    <ResponseField name="content_type" type="string">
      ファイルの配信時の `Content-Type`。
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://blob.squarecloud.app/v1/objects/download?object=prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf&expires=600&redirect=false' \
    --header 'Authorization: YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    object: 'prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf',
    expires: '600',
    filename: 'invoice-september.pdf',
    redirect: 'false',
  });

  const res = await fetch(`https://blob.squarecloud.app/v1/objects/download?${params}`, {
    headers: { Authorization: 'YOUR_API_KEY' },
  });
  const { response } = await res.json();
  // hand response.url to the user; it works without credentials for 10 minutes
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "response": {
      "url": "https://files.squarecloud.dev/d/Rb7nKq2WvX9sLp4TzYc1Hm8JdF0gUe6AoNiQ3tVwBk5Sy.Pj3Lx9Qe2Rw7Ty4Uo",
      "expires_at": "2026-09-25T12:10:00.000Z",
      "private": true,
      "size": 88412,
      "content_type": "application/pdf"
    }
  }
  ```
</ResponseExample>

### エラー

| コード                          | HTTP | 発生する状況                                          |
| ---------------------------- | ---- | ----------------------------------------------- |
| `INVALID_OBJECT`             | 400  | `object` がない、形式が正しくない、またはあなたのものではない。            |
| `INVALID_DOWNLOAD_EXPIRES`   | 400  | `expires` が 60〜86400 の整数ではない。                   |
| `INVALID_OBJECT_DISPOSITION` | 400  | `disposition` が `inline` または `attachment` ではない。 |
| `INVALID_FILENAME`           | 400  | 無効な文字を取り除いた後、`filename` が空になった。                 |
| `OBJECT_NOT_FOUND`           | 404  | ファイルが存在しない。                                     |
| `RATE_LIMITED`               | 429  | 1 分間に 60 リクエストを超えた。                             |