> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 文件

> 为二维码上传 PDF、图片、视频和 Logo。

> [!NOTE]
>
> GetQR API 目前处于 Beta 阶段，仅向部分工作区开放。正式发布前，细节可能会有所变化。

PDF、Image 和 Video 二维码都指向一个文件，自定义 Logo 也是文件。上传分两步：先注册文件以获取 URL，再将文件内容发送到该 URL。

| 方法 | 路径 | 说明 |
| - | - | - |
| `POST` | `/api/v1/files` | [注册文件上传](#注册文件上传) |

## 上传文件

**1. 注册文件**

调用[注册文件上传](#注册文件上传)，并提供文件的 `target`、`contentType` 和 `size`。`target` 决定可接受的内容类型和大小上限。您会获得一个 `fileId` 和一个 `uploadUrl`。

**2. 发送文件**

通过 `PUT` 请求将文件发送到 `uploadUrl`。其 `Content-Type` 和 `Content-Length` 必须与您注册时的 `contentType` 和 `size` 完全一致，否则会被拒绝。该 URL 已预签名，因此请勿添加 API 密钥。它会在 10 分钟后过期。

```bash theme={null}
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @menu.pdf
```

**3. 使用文件 ID**

在[创建二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md)时传入 `fileId`：

* 作为 `pdf`、`image` 或 `video` 二维码的 `fileId`。请使用与类型匹配的用途上传。
* 作为 `vcard`、`social`、`multilink` 或 `event` 二维码头像的 `fileId`。请使用 `logo` 用途上传。
* 作为自定义 Logo 的 `logoOptions.fileId`，同时将 `logoOptions.type` 设为 `uploaded`。请使用 `logo` 用途上传。请参阅[自定义设计](https://docs.getqr.com/zh/api/guides/customization.md)。

## 限制

| `target` | 可接受的内容类型 | 大小上限 |
| - | - | - |
| `pdf` | `application/pdf` | 20 MB（20,971,520 字节） |
| `image` | `image/*` | 5 MB（5,242,880 字节） |
| `video` | `video/*` | 50 MB（52,428,800 字节） |
| `logo` | `image/*` | 5 MB（5,242,880 字节） |

* **纯 MIME 类型。** 只发送一个小写的类型和子类型，例如 `image/png`。带 `;charset=` 等参数或多个类型的列表都会被拒绝。
* **不支持 SVG。** 不接受 `image/svg+xml` 等基于 XML 的类型。请上传 `image/png` 或 `image/jpeg` 等位图。

## 请求头

**Authorization** `string` *required*

`Bearer` 后跟您的 API 密钥。请参阅[身份验证](https://docs.getqr.com/zh/api/authentication.md)。

**Content-Type** `string` *required*

`application/json`。

## 注册文件上传

`POST /api/v1/files`

注册文件，并返回一个用于上传的预签名 URL。此调用本身不会上传文件。

**target** `string` *required*

文件的用途：`pdf`、`image`、`video` 或 `logo`。它决定可接受的内容类型和大小上限。请参阅[限制](#限制)。

**contentType** `string` *required*

文件的 MIME 类型，例如 `application/pdf`，不带参数。上传请求必须发送完全相同的 `Content-Type`。

**size** `integer` *required*

文件的准确大小（字节），为正整数。会根据该用途的大小上限进行检查。上传请求必须发送完全相同的 `Content-Length`。

**name** `string`

原始文件名，最多 255 个字符，用于在控制台中显示。包含 `/` 或 `\` 的路径会被拒绝。

**fileId** `string`

作为 `fileId` 或 `logoOptions.fileId` 传入的 ID。

**uploadUrl** `string`

用于 `PUT` 文件的预签名 URL。

**expiresIn** `integer`

距离 `uploadUrl` 过期的秒数：`600`。

**method** `string`

上传使用的 HTTP 方法：`PUT`。

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/files" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "pdf",
    "contentType": "application/pdf",
    "size": 248000,
    "name": "menu.pdf"
  }'
```

```json 200 theme={null}
{
  "fileId": "file_7bQ2xR9mKp",
  "uploadUrl": "https://storage.getqr.com/qrs-content/pdf/file_7bQ2xR9mKp?X-Amz-...",
  "expiresIn": 600,
  "method": "PUT"
}
```

## 常见问题

> [accordion] 422 "Content type … is not allowed for target"
>
> 内容类型与用途不匹配。例如，`pdf` 只接受 `application/pdf`。请参阅[限制](#限制)。

> [accordion] 422 "must be a single lowercase type/subtype"
>
> 请以小写形式发送内容类型，且不带参数：应为 `image/png`，而不是 `Image/PNG` 或 `image/png; charset=utf-8`。

> [accordion] 422 "File is too large for target"
>
> 声明的 `size` 超过了该用途的大小上限。请先压缩文件，再进行注册。

> [accordion] 上传到 uploadUrl 失败
>
> 该 URL 在注册文件 10 分钟后过期，并且请求必须发送与注册时完全一致的 `Content-Type` 和 `Content-Length`。请重新注册文件以获取新的 URL。

> [accordion] 创建二维码时返回 422 "is registered but its content was never uploaded"
>
> 您已注册文件，但向 `uploadUrl` 发送的 `PUT` 请求未完成。请先上传文件，再创建二维码。

> [accordion] 创建二维码时返回 422 "was uploaded to …"
>
> 文件注册时使用了其他用途，例如将 `image` 文件用于 `pdf` 二维码。请使用匹配的用途重新注册上传。

> [accordion] 创建二维码时返回 404 "File … was not found"
>
> 该 `fileId` 不存在。请从[注册文件上传](#注册文件上传)的响应中获取它。

## 后续步骤

> [card] [二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md)

> [card] [二维码类型](https://docs.getqr.com/zh/api/guides/qr-types.md)

> [card] [自定义设计](https://docs.getqr.com/zh/api/guides/customization.md)

> [card] [错误](https://docs.getqr.com/zh/api/errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.