> ## 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/info 读取单个文件的详细信息：大小、内容类型、过期时间、可见性、缓存、原始名称和元数据。

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  你账户的 API 密钥。你可以在[账户设置](https://squarecloud.app/zh/account/security)中找到它。
</ParamField>

对象信息会返回 Blob Storage 所掌握的关于单个文件的全部信息，而无需下载该文件：大小、内容类型、过期时间、可见性、分发时使用的响应头、原始文件名以及你的元数据。需要 `blob:read` scope。

<ParamField query="object" type="string" required>
  文件的 id。
</ParamField>

### 速率限制

<Note>每分钟 60 次请求（`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="size" type="number">
      大小，单位为字节。
    </ResponseField>

    <ResponseField name="content_type" type="string">
      分发文件时使用的 `Content-Type`，由其扩展名推导。
    </ResponseField>

    <ResponseField name="etag" type="string">
      ETag。内容改变时它也会改变。
    </ResponseField>

    <ResponseField name="created_at" type="ISO 8601">
      文件的写入时间。更改可见性、过期时间或响应头会重写文件并重置此日期。
    </ResponseField>

    <ResponseField name="expires_at" type="ISO 8601 | null">
      文件将被删除的时间，或 `null`。
    </ResponseField>

    <ResponseField name="private" type="boolean">
      文件是否为私有。
    </ResponseField>

    <ResponseField name="url" type="string | null">
      公开 URL，私有文件为 `null`。
    </ResponseField>

    <ResponseField name="cache_control" type="string | null">
      `Cache-Control` 响应头，使用 CDN 默认值时为 `null`。
    </ResponseField>

    <ResponseField name="content_disposition" type="string | null">
      `Content-Disposition` 响应头，或 `null`。
    </ResponseField>

    <ResponseField name="original_name" type="string | null">
      上传时的文件名。
    </ResponseField>

    <ResponseField name="metadata" type="object">
      你的元数据，以字符串键值对表示。
    </ResponseField>

    <ResponseField name="legacy" type="boolean">
      对于 2026 年 9 月更新之前存储的旧版文件为 `true`。
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://blob.squarecloud.app/v1/objects/info?object=pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png' \
    --header 'Authorization: YOUR_API_KEY'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "response": {
      "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
      "size": 416230,
      "content_type": "image/png",
      "etag": "\"9bb58f26192e4ba00f01e2e7b136bbd8\"",
      "created_at": "2026-09-25T12:00:00.000Z",
      "expires_at": null,
      "private": false,
      "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
      "cache_control": "public, max-age=31536000, immutable",
      "content_disposition": null,
      "original_name": "logo.png",
      "metadata": { "campaign": "spring" },
      "legacy": false
    }
  }
  ```
</ResponseExample>

### 错误

| 代码                 | HTTP | 触发情况                   |
| ------------------ | ---- | ---------------------- |
| `INVALID_OBJECT`   | 400  | `object` 缺失、格式错误或不属于你。 |
| `OBJECT_NOT_FOUND` | 404  | 文件不存在。                 |
| `RATE_LIMITED`     | 429  | 一分钟内超过 60 次请求。         |