> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# HappyHorse Videos API 연동 안내

> HappyHorse Video API guide - Ace Data Cloud

이 문서는 HappyHorse Videos API의 연동 방식을 소개합니다. 이 인터페이스는 통합 `/happyhorse/videos` 엔드포인트와 `action` 파라미터를 통해 텍스트-비디오, 첫 프레임 이미지-비디오, 참조 이미지-비디오 및 비디오 편집을 지원합니다.

## 신청 절차

HappyHorse Videos API를 사용하려면 먼저 [Ace Data Cloud 콘솔](https://platform.acedata.cloud/console/applications)에서 API Token을 발급받아 보관해 두세요.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

아직 로그인하거나 가입하지 않은 경우, 로그인 페이지로 자동 이동하여 회원가입 및 로그인을 안내하며, 완료 후 현재 페이지로 자동으로 돌아옵니다.

**하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 서비스별로 별도 신청할 필요가 없습니다.** 최초 신청 시 무료 크레딧이 제공되어 무료로 체험할 수 있으며, 크레딧이 부족할 경우 [콘솔](https://platform.acedata.cloud/console/coin)에서 공용 잔액을 충전할 수 있습니다.

> 📘 전체 문서: [HappyHorse Videos API →](https://platform.acedata.cloud/documents/happyhorse-videos)

## 작업 유형

`action`은 이번 요청의 생성 모드를 결정합니다.

* `generate`: 텍스트-비디오, 기본 action이며, `happyhorse-1.0-t2v` 및 `happyhorse-1.1-t2v`를 지원하고, 반드시 `prompt`를 전달해야 합니다.
* `image_to_video`: 첫 프레임 이미지-비디오이며, `happyhorse-1.0-i2v` 및 `happyhorse-1.1-i2v`를 지원하고, 반드시 `image_url`을 전달해야 합니다.
* `reference_to_video`: 참조 이미지-비디오이며, `happyhorse-1.0-r2v` 및 `happyhorse-1.1-r2v`를 지원하고, 반드시 `prompt`와 1–9개의 `image_urls`를 전달해야 합니다.
* `video_edit`: 비디오 편집이며, `happyhorse-1.0-video-edit`를 지원하고, 반드시 `prompt`와 `video_url`을 전달해야 하며, 0–5개의 참조 이미지 `image_urls`를 추가로 전달할 수 있습니다.

각 작업은 기본적으로 1.1 모델을 사용하며, `video_edit`는 현재 `happyhorse-1.0-video-edit`만 제공합니다.

## 기본 사용법

텍스트-비디오는 `prompt`만 제공하면 되며, `resolution`, `ratio`, `duration` 등의 파라미터도 지정할 수 있습니다.

```json theme={null}
{
  "action": "generate",
  "model": "happyhorse-1.1-t2v",
  "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}
```

반환 결과 예시는 다음과 같습니다.

```json theme={null}
{
  "success": true,
  "task_id": "27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1",
  "trace_id": "6071ab5e-2f37-46f0-9e07-f1e378112e69",
  "data": [
    {
      "id": "9650580f-6d9e-4bc1-823a-29011790c5cb",
      "video_url": "https://cdn.acedata.cloud/assets/examples/happyhorse/27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1-2c108ce23554.mp4",
      "state": "succeeded",
      "duration": 5,
      "resolution": "720P",
      "ratio": null
    }
  ]
}
```

필드 설명:

* `success`: 이번 요청의 성공 여부입니다.
* `task_id`: Ace Data Cloud 측 작업 ID이며, 작업 상태 조회에 사용할 수 있습니다.
* `trace_id`: 이번 요청의 추적 ID이며, 문제를 조사하는 데 사용됩니다.
* `data`: 비디오 결과 목록입니다.
  * `id`: HappyHorse 측 작업 ID입니다.
  * `video_url`: 생성된 비디오의 CDN 링크 주소입니다.
  * `state`: 작업 상태이며, `pending` / `succeeded` / `error` 중 하나입니다.
  * `duration`: 과금 비디오 길이이며, 단위는 초입니다. `video_edit`는 입력 및 출력 비디오 길이의 합계입니다.
  * `resolution`: 출력 해상도입니다.
  * `ratio`: 출력 가로세로 비율입니다.

해당 CURL 코드는 다음과 같습니다.

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/happyhorse/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "happyhorse-1.1-t2v",
  "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}'
```

해당 Python 코드는 다음과 같습니다.

```python theme={null}
import requests

url = "https://api.acedata.cloud/happyhorse/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json",
}

payload = {
    "action": "generate",
    "model": "happyhorse-1.1-t2v",
    "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
    "resolution": "720P",
    "ratio": "16:9",
    "duration": 5,
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

## 첫 프레임 이미지-비디오

`image_to_video`를 사용할 때 `image_url`은 비디오의 첫 프레임으로 사용됩니다. 출력 가로세로 비율은 첫 프레임 이미지를 최대한 따르므로, 이 작업에는 `ratio`를 전달할 필요가 없습니다.

```json theme={null}
{
  "action": "image_to_video",
  "model": "happyhorse-1.1-i2v",
  "image_url": "https://cdn.acedata.cloud/b1c82e4937.png",
  "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
  "resolution": "1080P",
  "duration": 5
}
```

## 참조 이미지-비디오

`reference_to_video`를 사용할 때 `image_urls`에 1–9개의 참조 이미지를 전달할 수 있습니다. 프롬프트에서 `character1`, `character2` 등의 방식으로 해당 순서의 이미지를 참조할 수 있습니다.

```json theme={null}
{
  "action": "reference_to_video",
  "model": "happyhorse-1.1-r2v",
  "prompt": "character1 walks forward through a sunrise meadow with the warm leather and gold trim style from character2",
  "image_urls": [
    "https://cdn.acedata.cloud/b1c82e4937.png",
    "https://cdn.acedata.cloud/eb75d88a3f.png"
  ],
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}
```

## 비디오 편집

`video_edit`를 사용할 때 편집할 비디오 `video_url`과 편집 의도 `prompt`를 반드시 전달해야 합니다. 선택 사항인 `image_urls`는 의상 변경, 스타일 전이 또는 부분 교체 등의 참조 이미지로 사용됩니다. `audio_setting`은 `auto` 또는 `origin` 중에서 선택할 수 있으며, `origin`은 원본 비디오 오디오를 유지함을 의미합니다.

```json theme={null}
{
  "action": "video_edit",
  "model": "happyhorse-1.0-video-edit",
  "prompt": "Apply the warm leather and gold trim style from the reference image while preserving the original camera motion",
  "video_url": "https://cdn.acedata.cloud/assets/examples/happyhorse/27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1-2c108ce23554.mp4",
  "image_urls": [
    "https://cdn.acedata.cloud/eb75d88a3f.png"
  ],
  "resolution": "720P",
  "audio_setting": "auto"
}
```

## 비동기 콜백

동영상 생성에는 일정한 처리 시간이 필요합니다. 긴 연결을 유지하며 기다리지 않으려면 `callback_url`을 전달할 수 있으며, 이 경우 API는 즉시 `task_id`를 반환하고, 작업이 완료되면 최종 결과를 해당 주소로 POST합니다:

```json theme={null}
{
  "action": "generate",
  "prompt": "A horse running through a snowy forest",
  "duration": 5,
  "callback_url": "https://your-domain.com/callback/happyhorse"
}
```

즉시 반환되는 결과는 다음과 같습니다:

```json theme={null}
{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}
```

폴링만 원하고 콜백이 필요하지 않은 경우에도 `"async": true`를 전달할 수 있으며, 이후 [HappyHorse Tasks API](https://platform.acedata.cloud/documents/happyhorse-tasks)를 통해 작업 결과를 조회합니다.

## 요금 설명

HappyHorse는 출력 동영상의 초 수와 해상도에 따라 요금이 부과됩니다:

* `720P`: 최저 약 \$0.105 / 초.
* `1080P`: 최저 약 \$0.18 / 초.
* `video_edit`: 입력 동영상과 출력 동영상의 총 길이를 기준으로 요금이 부과되며, 실제 청구 시간은 작업 완료 후의 통계를 기준으로 합니다.

실패한 작업에는 요금이 부과되지 않으며, 무료 할당량도 차감되지 않습니다.

## 오류 처리

요청에 문제가 발생하면 API는 해당 오류 코드와 설명을 반환하며, 일반적인 항목은 다음과 같습니다:

* `400`: 요청 매개변수가 잘못되었습니다. 예를 들어 action과 model이 일치하지 않거나, `prompt` / `image_url` / `video_url`이 누락되었거나, `duration`이 3–15초 범위를 초과한 경우입니다.
* `401`: 인증에 실패했습니다. token이 유효하지 않거나 API와 일치하지 않습니다.
* `403`: 잔액이 부족하거나, 프롬프트가 콘텐츠 검토에 걸려 거부되었습니다.
* `429`: 요청이 너무 빈번하여 속도 제한이 트리거되었습니다. 잠시 후 다시 시도하십시오.
* `500`: 서버 내부 오류 또는 생성 실패입니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.