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

# Base64 文件上传

> - 支持 Base64 编码和 Data URL 格式
- 可自动识别文件类型并分类存储
- 返回可访问的文件 URL
- 文件会在 72 小时后过期
- 存储空间不足时默认自动清理最早上传的文件（可通过 auto_cleanup=false 关闭）




## OpenAPI

````yaml openapi/zh/upload-base64.json POST /v1/files/upload/base64
openapi: 3.1.0
info:
  title: Base64 File Upload
  version: '1.0'
servers:
  - url: https://api.aihubmax.com
security:
  - BearerAuth: []
paths:
  /v1/files/upload/base64:
    post:
      tags:
        - File Management
      summary: Base64 File Upload
      description: |
        - 支持 Base64 编码和 Data URL 格式
        - 可自动识别文件类型并分类存储
        - 返回可访问的文件 URL
        - 文件会在 72 小时后过期
        - 存储空间不足时默认自动清理最早上传的文件（可通过 auto_cleanup=false 关闭）
      operationId: upload-base64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - file_data
              properties:
                file_data:
                  type: string
                  description: Base64 编码的文件内容，支持纯 base64 或 data URL 格式
                  example: >-
                    iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk...
                file_name:
                  type: string
                  description: 文件名（含扩展名），不提供时从 data URL MIME 推断或默认 upload.bin
                  example: photo.png
                auto_cleanup:
                  type: boolean
                  default: true
                  description: |
                    存储空间不足时是否自动清理最早上传的文件以腾出空间

                    **说明：**
                    - 默认 `true`：自动淘汰最早上传的文件
                    - 设为 `false`：空间不足时直接返回 403 错误
                  example: true
      responses:
        '200':
          $ref: '#/components/responses/FileUploaded'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    FileUploaded:
      description: 文件上传成功
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FileUploadResponse'
    BadRequest:
      description: 请求错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse400'
    Unauthorized:
      description: 未授权
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse401'
    Forbidden:
      description: 存储空间不足
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse403'
    PayloadTooLarge:
      description: 文件过大
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse413'
    TooManyRequests:
      description: 请求过多
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse429'
    InternalServerError:
      description: 服务器内部错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse500'
  schemas:
    FileUploadResponse:
      type: object
      properties:
        id:
          type: string
          description: 文件ID
          example: file-1757165031-a1b2c3
        filename:
          type: string
          description: 原始文件名
          example: photo.png
        url:
          type: string
          description: 上传文件的可访问URL
          example: https://cdn.foxapi.cc/uploads/20260319/a1b2c3d4e5f6/photo.png
        size:
          type: integer
          description: 文件大小（字节）
          example: 204800
        created:
          type: integer
          description: 上传时间戳
          example: 1757165031
    ErrorResponse400:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: 请求参数无效
            type:
              type: string
              example: invalid_request_error
    ErrorResponse401:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: API密钥无效
            type:
              type: string
              example: authentication_error
    ErrorResponse403:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: 存储空间不足
            type:
              type: string
              example: permission_error
    ErrorResponse413:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: 文件过大
            type:
              type: string
              example: file_too_large_error
    ErrorResponse429:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: 请求频率超限
            type:
              type: string
              example: rate_limit_error
    ErrorResponse500:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: 服务器内部错误
            type:
              type: string
              example: server_error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        ## 所有接口均需要使用Bearer Token进行认证 ##

        使用时在请求头中添加：

        `Authorization: Bearer YOUR_API_KEY`

````