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

# 文件流上传

> - 使用 multipart/form-data 格式上传文件
- 支持下划线和驼峰两种参数命名方式
- 适用于直接上传本地文件
- 文件会在72小时后过期
- 当前用户配额有限，配额耗尽时上传会失败，如需持久化保存请保存在本地

**注意：**
文件上传接口的baseurl为`https://files-api.evolink.ai`



## OpenAPI

````yaml cn/api-manual/file-series/upload-stream.json POST /api/v1/files/upload/stream
openapi: 3.1.0
info:
  title: 文件流上传接口
  description: 通过 multipart/form-data 上传文件到文件服务器
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://files-api.evolink.ai
    description: 文件服务环境
security:
  - bearerAuth: []
tags:
  - name: 文件上传
    description: 文件上传相关接口
paths:
  /api/v1/files/upload/stream:
    post:
      tags:
        - 文件上传
      summary: 文件流上传
      description: |-
        - 使用 multipart/form-data 格式上传文件
        - 支持下划线和驼峰两种参数命名方式
        - 适用于直接上传本地文件
        - 文件会在72小时后过期
        - 当前用户配额有限，配额耗尽时上传会失败，如需持久化保存请保存在本地

        **注意：**
        文件上传接口的baseurl为`https://files-api.evolink.ai`
      operationId: uploadFileStream
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/StreamUploadRequest'
            examples:
              stream_upload:
                summary: 文件流上传
                value:
                  file: '@/path/to/file.png'
      responses:
        '200':
          description: 文件上传成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileUploadResponse'
components:
  schemas:
    StreamUploadRequest:
      type: object
      required:
        - file
      properties:
        file:
          type: string
          format: binary
          description: |-
            文件二进制数据

            **说明：**
            - 通过 form-data 格式上传
            - 系统会自动识别文件类型
            - 单次请求最多支持`1`张图像
            - 当前仅支持：`image/jpeg`、`image/png`、`image/gif`、`image/webp`四种类型文件的上传
        upload_path:
          type: string
          description: |-
            自定义上传路径

            **说明：**
            - 支持下划线命名：`upload_path`
            - 支持驼峰命名：`uploadPath`
            - 不指定时系统会根据文件类型自动分类
          example: photos
        file_name:
          type: string
          description: |-
            自定义文件名

            **说明：**
            - 支持下划线命名：`file_name`
            - 支持驼峰命名：`fileName`
            - 不指定时系统会自动生成唯一文件名
          example: photo.png
    FileUploadResponse:
      type: object
      properties:
        success:
          type: boolean
          description: 请求是否成功
          example: true
        code:
          type: integer
          description: 响应状态码
          example: 200
        msg:
          type: string
          description: 响应消息
          example: 文件上传成功
        data:
          $ref: '#/components/schemas/FileData'
    FileData:
      type: object
      properties:
        file_id:
          type: string
          description: 文件唯一标识ID
          example: file_abc123
        file_name:
          type: string
          description: 存储的文件名
          example: photo.png
        original_name:
          type: string
          description: 原始文件名
          example: photo.png
        file_size:
          type: integer
          description: 文件大小（字节）
          example: 2048
        mime_type:
          type: string
          description: 文件MIME类型
          example: image/png
        upload_path:
          type: string
          description: 文件存储路径
          example: photos
        file_url:
          type: string
          format: uri
          description: 文件访问URL
          example: https://files.evolink.ai/photos/photo.png
        download_url:
          type: string
          format: uri
          description: 文件下载URL
          example: https://files.evolink.ai/api/v1/files/download/file_abc123
        upload_time:
          type: string
          format: date-time
          description: 上传时间（ISO 8601格式）
          example: '2025-10-09T00:00:00+08:00'
        expires_at:
          type: string
          format: date-time
          description: 文件过期时间（ISO 8601格式）
          example: '2025-10-12T00:00:00+08:00'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |-
        ##所有接口均需要使用Bearer Token进行认证##

        **获取 API Key ：**

        访问 [API Key 管理页面](https://evolink.ai/dashboard/keys) 获取您的 API Key

        **使用时在请求头中添加：**
        ```
        Authorization: Bearer YOUR_API_KEY
        ```

````