/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를 사용할 때 편집할 비디오 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: 서버 내부 오류 또는 생성 실패입니다.

