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

신청 절차

HappyHorse Videos API를 사용하려면 먼저 Ace Data Cloud 콘솔에서 API Token을 발급받아 보관해 두세요. 아직 로그인하거나 가입하지 않은 경우, 로그인 페이지로 자동 이동하여 회원가입 및 로그인을 안내하며, 완료 후 현재 페이지로 자동으로 돌아옵니다. 하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 서비스별로 별도 신청할 필요가 없습니다. 최초 신청 시 무료 크레딧이 제공되어 무료로 체험할 수 있으며, 크레딧이 부족할 경우 콘솔에서 공용 잔액을 충전할 수 있습니다.
📘 전체 문서: HappyHorse Videos API →

작업 유형

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 등의 파라미터도 지정할 수 있습니다.
반환 결과 예시는 다음과 같습니다.
필드 설명:
  • 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 코드는 다음과 같습니다.
해당 Python 코드는 다음과 같습니다.

첫 프레임 이미지-비디오

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

참조 이미지-비디오

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

비디오 편집

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

비동기 콜백

동영상 생성에는 일정한 처리 시간이 필요합니다. 긴 연결을 유지하며 기다리지 않으려면 callback_url을 전달할 수 있으며, 이 경우 API는 즉시 task_id를 반환하고, 작업이 완료되면 최종 결과를 해당 주소로 POST합니다:
즉시 반환되는 결과는 다음과 같습니다:
폴링만 원하고 콜백이 필요하지 않은 경우에도 "async": true를 전달할 수 있으며, 이후 HappyHorse Tasks API를 통해 작업 결과를 조회합니다.

요금 설명

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: 서버 내부 오류 또는 생성 실패입니다.