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

# 클라우드 API 개요

> 워크플로 실행, 파일 관리 및 실행 모니터링을 위한 Comfy Cloud에 대한 프로그래밍 방식 접근

<Warning>
  **지원 중단됨:** v1 Cloud API는 [Comfy API v2](/ko/api-reference/v2/overview)로 대체되어 지원 중단되었습니다. 기존 통합 및 v2가 아직 노출하지 않는 Cloud 기능을 위해 계속 사용할 수 있지만, 엔드포인트와 동작은 사전 통지 없이 변경될 수 있습니다.
</Warning>

v1 Cloud API는 클라우드 인프라에서 워크플로를 실행하는 Comfy의 관리형 서비스인 [Comfy Cloud](/ko/development/deploy/cloud)에 프로그래밍 방식으로 접근할 수 있게 해줍니다.

Comfy Cloud는 상태 저장 애플리케이션입니다. 계정에는 작업 간에 유지되는 상태가 포함됩니다: 크레딧과 구독 등급, 업로드된 에셋과 생성된 출력, 작업 대기열, 설치된 모델 및 노드 집합 등입니다. v1 API는 그 전체 애플리케이션의 인터페이스이므로, 이식 가능한 [Comfy API v2](/ko/api-reference/v2/overview)에서 지원되지 않는 기능(예: 실행 대기열 관리, 모델 탐색, 노드 정의, 계정 엔드포인트)을 포함합니다. v2(또는 이를 래핑하는 SDK)를 사용하여 워크플로를 제출하고 결과를 검색하십시오. 이는 서버리스 배포와 자체 호스팅 ComfyUI에서도 작동하는 방식입니다. v1은 그 주변의 Cloud 고유 기능에 사용하십시오.

워크플로를 실행하려면 [Comfy Cloud 퀵스타트](/ko/development/deploy/cloud#빠른-시작)와 [Comfy SDKs](/ko/development/api-development/sdks)부터 시작하십시오. 크레딧 및 동시성 제한은 [Comfy Cloud 페이지](/ko/development/deploy/cloud)에서 다루며, 실행 가능한 v1 예제는 [Cloud API 참조](/ko/development/cloud/api-reference)에서 확인할 수 있습니다. 이 페이지에서는 v1 고유의 인터페이스(인증 및 v2가 노출하지 않는 엔드포인트)를 다룹니다.

<Note>
  **구독 필요:** API 액세스에는 유료 Comfy Cloud 구독이 필요하며, 무료 등급에는 포함되지 않습니다. [가격 페이지](https://www.comfy.org/cloud/pricing?utm_source=docs\&utm_campaign=cloud-api)를 참조하십시오.
</Note>

## 기본 URL

```
https://cloud.comfy.org
```

이 URL은 SDK의 기본 대상이기도 하므로 Comfy Cloud에서는 별도로 구성할 필요가 없습니다. 동일한 코드를 서버리스 배포 또는 자체 ComfyUI에 연결하려면 `COMFY_BASE_URL`을 설정하세요. [기본 URL 선택](/ko/development/api-development/sdks#기본-url-선택)을 참조하세요.

## 인증

모든 v1 요청에는 `X-API-Key` 헤더에 전달된 API 키가 필요합니다:

```bash theme={null}
curl -X GET "https://cloud.comfy.org/api/user" \
  -H "X-API-Key: $COMFY_CLOUD_API_KEY"
```

키 생성 및 관리에 대한 지침은 [API 키 얻기](/ko/development/api-development/getting-an-api-key)를 참조하십시오. 유효하지 않거나 누락된 키는 `401`을 반환합니다. 비활성 구독 상태의 키는 `429`를 반환합니다.

동일한 키가 [파트너 노드](/ko/tutorials/partner-nodes/overview)에도 사용됩니다. HTTP를 통해서는 `extra_data.api_key_comfy_org`에 다시 전달합니다. 예시는 [파트너 노드 사용](/ko/development/cloud/api-reference#파트너-노드-사용)을 참조하십시오.

## 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#객체-정보)      |
| 사용 가능한 모델 찾아보기           | 모델 엔드포인트                | [OpenAPI 사양](/ko/development/cloud/openapi)             |
| 계정 및 사용자 정보              | `GET /api/user`         | [OpenAPI 사양](/ko/development/cloud/openapi)             |
| 기존 이미지를 참조하는 마스크 업로드     | `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#오류-처리)를 참조하세요.

## 다음 단계

<CardGroup cols={2}>
  <Card title="Comfy Cloud" icon="cloud" href="/ko/development/deploy/cloud">
    빠른 시작, 크레딧 및 동시성 제한.
  </Card>

  <Card title="클라우드 API 참조" icon="book" href="/ko/development/cloud/api-reference">
    curl, Python 및 TypeScript 예제를 포함한 전체 엔드포인트 문서입니다.
  </Card>

  <Card title="Comfy API v2 참조" icon="cloud" href="/ko/api-reference/v2/overview">
    두 SDK의 기반이 되는 버전화된 HTTP API입니다. 모든 언어에서 사용할 수 있습니다.
  </Card>

  <Card title="OpenAPI 규격" icon="file-code" href="/ko/development/cloud/openapi">
    코드 생성을 위한 기계 판독 가능한 API 규격입니다.
  </Card>
</CardGroup>