> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-chore-sync-comfy-api-v2-spec-12fd5b4.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 클라우드 API 개요
> 워크플로 실행, 파일 관리 및 실행 모니터링을 위한 Comfy Cloud에 대한 프로그래밍 방식 접근
**실험적 API:** 이 API는 실험적인 것으로, 변경될 수 있습니다. 엔드포인트, 요청/응답 형식 및 동작은 사전 통지 없이 수정될 수 있습니다.
# Comfy Cloud API
Comfy Cloud API는 Comfy Cloud 인프라에서 워크플로를 실행하기 위한 프로그래밍 방식 접근을 제공합니다. 이 API는 로컬 ComfyUI의 API와 호환되므로 기존 통합을 쉽게 이전할 수 있습니다.
Python 또는 TypeScript로 작업하는 경우 [Comfy SDKs](/ko/development/api-development/sdks)를 사용하십시오. 이 SDK는 이 API를 래핑하며 워크플로를 실행하는 가장 빠른 방법입니다. 이 페이지에서는 Comfy Cloud에만 해당하는 내용, 즉 API 키, 크레딧 및 동시성 제한을 다룹니다. 그 외의 모든 내용은 [Cloud API 참조](/ko/development/cloud/api-reference)에 있습니다.
**구독 필요:** API 접근은 **Standard**, **Creator**, **Pro** 계층에서 이용 가능합니다. 무료 계층에는 API 접근이 포함되지 않습니다. 자세한 내용은 [가격 페이지](https://www.comfy.org/cloud/pricing?utm_source=docs\&utm_campaign=cloud-api)을 참조하십시오.
## 크레딧 및 사용량
API 요청은 Comfy Cloud 웹 UI와 동일한 월간 크레딧 할당량을 사용합니다. 별도의 API 크레딧 풀은 없습니다. 각 계층에 포함된 크레딧, 충전 옵션 및 워크플로당 런타임 제한은 UI 작업과 정확히 동일한 방식으로 API 작업에도 적용됩니다. [가격 페이지](https://www.comfy.org/cloud/pricing?utm_source=docs\&utm_campaign=cloud-api)에서 Standard, Creator 및 Pro 계층의 월간 크레딧 수치를 확인하십시오. 월 중간에 크레딧이 소진되면 계정 대시보드에서 추가 구매가 가능합니다.
## 기본 URL
```
https://cloud.comfy.org
```
이 URL은 SDK의 기본 대상이기도 하므로 Comfy Cloud에서는 별도로 구성할 필요가 없습니다. 동일한 코드를 서버리스 배포 또는 자체 ComfyUI에 연결하려면 `COMFY_BASE_URL`을 설정하세요. [기본 URL 선택](/ko/development/api-development/sdks#기본-url-선택)을 참조하세요.
## 인증
모든 API 요청에는 API 키가 필요합니다. HTTP를 직접 사용할 때는 `X-API-Key` 헤더에 API 키를 전달합니다. SDK를 사용할 때는 API 키를 클라이언트에 한 번만 전달하면 클라이언트가 모든 요청을 대신 인증해 줍니다.
### API 키 얻기
API 키 생성 및 관리에 대한 지침은 [API 키 얻기](/ko/development/api-development/getting-an-api-key)를 참조하십시오.
### API 키 사용하기
```bash curl theme={null}
curl -X GET "https://cloud.comfy.org/api/user" \
-H "X-API-Key: $COMFY_CLOUD_API_KEY"
```
```python Python theme={null}
import os
from comfy_sdk import Comfy
client = Comfy(api_key=os.environ["COMFY_CLOUD_API_KEY"])
```
```typescript TypeScript theme={null}
import { Comfy } from "@comfyorg/sdk";
const client = new Comfy({ apiKey: process.env.COMFY_CLOUD_API_KEY! });
```
유효하지 않거나 누락된 키는 `401`을 반환하며, SDK는 이를 `Unauthorized` 오류로 발생시킵니다. 비활성 구독 상태의 키는 `429`를 반환합니다.
동일한 키가 [파트너 노드](/ko/tutorials/partner-nodes/overview)에도 사용됩니다. HTTP를 통해서는 `extra_data.api_key_comfy_org`에 다시 전달합니다. SDK는 `submit()`에 `api_key`를 전달하면 이 작업을 자동으로 처리합니다.
## 워크플로 실행
워크플로는 ComfyUI 프론트엔드의 "Export Workflow (API)" 옵션에서 생성되는 JSON인 [API 형식](/ko/development/api-development/workflow-api-format)으로 제출됩니다. 워크플로를 제출하면 작업이 비동기적으로 실행되며, 완료되면 출력을 다운로드합니다.
Python 또는 TypeScript로 설치, 워크플로 제출, 실시간 진행 상황 확인, 출력 저장을 수행할 수 있습니다. 여기에서 시작하세요.
다른 언어에서 HTTP 엔드포인트를 직접 호출하거나 아래의 기능을 사용하려면 [Cloud API 참조](/ko/development/cloud/api-reference)를 확인하세요. 이 문서에는 curl, Python, TypeScript 예제와 함께 제출, 폴링, WebSocket 프로토콜 및 출력 다운로드 방법이 설명되어 있습니다.
### 병렬 실행 (동시 작업)
API 사용자는 이전 작업이 완료될 때까지 기다리지 않고 여러 워크플로를 동시에 제출할 수 있습니다. 작업이 수락되는 즉시 제출이 반환되므로 여러 작업을 동시에 진행할 수 있습니다. 디스패처는 구독 등급의 한도까지 작업을 병렬로 실행합니다.
| 구독 등급 | 동시 작업 |
| -------- | ----- |
| Standard | 1 |
| Creator | 3 |
| Pro | 5 |
동시 실행 한도를 초과하여 제출된 작업은 정상적으로 실행 대기열에 추가되며, 슬롯이 비면 자동으로 실행됩니다. 대기열 자체가 가득 차면 SDK가 제한된 범위 내에서 재시도한 후 `QueueFull` 예외를 발생시킵니다.
병렬 실행은 현재 API를 통해서만 사용할 수 있습니다. 구독 세부 정보는 [가격 페이지](https://www.comfy.org/cloud/pricing?utm_source=docs\&utm_campaign=cloud-api)을 확인하세요.
## SDK가 아직 다루지 않는 기능
SDK는 한 가지 작업을 수행합니다: 워크플로를 실행하고 결과를 받아오는 것입니다. 클라우드의 나머지 부분은 HTTP로만 접근할 수 있으므로, 실행에 SDK를 사용하더라도 이러한 엔드포인트를 직접 호출하세요.
| 기능 | 엔드포인트 | 참조 |
| ------------------------ | ----------------------- | ------------------------------------------------------- |
| 실행 대기열 상태 및 실행 중·대기 중 작업 | `GET /api/queue` | [실행 대기열 관리](/ko/development/cloud/api-reference#대기열-관리) |
| 현재 실행 중단 | `POST /api/interrupt` | [실행 대기열 관리](/ko/development/cloud/api-reference#대기열-관리) |
| 노드 정의 및 입력 사양 | `GET /api/object_info` | [객체 정보](/ko/development/cloud/api-reference#객체-정보) |
| 사용 가능한 모델 찾아보기 | 모델 엔드포인트 | [클라우드 API 참조](/ko/development/cloud/api-reference) |
| 계정 및 사용자 정보 | `GET /api/user` | [클라우드 API 참조](/ko/development/cloud/api-reference) |
| 기존 이미지를 참조하는 마스크 업로드 | `POST /api/upload/mask` | [입력 업로드](/ko/development/cloud/api-reference#입력-업로드) |
작업 취소는 두 방식 모두에서 지원됩니다: SDK는 핸들을 보유한 작업을 취소하고, `POST /api/queue`는 ID로 취소합니다.
## 사용 가능한 엔드포인트
| 카테고리 | 설명 |
| ------------------------------------------------------------------------ | -------------------- |
| [워크플로](/ko/development/cloud/api-reference#워크플로우-실행) | 워크플로 제출, 상태 확인 |
| [작업](/ko/development/cloud/api-reference#작업-상태-확인) | 작업 상태 및 대기열 모니터링 |
| [입력](/ko/development/cloud/api-reference#입력-업로드) | 이미지, 마스크 및 기타 입력 업로드 |
| [출력](/ko/development/cloud/api-reference#출력-다운로드) | 생성된 콘텐츠 다운로드 |
| [WebSocket](/ko/development/cloud/api-reference#실시간-진행-상황을-위한-websocket) | 실시간 진행 상태 업데이트 |
| [객체 정보](/ko/development/cloud/api-reference#객체-정보) | 사용 가능한 노드 및 그 정의 |
## 오류 처리
REST 엔드포인트는 표준 HTTP 상태 코드를 반환합니다:
| 상태 | 설명 |
| ----- | -------------------------- |
| `400` | 잘못된 요청 (잘못된 워크플로, 필드 누락) |
| `401` | 인증되지 않음 (잘못되었거나 누락된 API 키) |
| `402` | 크레딧 부족 |
| `429` | 구독 비활성 상태 |
| `500` | 내부 서버 오류 |
SDK는 대신 이러한 오류를 타입화된 예외로 발생시킵니다. 여기에는 `Unauthorized`, `InvalidWorkflow`, `InsufficientCredits`, `QueueFull`, `JobFailed`가 포함되며, 모두 `ComfyError`를 확장합니다.
실행 실패는 HTTP 오류와 별개입니다. 실행 중 전달되는 `exception_type` 값은 [오류 처리](/ko/development/cloud/api-reference#오류-처리)를 참조하세요.
## 다음 단계
Python 또는 TypeScript로 워크플로를 실행하세요. 에셋, 라이브 이벤트 및 타입화된 오류를 지원합니다.
curl, Python 및 TypeScript 예제를 포함한 전체 엔드포인트 문서입니다.
두 SDK의 기반이 되는 버전화된 HTTP API입니다. 모든 언어에서 사용할 수 있습니다.
코드 생성을 위한 기계 판독 가능한 API 규격입니다.