> ## 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.

# URL 文件上传

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

### 功能特点

* 支持 HTTP 和 HTTPS 文件链接
* 自动下载远程文件并上传
* 自动从 URL 提取文件名或使用自定义文件名
* 自动识别 MIME 类型
* 返回完整的文件信息和下载链接
* API Key 认证保护
* 上传文件为临时文件，3天后自动删除

### 支持的协议

* **HTTP**：`http://example.com/file.jpg`
* **HTTPS**：`https://example.com/file.jpg`

### 使用场景

* 从其他服务迁移文件
* 批量下载和存储网络资源
* 备份远程文件
* 缓存外部资源

### 重要说明

* 确保提供的 URL 可公开访问
* 下载超时时间为 30 秒
* 推荐文件大小上限为 100MB


## OpenAPI

````yaml cn/file-upload-api/file-upload-api-cn.json POST /api/file-url-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-url-upload:
    post:
      summary: URL文件上传
      operationId: upload-file-url
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UrlUploadRequest'
            examples:
              image_from_url:
                summary: 从URL下载图片
                value:
                  fileUrl: https://example.com/images/sample.jpg
                  uploadPath: images/downloaded
                  fileName: my-downloaded-image.jpg
              document_from_url:
                summary: 从URL下载文档
                value:
                  fileUrl: https://example.com/docs/manual.pdf
                  uploadPath: documents/manuals
      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:
    UrlUploadRequest:
      type: object
      properties:
        fileUrl:
          type: string
          format: uri
          description: 文件下载链接，必须是有效的HTTP或HTTPS地址
          example: https://example.com/images/sample.jpg
        uploadPath:
          type: string
          description: 文件上传路径，不包含前后斜杠
          example: images/downloaded
        fileName:
          type: string
          description: >-
            文件名称（可选），包含文件扩展名。如不提供，系统将生成随机文件名。若传入的文件名与已存在的文件名相同，旧文件将被覆盖，但由于缓存机制，覆盖效果可能不会立即显现
          example: sample-image.jpg
      required:
        - fileUrl
        - 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 已泄露，请立即在管理页面重置

````