hiapi API로 happyhorse-1.1 사용하는 방법: 텍스트→비디오, 이미지→비디오, 레퍼런스→비디오

happy horse 1.1 사용법을 찾고 있다면, 짧게 말해: happyhorse-1.1은 하나의 모델 엔드포인트가 아니라 세 개이며, 모두 hiapi의 통합 비동기 작업 API를 통해 제공됩니다:

엔드포인트(모델 ID)	기능	필수 입력
happyhorse-1.1/text-to-video	텍스트 프롬프트로 비디오 생성	prompt
happyhorse-1.1/image-to-video	정지 이미지를 움직이게 함	image_urls
happyhorse-1.1/reference-to-video	레퍼런스 이미지와 프롬프트의 안내로 비디오 생성	prompt, reference_image

이 세 엔드포인트는 동일한 생명주기를 공유합니다: POST /v1/tasks로 제출 → taskId 획득 → GET /v1/tasks/<id> 폴링(또는 콜백 수신) → output[0].url 다운로드. 아래의 모든 파라미터 표와 모든 오류 메시지는 실제 API에 대해 검증되었습니다—추측으로 작성된 내용은 없습니다.

사전 요구 사항

필요한 것은 단 하나, hiapi API 키입니다. hiapi 콘솔에서 발급받으세요—sk-... 형태이며, Authorization: Bearer 요청 헤더에 넣습니다. 비디오 생성은 출력 초 단위로 과금되며, 엔드포인트별 현재 초당 요금은 가격 페이지에서 확인할 수 있습니다.

export HIAPI_KEY="sk-your-key-here"

최소 실행 예제(텍스트→비디오)

작업 제출:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/text-to-video",
    "input": {
      "prompt": "A golden retriever puppy runs through a sunlit meadow, slow motion, cinematic",
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "duration": 5
    }
  }'

응답의 data.taskId 아래에서 작업 ID를 받게 됩니다. 이를 폴링하세요:

curl -s https://api.hiapi.ai/v1/tasks/<taskId> \
  -H "Authorization: Bearer $HIAPI_KEY"

data.status가 success가 되면 비디오 URL은 data.output[0].url에 있습니다. 즉시 다운로드하세요—출력 URL에는 expireAt 타임스탬프가 붙고 임시 저장소에 보관되므로, 영구 호스팅이 아니라 수령 기간으로 취급해야 합니다.

다음은 동일한 흐름의 전체 Python 스크립트입니다(표준 라이브러리만 사용):

import json
import time
import urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-your-key-here"

def api(method, url, payload=None):
    req = urllib.request.Request(url, method=method)
    req.add_header("Authorization", f"Bearer {KEY}")
    req.add_header("Content-Type", "application/json")
    data = json.dumps(payload).encode() if payload else None
    with urllib.request.urlopen(req, data=data) as resp:
        return json.loads(resp.read())

# 1. Submit
task = api("POST", API, {
    "model": "happyhorse-1.1/text-to-video",
    "input": {
        "prompt": "A golden retriever puppy runs through a sunlit meadow, cinematic",
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "duration": 5,
    },
})
task_id = task["data"]["taskId"]
print("submitted:", task_id)

# 2. Poll until terminal state
while True:
    data = api("GET", f"{API}/{task_id}")["data"]
    status = data["status"]
    if status == "success":
        video_url = data["output"][0]["url"]
        break
    if status == "fail":
        raise RuntimeError(f"task failed: {data.get('error')}")
    time.sleep(5)

# 3. Download before the URL expires
urllib.request.urlretrieve(video_url, "output.mp4")
print("saved output.mp4")

엔드포인트별 파라미터

입력 스키마는 엄격합니다: 알 수 없는 필드는 조용히 무시되지 않고 400으로 거부됩니다. size, seed, negative_prompt, audio 같은 필드는 모두 additional properties ... not allowed를 반환합니다. 다음은 각 엔드포인트가 정확히 허용하는 파라미터입니다.

happyhorse-1.1/text-to-video

필드	필수	타입	허용 값
prompt	✅	string	장면 설명
aspect_ratio	—	string	16:9, 9:16, 3:4, 4:3, 4:5, 5:4, 1:1, 9:21, 21:9
resolution	—	string	720p, 1080p
duration	—	integer	3–15(초)

프롬프트 작성 요령을 포함한 전체 설명: happyhorse-1.1 텍스트→비디오 튜토리얼.

happyhorse-1.1/image-to-video

필드	필수	타입	허용 값
image_urls	✅	문자열 배열	정확히 1개의 공개 접근 가능한 이미지 URL(maxItems: 1)
prompt	—	string	애니메이션용 움직임/장면 안내
resolution	—	string	720p, 1080p
duration	—	integer	3–15(초)

여기에는 흔히 걸리는 함정이 두 가지 있습니다. 첫째, image_urls는 배열이지만 현재 하나의 요소만 허용합니다—맨 문자열도, 여러 URL도 아닌 ["https://..."] 형태로 전달하세요. 둘째, 이 엔드포인트에는 aspect_ratio가 없습니다(API가 거부합니다). 출력 화면 비율은 소스 이미지를 따릅니다.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/image-to-video",
    "input": {
      "image_urls": ["https://your-cdn.example.com/product-shot.jpg"],
      "prompt": "slow camera push-in, soft studio lighting",
      "resolution": "720p",
      "duration": 5
    }
  }'

더 깊이 읽기: happy horse 이미지→비디오 튜토리얼.

happyhorse-1.1/reference-to-video

필드	필수	타입	허용 값
prompt	✅	string	장면 설명
reference_image	✅	문자열 배열	1–9개의 공개 접근 가능한 이미지 URL(maxItems: 9)
aspect_ratio	—	string	텍스트→비디오와 동일한 9가지 비율
resolution	—	string	720p, 1080p
duration	—	integer	3–15(초)

이것이 바로 '내 캐릭터/제품을 일관되게 유지'하는 엔드포인트입니다: 레퍼런스 이미지가 정체성과 스타일을 고정하고, 프롬프트가 동작을 이끕니다. 이미지→비디오와 달리 여기서는 aspect_ratio 제어권이 다시 주어지며, 최대 9장의 레퍼런스 이미지를 전달할 수 있습니다.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/reference-to-video",
    "input": {
      "prompt": "the character waves at the camera and smiles, city street at dusk",
      "reference_image": ["https://your-cdn.example.com/character-front.jpg",
                          "https://your-cdn.example.com/character-side.jpg"],
      "aspect_ratio": "9:16",
      "resolution": "720p",
      "duration": 5
    }
  }'

더 깊이 읽기: happyhorse-1.1 레퍼런스→비디오 튜토리얼.

어떤 엔드포인트를 선택해야 할까?

• 아이디어만 있다 → text-to-video. 텍스트에서 움직임으로 가는 가장 빠른 경로.
• 애니메이션화할 정확한 화면이 있다(제품 사진, 일러스트, 사진) → image-to-video. 소스 이미지가 곧 첫 프레임의 모습입니다.
• 여러 클립에 걸쳐 동일한 주체를 유지해야 한다(캐릭터, 마스코트, 제품의 여러 각도) → reference-to-video. 레퍼런스 이미지가 정체성을 고정하고, 프롬프트는 클립마다 달라집니다.

프로덕션 실전 패턴

폴링 대신 콜백 사용

스크립트 범위를 넘어서는 모든 용도에서는 작업 생성 시 webhook을 등록하세요—비디오 작업은 오래 걸리므로 웹 요청 핸들러에서 폴링하면 결국 타임아웃이 납니다:

{
  "model": "happyhorse-1.1/text-to-video",
  "input": { "prompt": "..." },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

"when": "final"만 지원됩니다—작업이 종료 상태에 도달하면 POST를 한 번만 받습니다(다른 값은 invalid callback.when: only 'final' is supported를 반환합니다). 수신 측은 taskId 기반으로 멱등하게 설계하세요: 제출 시 작업 ID를 저장하고, 중복 또는 이미 처리된 콜백은 무시하세요. 네트워크 문제로 콜백이 유실된 경우를 대비해 저빈도 폴링 스위퍼를 하나 남겨 두세요.

오류 처리: 세 가지 실패 유형

1. 검증 오류(HTTP 400, INVALID_REQUEST). 메시지가 매우 정확합니다—읽어 보면 정확한 필드를 알려 줍니다:

{
  "code": 400,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: duration: maximum: got 99, want 15; resolution: value must be one of '720p', '1080p'"
}

2. 인증/권한 오류(HTTP 401, permission_denied). 키가 틀렸거나 키에 이 모델 접근 권한이 없습니다:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key cannot use the selected model. ...",
    "request_id": "2026..."
  }
}

콘솔에서 키를 확인하고, 지원팀에 문의할 경우 request_id를 함께 전달하세요.

3. 생성 실패(작업 status: "fail"). 제출은 성공했으나 생성이 실패한 경우로, 폴링 또는 콜백 수신 시 오류 상세 정보는 작업 객체의 error 필드에 있습니다. 이 유형은 백오프 재시도할 가치가 있지만, 검증 오류와 인증 오류는 그렇지 않습니다.

비용 제어

과금은 생성된 비디오 초 단위로 이루어지므로 duration이 주요 비용 레버입니다—15초 클립은 5초 클립의 3배 비용이 들며, resolution의 영향은 상대적으로 작습니다. duration: 3과 720p로 프롬프트를 반복 개선한 뒤 최종 버전을 전체 길이로 렌더링하세요. 현재 요금은 가격 페이지를 참고하세요.

관련 읽을거리

• happyhorse-1.1 텍스트→비디오—모델 페이지 및 체험장
• happyhorse-1.1 이미지→비디오—모델 페이지 및 체험장
• happyhorse-1.1 레퍼런스→비디오—모델 페이지 및 체험장
• happyhorse-1.1을 활용한 숏폼 비디오 워크플로
• hiapi 문서

자주 묻는 질문

이미지와 텍스트 프롬프트를 함께 사용할 수 있나요? 네—image-to-video는 필수인 image_urls 외에 선택적 prompt도 받으며, reference-to-video는 prompt와 reference_image를 모두 요구합니다. 프롬프트만 사용하는 것은 text-to-video뿐입니다.

이미지를 몇 장까지 전달할 수 있나요? image-to-video: 정확히 한 장(image_urls는 최대 1개 요소). reference-to-video: reference_image에 최대 아홉 장. 둘 다 업로드 파일이나 base64가 아닌, 공개 접근 가능한 URL 배열을 받습니다.

happyhorse-1.1은 seed, negative_prompt 또는 audio 파라미터를 지원하나요? 아니요. 입력 스키마가 엄격하여 이 세 가지는 모두 400 additional properties not allowed 오류로 거부됩니다. 재현성이 필요하다면 프롬프트와 파라미터를 완전히 동일하게 유지하고, 버전 관리는 여러분 쪽에서 하세요.

사용 가능한 해상도와 길이는 무엇인가요? 세 엔드포인트 모두: 720p 또는 1080p, 그리고 3~15초(정수). 생략하면 기본값이 적용됩니다.

유효해 보이는 키를 사용했는데 왜 401 permission_denied를 받나요? 키는 존재하지만 이 모델을 사용할 수 없습니다—범위 제한 키나 체험 키에서 흔히 발생합니다. 콘솔에서 해당 키의 모델 권한을 확인하거나, 제한 없는 새 키를 발급받으세요.

폴링 없이 비디오가 언제 준비되는지 어떻게 알 수 있나요? 제출 시 callback: {"url": "...", "when": "final"}을 전달하세요. 작업이 success 또는 fail에 도달하면 hiapi가 여러분의 URL로 한 번 POST합니다. 출력 URL은 만료된다는 점을 기억하세요—콜백 핸들러에서 파일을 다운로드하고, 핫링크하지 마세요.