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

# Base64 文件上传

<Info>
  上传的文件为临时文件，3天后自动删除。
</Info>

### 功能特点

* 支持 Base64 编码数据和 data URL 格式
* 自动识别 MIME 类型和文件扩展名
* 支持自定义文件名或自动生成
* 返回完整的文件信息和下载链接
* API Key 认证保护
* 上传文件为临时文件，3天后自动删除

### 支持的格式

* **纯 Base64 字符串**：`iVBORw0KGgoAAAANSUhEUgAA...`
* **Data URL 格式**：`data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...`

### 使用建议

* 推荐用于小文件如图片
* 大文件（>10MB）建议使用文件流上传 API
* Base64 编码会使数据传输量增加约 33%


## OpenAPI

````yaml cn/file-upload-api/file-upload-api-cn.json POST /api/file-base64-upload
openapi: 3.0.0
info:
  title: 文件上传 API
  description: 文件上传服务 API 文档 - 支持多种文件上传方式，上传的文件为临时文件，仅保留3天后自动删除
  version: 1.0.0
  contact:
    name: 技术支持
    email: support@sunoapi.org
servers:
  - url: https://sunoapiorg.redpandaai.co
    description: API 服务器
security:
  - BearerAuth: []
tags:
  - name: 文件上传
    description: 多种方式上传临时文件，支持 Base64、文件流和 URL 上传，文件保留3天后自动删除
paths:
  /api/file-base64-upload:
    post:
      summary: Base64文件上传
      operationId: upload-file-base64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Base64UploadRequest'
            examples:
              with_data_url:
                summary: 使用data URL格式
                value:
                  base64Data: >-
                    data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==
                  uploadPath: images/base64
                  fileName: test-image.png
              with_pure_base64:
                summary: 使用纯Base64字符串
                value:
                  base64Data: >-
                    iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==
                  uploadPath: documents/uploads
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '405':
          $ref: '#/components/responses/MethodNotAllowedError'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    Base64UploadRequest:
      type: object
      properties:
        base64Data:
          type: string
          description: >-
            Base64编码的文件数据。支持纯Base64字符串或data
            URL格式（如：data:image/png;base64,iVBOR...）
          example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...
        uploadPath:
          type: string
          description: 文件上传路径，不包含前后斜杠
          example: images/base64
        fileName:
          type: string
          description: >-
            文件名称（可选），包含文件扩展名。如不提供，系统将生成随机文件名。若传入的文件名与已存在的文件名相同，旧文件将被覆盖，但由于缓存机制，覆盖效果可能不会立即显现
          example: my-image.png
      required:
        - base64Data
        - uploadPath
    ApiResponse:
      type: object
      properties:
        success:
          type: boolean
          description: 请求是否成功
        code:
          $ref: '#/components/schemas/StatusCode'
        msg:
          type: string
          description: 响应消息
          example: 文件上传成功
      required:
        - success
        - code
        - msg
    FileUploadResult:
      type: object
      properties:
        fileName:
          type: string
          description: 文件名称
          example: uploaded-image.png
        filePath:
          type: string
          description: 文件在存储中的完整路径
          example: images/user-uploads/uploaded-image.png
        downloadUrl:
          type: string
          format: uri
          description: 文件下载链接
          example: >-
            https://tempfile.redpandaai.co/xxx/images/user-uploads/uploaded-image.png
        fileSize:
          type: integer
          description: 文件大小（字节）
          example: 154832
        mimeType:
          type: string
          description: 文件MIME类型
          example: image/png
        uploadedAt:
          type: string
          format: date-time
          description: 上传时间
          example: '2025-01-01T12:00:00.000Z'
      required:
        - fileName
        - filePath
        - downloadUrl
        - fileSize
        - mimeType
        - uploadedAt
    ErrorResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            error:
              type: string
              description: 详细错误信息
    StatusCode:
      type: integer
      enum:
        - 200
        - 400
        - 401
        - 405
        - 500
      description: 响应状态码
      x-enumDescriptions:
        '200': 成功 - 请求已成功处理
        '400': 请求错误 - 请求参数不正确或缺少必需参数
        '401': 未授权 - 身份验证凭据缺失或无效
        '405': 方法不允许 - 请求方法不被支持
        '500': 服务器错误 - 处理请求时发生意外错误
  responses:
    SuccessResponse:
      description: 文件上传成功
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ApiResponse'
              - type: object
                properties:
                  data:
                    $ref: '#/components/schemas/FileUploadResult'
          example:
            success: true
            code: 200
            msg: 文件上传成功
            data:
              fileName: uploaded-image.png
              filePath: images/user-uploads/uploaded-image.png
              downloadUrl: >-
                https://tempfile.redpandaai.co/xxx/images/user-uploads/uploaded-image.png
              fileSize: 154832
              mimeType: image/png
              uploadedAt: '2025-01-01T12:00:00.000Z'
    BadRequestError:
      description: 请求参数错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing_parameter:
              summary: 缺少必需参数
              value:
                success: false
                code: 400
                msg: '缺少必需参数: uploadPath（上传路径）'
            invalid_format:
              summary: 格式错误
              value:
                success: false
                code: 400
                msg: 'Base64解码失败: 无效的Base64格式'
    UnauthorizedError:
      description: 未授权访问
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            code: 401
            msg: '认证失败: API Key无效'
    MethodNotAllowedError:
      description: 不支持的请求方法
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            code: 405
            msg: 不支持的请求方法
    ServerError:
      description: 服务器内部错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            code: 500
            msg: 服务器内部错误
            error: 上传文件时发生错误
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: |-
        所有 API 需要通过 Bearer Token 进行身份验证。

        获取 API Key：
        1. 访问 [API Key 管理页面](https://sunoapi.org/api-key) 获取您的 API Key

        使用方法：
        在请求头中添加：
        Authorization: Bearer YOUR_API_KEY

        注意：
        - 请妥善保管您的 API Key，不要与他人分享
        - 如果怀疑 API Key 已泄露，请立即在管理页面重置

````