/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를 전달할 수 있습니다.
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: 출력 화면 비율입니다.
첫 프레임 이미지-비디오 생성
image_to_video를 사용할 때 image_url은 비디오의 첫 프레임으로 사용됩니다. 출력 화면 비율은 첫 프레임 이미지를 최대한 따르므로, 이 작업에서는 ratio를 전달할 필요가 없습니다.
참조 이미지-비디오 생성
reference_to_video를 사용할 때 image_urls에는 1–9장의 참조 이미지를 전달할 수 있습니다. 프롬프트에서 character1, character2 등의 방식으로 해당 순서의 이미지를 참조할 수 있습니다.
비디오 편집
video_edit의 출력 길이와 화면 비율은 원본 비디오를 상속하며, duration 또는 ratio를 전달해도 변경되지 않습니다. 이미지-비디오 생성의 화면 비율도 원본 이미지를 상속합니다. 편집 비용은 입력 및 출력 비디오 길이의 합계를 기준으로 계산됩니다.
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: 서버 내부 오류 또는 생성 실패입니다.

