> ## 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시간 후 만료됩니다
- 현재 사용자 할당량이 제한되어 있습니다. 할당량이 소진되면 업로드가 실패합니다. 영구 저장이 필요한 경우 로컬에 저장해 주세요

**참고:**
파일 업로드 API 기본 URL은 `https://files-api.evolink.ai`입니다



## OpenAPI

````yaml ko/api-manual/file-series/upload-stream.json POST /api/v1/files/upload/stream
openapi: 3.1.0
info:
  title: 파일 스트림 업로드 API
  description: multipart/form-data를 통해 파일 서버에 파일 업로드
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://files-api.evolink.ai
    description: 파일 서비스 환경
security:
  - bearerAuth: []
tags:
  - name: 파일 업로드
    description: 파일 업로드 관련 API
paths:
  /api/v1/files/upload/stream:
    post:
      tags:
        - 파일 업로드
      summary: 파일 스트림 업로드
      description: |-
        - multipart/form-data 형식으로 파일 업로드
        - 언더스코어 및 카멜케이스 파라미터 명명 모두 지원
        - 로컬 파일을 직접 업로드하는 데 적합합니다
        - 파일은 72시간 후 만료됩니다
        - 현재 사용자 할당량이 제한되어 있습니다. 할당량이 소진되면 업로드가 실패합니다. 영구 저장이 필요한 경우 로컬에 저장해 주세요

        **참고:**
        파일 업로드 API 기본 URL은 `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: 고유 파일 식별자
          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: |-
        ##모든 API는 Bearer Token 인증이 필요합니다##

        **API Key 받기:**

        [API Key 관리 페이지](https://evolink.ai/dashboard/keys)를 방문하여 API Key를 받으세요

        **요청 헤더에 추가:**
        ```
        Authorization: Bearer YOUR_API_KEY
        ```

````