> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-feat-openapi-i18n.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 이미지 파일 업로드

> 클라우드 저장소에 이미지 파일을 업로드합니다.

이미지 제한 사항:
  - 최대 파일 크기: 50MB
  - 각 변의 최대 너비/높이: 16384px
  - 최대 총 픽셀 수: 64메가픽셀 (67108864 픽셀)

이 제한을 초과하는 업로드는 HTTP 400으로 거부됩니다.




## OpenAPI

````yaml /openapi/cloud.ko.yaml post /api/upload/image
openapi: 3.0.3
info:
  title: Comfy Cloud API
  description: >
    <Warning>

    **실험적 API:** 이 API는 실험적이며 변경될 수 있습니다. 

    엔드포인트, 요청/응답 형식 및 동작은 사전 통지 없이 수정될 수 있습니다.

    </Warning>


    Comfy Cloud용 API - 클라우드 인프라에서 ComfyUI 워크플로를 실행합니다.


    이 API를 사용하여 Comfy Cloud와 프로그래밍 방식으로 상호작용할 수 있습니다:

    - 워크플로 제출 및 관리

    - 파일 업로드 및 다운로드

    - 작업 상태 및 진행 상황 모니터링


    ## Cloud vs OSS ComfyUI 호환성


    Comfy Cloud는 최대 호환성을 위해 OSS ComfyUI와 동일한 API 인터페이스를 구현하지만,

    일부 필드는 호환성을 위해 허용되지만 다르게 처리되거나 무시됩니다:


    | 필드 | 엔드포인트 | Cloud 동작 |

    |-------|-----------|----------------|

    | `subfolder` | `/api/view`, `/api/upload/*` | **무시됨** - Cloud는 콘텐츠 주소 지정
    저장소(해시 기반)를 사용합니다. 클라이언트 측 구성을 위해 응답에 반환됩니다. |

    | `type` (input/output/temp) | `/api/view`, `/api/upload/*` | 부분적으로 사용됨 - 모든
    파일은 디렉토리 구조 대신 태그 기반 조직으로 저장됩니다. |

    | `overwrite` | `/api/upload/*` | **무시됨** - 콘텐츠 주소 지정 저장소는 동일한 콘텐츠가 항상 동일한
    해시를 갖도록 합니다. |

    | `number`, `front` | `/api/prompt` | **무시됨** - Cloud는 사용자별로 자체 공정 실행 대기열
    스케줄링을 사용합니다. |

    | `split`, `full_info` | `/api/userdata` | **무시됨** - Cloud는 항상 전체 파일 메타데이터를
    반환합니다. |


    이러한 필드는 기존 ComfyUI 클라이언트 및 워크플로와의 드롭인 호환성을 위해 API 스키마에 유지됩니다.
  version: 1.0.0
  license:
    name: GNU General Public License v3.0
    url: https://github.com/Comfy-Org/ComfyUI/blob/master/LICENSE
servers:
  - url: https://cloud.comfy.org
    description: Comfy Cloud API
security:
  - ApiKeyAuth: []
tags:
  - name: workflow
    description: |
      워크플로를 제출하여 실행하고, 실행 대기열을 관리합니다.
      클라우드에서 ComfyUI 워크플로를 실행하는 주요 방법입니다.
  - name: job
    description: |
      작업 상태를 모니터링하고, 실행 기록을 확인하며, 실행 중인 작업을 관리합니다.
      작업은 POST /api/prompt를 통해 워크플로를 제출할 때 생성됩니다.
  - name: asset
    description: |
      지속적 에셋(이미지, 모델, 출력)을 업로드, 다운로드 및 관리합니다.
      에셋은 태그 지정 및 메타데이터 지원과 함께 내구성 있는 스토리지를 제공합니다.
  - name: file
    description: |
      로컬 ComfyUI와 호환되는 레거시 파일 업로드 및 다운로드 엔드포인트입니다.
      새로운 통합의 경우 Assets API 사용을 고려하세요.
  - name: model
    description: |
      사용 가능한 AI 모델을 찾아보세요. 모델은 클라우드 인프라에 사전 로드됩니다.
  - name: node
    description: |
      사용 가능한 ComfyUI 노드 및 해당 입력/출력에 대한 정보를 가져옵니다.
      동적 워크플로 인터페이스 구축에 유용합니다.
  - name: user
    description: |
      사용자 계정 정보 및 개인 데이터 스토리지.
  - name: system
    description: |
      서버 상태, 상태 확인 및 시스템 정보.
paths:
  /api/upload/image:
    post:
      tags:
        - file
      summary: 이미지 파일 업로드
      description: |
        클라우드 저장소에 이미지 파일을 업로드합니다.

        이미지 제한 사항:
          - 최대 파일 크기: 50MB
          - 각 변의 최대 너비/높이: 16384px
          - 최대 총 픽셀 수: 64메가픽셀 (67108864 픽셀)

        이 제한을 초과하는 업로드는 HTTP 400으로 거부됩니다.
      operationId: uploadImage
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - image
              properties:
                image:
                  type: string
                  format: binary
                  description: 업로드할 이미지 파일
                overwrite:
                  type: string
                  description: >
                    기존 파일 덮어쓰기 여부 (참/거짓).

                    **참고:** ComfyUI API 호환성을 위해 허용되지만 클라우드에서는 사실상 무시됩니다.

                    클라우드는 콘텐츠 주소 지정 저장소(해시 기반 중복 제거)를 사용하므로, 동일한 콘텐츠는 항상 동일한 해시에
                    매핑됩니다.

                    동일한 콘텐츠를 다시 업로드하는 것은 아무런 작업도 수행하지 않습니다.
                subfolder:
                  type: string
                  description: >
                    선택적 하위 폴더 경로.

                    **참고:** ComfyUI API 호환성을 위해 허용되지만 저장에는 **무시**됩니다.

                    클라우드는 해시만으로 에셋을 저장합니다. 하위 폴더는 클라이언트 측 구성을 위해 응답에 반환되지만 서버 측
                    저장 경로에는 사용되지 않습니다.
                type:
                  type: string
                  description: >
                    업로드 유형 (기본값: "output").

                    **참고:** ComfyUI API 호환성을 위해 허용됩니다. 클라우드는 모든 업로드를 디렉토리 기반 구성이
                    아닌 태그가 있는 에셋으로 저장합니다.
      responses:
        '200':
          description: 이미지 업로드 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    description: 업로드된 이미지의 파일 이름
                  subfolder:
                    type: string
                    description: 이미지가 저장된 하위 폴더 경로
                  type:
                    type: string
                    description: '업로드 유형 (예: "output")'
        '400':
          description: 잘못된 요청
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 인증되지 않음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 내부 서버 오류
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >
        API 키 인증. 계정 설정에서 API 키를 생성하세요.

        https://platform.comfy.org/profile/api-keys 에서 생성할 수 있습니다. X-API-Key 헤더에
        키를 전달하세요.

````