> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-willie-des-1087-router-migration-block.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# v1 Cloud API 개요

> 지원 중단된 v1 Cloud API 범위: 인증과 Comfy API v2가 아직 제공하지 않는 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)에서 지원하지 않는 기능을 포함합니다. Comfy API 배포와 자체 호스팅 ComfyUI에서도 작동하는 방식으로 워크플로를 제출하고 결과를 가져오려면 v2(또는 이를 래핑하는 SDK)를 사용하십시오. 그 주변의 Cloud 특화 기능에는 v1을 사용하십시오.

워크플로를 실행하려면 [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
```

## 인증

모든 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>