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

# 通过 Base64 上传文件

> 使用 Base64 编码数据或 Data URL 格式将文件上传到 PoYo AI

## 使用指南

* 该接口接收 Base64 编码的文件数据，并上传到 PoYo AI 存储
* 同时支持 Data URL 格式（带 MIME 类型前缀）和纯 Base64 字符串
* 适合上传应用中已经是 Base64 编码的文件，例如 canvas 绘图或客户端处理过的图片
* 文件可通过返回的 URL 立即访问，保留 72 小时

## 参数详情

* **Base64 数据格式**：

  * **Data URL 格式**：`data:image/png;base64,iVBORw0KGgo...`（推荐）

  * **纯 Base64 字符串**：`iVBORw0KGgo...`（不带 MIME 类型前缀）

  * Base64 字符串不得包含任何空白、换行符或格式字符

  * 支持的文件格式：仅 **JPEG、PNG、GIF、WebP**

  * 上传数量上限：**每次请求 1 张图片**

* **存储配置**：

  * 所有文件在存储路径中都会自动加上 `temp/` 前缀

  * 如果指定 `upload_path: "profile-images"`，实际路径为 `temp/profile-images`

  * 文件在上传 **72 小时**后过期并自动删除

* **文件命名**：

  * 如果未提供 `file_name`，系统会按以下格式生成唯一文件名：`{timestamp}_{random}_{extension}`

  * 自动生成的文件名示例：`20251229130857_a8B9cD2e.png`

## 开发者说明

* 适合使用 Base64 上传的情况：

  * 客户端生成的图片（canvas、截图）

  * 应用中已经是 Base64 编码的图片

  * 可以接受编码开销的中小尺寸图片

* 不适合使用 Base64 上传的情况：

  * 大图片文件（Base64 编码会使体积增加约 33%）

  * 存储在磁盘上的文件（改用文件流上传）

  * 可通过 URL 获取的文件（改用 URL 上传）

* 确保 Base64 数据格式正确，不含任何换行或空格

* 如需持久保存，请在 72 小时过期前将文件下载到本地

## 速率限制与配额

* **速率限制**：每个已认证用户、每个上传接口，在 60 秒固定窗口内最多 10 次请求

* 超出速率限制时，会收到 `429 Too Many Requests` 错误

* 固定窗口从窗口内第一次请求开始计算，同一用户的 JWT 请求和 API Key 请求共享该窗口

* 使用指数退避重试逻辑处理速率限制错误

## 常见错误场景

* **Base64 编码无效**：提供的 Base64 字符串无法解码

* **Data URL 格式无效**：Data URL 格式错误（例如缺少 `data:` 前缀或 `;base64,` 分隔符）

* **不支持的文件类型**：解码后的文件不是支持的图片格式（JPEG、PNG、GIF、WebP）

* **文件数据无效**：解码后的数据为空或已损坏

* **认证错误**：Authorization 请求头中的 API Key 缺失或无效


## OpenAPI

````yaml zh/api-manual/file-series/upload-base64.json POST /api/common/upload/base64
openapi: 3.0.0
info:
  title: PoYo AI - 通过 Base64 上传文件
  description: 使用 Base64 编码数据或 Data URL 格式将文件上传到 PoYo AI
  version: 1.0.0
servers:
  - url: https://api.poyo.ai
    description: 生产环境
security:
  - BearerAuth: []
paths:
  /api/common/upload/base64:
    post:
      tags:
        - File Upload
      summary: 通过 Base64 上传文件
      description: >-
        使用 Base64 编码数据或 Data URL 格式上传文件。同时支持纯 Base64 字符串和带 MIME 类型前缀的 Data URL
        格式。
      operationId: uploadFileFromBase64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadBase64Request'
            examples:
              data-url-format:
                summary: Data URL 格式
                value:
                  base64_data: >-
                    data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==
              pure-base64:
                summary: 纯 Base64 字符串
                value:
                  base64_data: >-
                    iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==
              custom-naming:
                summary: 使用自定义路径和文件名上传
                value:
                  base64_data: >-
                    data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwCwAA8=
                  upload_path: profile-images
                  file_name: user-avatar.jpg
      responses:
        '200':
          description: 文件上传成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadResponse'
        '400':
          description: 请求错误 - Base64 无效、文件类型不支持或数据无效
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid-base64:
                  summary: Base64 编码无效
                  value:
                    detail: Invalid Base64 encoding
                invalid-data-url:
                  summary: Data URL 格式无效
                  value:
                    detail: Invalid data URL format
                unsupported-type:
                  summary: 文件类型不支持
                  value:
                    detail: 'Unsupported file type: image/svg+xml'
                invalid-file-data:
                  summary: 文件数据无效
                  value:
                    detail: Invalid file data
        '401':
          description: 未授权 - 缺少认证信息或认证无效
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not-authenticated:
                  summary: 未认证
                  value:
                    detail: Not authenticated
        '429':
          description: 超出速率限制 - 每个已认证用户在每个上传接口上，每 60 秒固定窗口内最多 10 次请求
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                rate-limit:
                  summary: 超出速率限制
                  value:
                    detail: Rate limit exceeded
        '500':
          description: 服务器错误 - 存储连接或上传失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                server-error:
                  summary: 服务器错误
                  value:
                    detail: 'Upload failed: S3 connection error'
components:
  schemas:
    UploadBase64Request:
      type: object
      required:
        - base64_data
      properties:
        base64_data:
          type: string
          description: |-
            Base64 编码的文件数据。

            支持两种格式：

            1. **Data URL 格式**：`data:image/png;base64,iVBORw0KGgo...`

            2. **纯 Base64 字符串**：`iVBORw0KGgo...`（不带 MIME 类型前缀）

            **支持的格式**：JPEG、PNG、GIF、WebP

            **注意**：Base64 字符串中不能包含任何空白字符或换行符。
          example: >-
            data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==
        upload_path:
          type: string
          description: |-
            自定义存储目录路径。

            未指定时，系统会自动对文件分类。

            **注意**：无论指定什么路径，所有文件都会以 `temp/` 前缀存储。
          example: profile-images
        file_name:
          type: string
          description: |-
            上传文件的自定义文件名。

            未指定时，系统会按以下格式生成唯一文件名：`{timestamp}_{random}_{extension}`

            **自动生成的文件名示例**：`20251229130857_a8B9cD2e.png`
          example: user-avatar.png
    UploadResponse:
      type: object
      required:
        - success
        - code
        - msg
        - data
      properties:
        success:
          type: boolean
          example: true
          description: 上传是否成功
        code:
          type: integer
          example: 200
          description: >-
            业务状态码。`200` 表示成功，其他值都表示请求失败。请务必检查这个字段：部分参数校验错误会以 HTTP 200 返回，响应体里的
            `code` 为 `400`。


            - `200`：成功

            - `400`：请求参数无效

            - `401`：API Key 缺失或无效

            - `402`：积分不足

            - `403`：没有权限

            - `404`：资源不存在

            - `408`：请求超时

            - `429`：请求频率超限

            - `500`：服务器内部错误

            - `502`：上游服务错误

            - `503`：服务暂不可用


            详见[错误码](/zh/api-manual/error-codes)。
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
        msg:
          type: string
          example: File uploaded successfully
          description: 响应消息
        data:
          type: object
          required:
            - file_id
            - file_name
            - original_name
            - file_size
            - mime_type
            - upload_path
            - file_url
            - download_url
            - upload_time
            - expires_at
          properties:
            file_id:
              type: string
              example: da2611c99d3ce825bc9a5409378db8e4
              description: 文件唯一标识（MD5 哈希）
            file_name:
              type: string
              example: test-base64.png
              description: 存储后的文件名
            original_name:
              type: string
              example: test-base64.png
              description: 原始文件名
            file_size:
              type: integer
              example: 3242
              description: 文件大小（字节）
            mime_type:
              type: string
              example: image/png
              description: 上传文件的 MIME 类型
            upload_path:
              type: string
              example: temp/test-base64
              description: 存储路径（包含 temp/ 前缀）
            file_url:
              type: string
              format: uri
              example: https://storage.poyo.ai/temp/test-base64/test-base64.png
              description: 上传文件的直接访问 URL
            download_url:
              type: string
              format: uri
              example: https://storage.poyo.ai/temp/test-base64/test-base64.png
              description: 下载 URL（与 file_url 相同）
            upload_time:
              type: string
              format: date-time
              example: '2025-12-29T13:09:01.233635'
              description: 上传时间戳，ISO 8601 格式
            expires_at:
              type: string
              format: date-time
              example: '2026-01-01T13:09:01.233635'
              description: 过期时间戳，ISO 8601 格式（上传后 72 小时）
    ErrorResponse:
      type: object
      required:
        - detail
      properties:
        detail:
          type: string
          description: 描述错误原因的错误信息
          example: Not authenticated
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        所有 API 接口都需要 Bearer Token 认证。


        创建 API Key：登录 PoYo，进入 **仪表盘 → API
        密钥**（[poyo.ai/zh/dashboard/api-key](https://poyo.ai/zh/dashboard/api-key)），点击创建
        Key。


        在请求头中添加：


        ```

        Authorization: Bearer YOUR_API_KEY

        ```

````

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