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

# 文件上传（Base64）

> 上传 Base64 编码的数据 URL 格式文件。MIME 类型会从数据 URL 前缀自动检测。

通过 Base64 数据 URL 格式上传文件到云存储。

**接口特点：**

* **前端友好** - 适合 Canvas、截图等场景直接上传
* **自动解析** - 从 data URL 前缀自动检测 MIME 类型
* **大文件支持** - 最大支持 50MB 文件上传
* **双线路** - 返回全球和中国两个访问 URL


## OpenAPI

````yaml /cn/files-openapi-zh.json POST /api/upload/base64
openapi: 3.0.3
info:
  title: 文件上传 API
  description: 通过 Base64、multipart/form-data 或远程 URL 上传文件。基于 Cloudflare R2 存储。
  version: 1.0.0
  contact:
    name: SinanCode
    url: https://sinancode.com
servers:
  - url: https://files-api.sinancode.com
    description: 生产服务器
security:
  - bearerAuth: []
tags:
  - name: 上传
    description: 文件上传操作
paths:
  /api/upload/base64:
    post:
      tags:
        - 上传
      summary: 通过 Base64 数据 URL 上传文件
      description: 上传 Base64 编码的数据 URL 格式文件。MIME 类型会从数据 URL 前缀自动检测。
      operationId: uploadBase64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Base64UploadRequest'
            example:
              data: >-
                data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==
      responses:
        '201':
          $ref: '#/components/responses/UploadSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    Base64UploadRequest:
      type: object
      required:
        - data
      properties:
        data:
          type: string
          description: Base64 数据 URL，格式：data:{mime-type};base64,{base64-data}
          example: data:image/png;base64,iVBORw0KGgo...
    UploadSuccessResponse:
      type: object
      required:
        - url
        - cn_url
        - key
        - md5
        - size
        - content_type
        - expires_at
      properties:
        url:
          type: string
          format: uri
          description: 已上传文件的公开访问 URL（全球）
          example: https://upload-tmp.sinancode.com/uploads/user123/abc123def456.png
        cn_url:
          type: string
          format: uri
          description: 已上传文件的公开访问 URL（中国）
          example: >-
            https://beijing-user-upload-tmp.tos-cn-beijing.volces.com/uploads/user123/abc123def456.png
        key:
          type: string
          description: 已上传文件的存储键
          example: uploads/user123/abc123def456.png
        md5:
          type: string
          description: 文件内容的哈希值（SHA-256 截断）
          example: d41d8cd98f00b204e9800998ecf8427e
        size:
          type: integer
          description: 文件大小（字节）
          example: 12345
        content_type:
          type: string
          description: 文件的 MIME 类型
          example: image/png
        expires_at:
          type: string
          format: date-time
          description: 文件过期时间（ISO 8601 格式）
          example: '2024-01-17T00:00:00.000Z'
    ErrorResponse:
      type: object
      required:
        - message
        - error_code
      properties:
        message:
          type: string
          description: 人类可读的错误消息
          example: Invalid file format
        error_code:
          type: string
          description: 机器可读的错误码
          example: UPLOAD.INVALID_FILE
  responses:
    UploadSuccess:
      description: 文件上传成功
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UploadSuccessResponse'
    BadRequest:
      description: 请求参数无效
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: 'Missing required field: data'
            error_code: UPLOAD.INVALID_FILE
    Unauthorized:
      description: 缺少或无效的授权令牌
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Missing authorization token
            error_code: AUTH.MISSING_TOKEN
    PayloadTooLarge:
      description: 文件大小超过最大限制（50MB）
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: File size exceeds maximum limit of 50MB
            error_code: UPLOAD.FILE_TOO_LARGE
    InternalError:
      description: 内部服务器错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Internal server error
            error_code: INTERNAL_ERROR
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 从 api.sinancode.com 获取的授权令牌

````