지도 시간
HappyHorse 1.1 API 가이드: EvoLink로 AI 비디오 생성하기
EvoLink Team
Product Team
2026년 6월 22일
15분 소요
EvoLink에서 HappyHorse 1.1 API 사용하는 방법
EvoLink를 통해 HappyHorse 1.1을 사용할 때의 실무 흐름은 다음과 같습니다.
- 입력 타입에 맞는 HappyHorse 1.1 model ID를 선택합니다.
POST /v1/videos/generations로 비디오 생성 task를 만듭니다.- 반환된 task ID를 저장합니다.
GET /v1/tasks/{task_id}를 polling하거나callback_url을 설정합니다.- 생성된 비디오를 애플리케이션이 의존하기 전에 저장하거나 자체 storage로 옮깁니다.
이 글은 EvoLink로 개발하는 팀을 위한 가이드입니다. 통합 의사결정과 프로덕션 워크플로를 설명하며, 현재 가격, 파라미터 범위, 요청 스키마는 HappyHorse 1.1 API 페이지와 API 레퍼런스를 기준으로 확인해야 합니다.
빠른 결론
HappyHorse 1.1은 EvoLink에서 세 가지 라우트를 제공합니다.
| 사용 사례 | Model ID | 적합한 경우 |
|---|---|---|
| Text-to-video | happyhorse-1.1-text-to-video | prompt만으로 시작하는 앱 |
| Image-to-video | happyhorse-1.1-image-to-video | 첫 프레임 이미지가 하나 있는 앱 |
| Reference-to-video | happyhorse-1.1-reference-to-video | 1-9개의 순서 있는 reference image가 필요한 워크플로 |
세 라우트 모두 EvoLink의 통합 비디오 생성 흐름을 사용합니다. API key 인증, async task 생성, task status 조회, 선택적
callback_url, 생성 초 단위 billing이 동일한 방식으로 작동합니다.HappyHorse 1.1을 이전 HappyHorse 1.0 라우트와 섞지 마세요. 현재 EvoLink에서 노출된 HappyHorse 1.1 통합면은 위 세 가지 라우트입니다.
확인된 정보
| 항목 | EvoLink의 HappyHorse 1.1 |
|---|---|
| API availability | EvoLink에서 사용 가능 |
| task 생성 | POST /v1/videos/generations |
| task 상태 조회 | GET /v1/tasks/{task_id} |
| delivery 방식 | async task 생성 및 상태 조회 |
| callback 지원 | create request에서 callback_url 사용 가능 |
| 출력 해상도 | 720p, 1080p |
| 길이 | 3-15초 정수 |
| 결과 링크 | 24시간 유효. 완료 후 즉시 저장하거나 옮겨야 함 |
| 과금 | 생성 초 단위, 해상도와 길이에 영향 |
| 가격 출처 | HappyHorse 1.1 가격표 |
비디오 생성은 동기 API 호출이 아니라 async production job으로 설계해야 합니다.
올바른 라우트 선택
가장 흔한 실수는 입력 asset이 아니라 라우트 이름만 보고 선택하는 것입니다.
| 입력 asset | 추천 라우트 | 이유 |
|---|---|---|
| prompt만 있음 | happyhorse-1.1-text-to-video | prompt-first 생성이며 aspect ratio 계획이 명확함 |
| 제품, 인물, 장면 이미지 1장 | happyhorse-1.1-image-to-video | 이미지를 첫 프레임으로 사용하고 출력 비율은 원본에서 결정됨 |
| 여러 인물, 오브젝트, 스타일 reference | happyhorse-1.1-reference-to-video | prompt에서 character1, character2 등으로 순서 있는 이미지를 참조 가능 |
아이디어 탐색은 text-to-video, asset animation은 image-to-video, 여러 reference 간 일관성이 중요하면 reference-to-video를 사용하세요.
사전 준비
| 준비 항목 | 해야 할 일 |
|---|---|
| EvoLink API key | EvoLink 계정에서 API key 생성 |
| 공개 이미지 URL | image-to-video와 reference-to-video에 필요 |
| Model ID | 세 가지 HappyHorse 1.1 라우트 중 선택 |
| 저장 계획 | 완료된 비디오를 저장할 위치 결정 |
| 콜백 엔드포인트 | 프로덕션 queue에서는 HTTPS callback 권장 |
| 비용 guardrail | batch job 전에 기본 duration, resolution, retry limit 설정 |
이미지 입력은 공개 HTTP 또는 HTTPS URL이어야 합니다. 내부망 링크, 인증이 필요한 object storage URL, local file은 프로덕션 입력으로 적합하지 않습니다.
기본 request flow
| 단계 | API action | 앱이 저장해야 할 것 |
|---|---|---|
| task 생성 | POST /v1/videos/generations | Task ID, model ID, user ID, 요청 duration, quality |
| task 추적 | GET /v1/tasks/{task_id} | status, progress, output link, usage |
| task 완료 | polling 또는 callback_url | 최종 비디오 asset, 최종 상태, 과금 metadata |
| 결과 저장 | 자체 storage | 안정적인 URL, job history, audit trail |
EvoLink 비디오 라우트는 같은 endpoint pattern을 공유합니다. 핵심은 올바른
model 값과 라우트별 input을 전달하는 것입니다.Text-to-video 예시
prompt만으로 시작할 때 사용합니다. 필수 필드는
model과 prompt입니다.curl --request POST \
--url https://api.evolink.ai/v1/videos/generations \
--header 'Authorization: Bearer <EVOLINK_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"model": "happyhorse-1.1-text-to-video",
"prompt": "A cinematic product shot of a transparent electric scooter moving through a clean studio space, slow dolly camera, soft reflections",
"quality": "720p",
"aspect_ratio": "16:9",
"duration": 5,
"callback_url": "https://your-domain.com/webhooks/video-task-completed"
}'| Parameter | 계획 팁 |
|---|---|
prompt | subject, scene, camera movement, motion, lighting, style을 설명 |
quality | 먼저 720p로 테스트하고 prompt가 안정되면 1080p로 전환 |
aspect_ratio | 최종 배포 채널에 맞춰 16:9, 9:16, 1:1 등을 선택 |
duration | 테스트는 3-5초부터 시작 |
seed | 재현 가능한 반복이 필요할 때만 고정 |
Image-to-video 예시
첫 프레임 이미지가 하나 있을 때 사용합니다. 필수 필드는
model과 image_urls입니다.curl --request POST \
--url https://api.evolink.ai/v1/videos/generations \
--header 'Authorization: Bearer <EVOLINK_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"model": "happyhorse-1.1-image-to-video",
"image_urls": ["https://cdn.example.com/product-hero.png"],
"prompt": "Animate the product with a smooth camera orbit and subtle studio lighting movement",
"quality": "720p",
"duration": 5,
"callback_url": "https://your-domain.com/webhooks/video-task-completed"
}'| 규칙 | 요구사항 |
|---|---|
| 이미지 수 | 첫 프레임 이미지 정확히 1장 |
| 포맷 | JPEG, JPG, PNG, WEBP |
| 최소 크기 | 너비와 높이 각각 300 px 이상 |
| aspect ratio | 원본 이미지가 지원 범위 내 |
| 파일 크기 | 이미지당 10MB 이하 |
| URL 접근 | 공개 HTTP 또는 HTTPS |
Image-to-video는 출력 aspect ratio를 원본 이미지에서 결정합니다. 이 라우트를 명시적
aspect_ratio 필드 중심으로 설계하지 마세요.Reference-to-video 예시
prompt가 순서 있는 reference image를 참조해야 할 때 사용합니다. 필수 필드는
model, prompt, image_urls입니다.curl --request POST \
--url https://api.evolink.ai/v1/videos/generations \
--header 'Authorization: Bearer <EVOLINK_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"model": "happyhorse-1.1-reference-to-video",
"prompt": "character1 walks into the scene, picks up the object shown as character2, and places it on the table beside character3",
"image_urls": [
"https://cdn.example.com/person.png",
"https://cdn.example.com/object.png",
"https://cdn.example.com/scene.png"
],
"quality": "720p",
"aspect_ratio": "16:9",
"duration": 5,
"callback_url": "https://your-domain.com/webhooks/video-task-completed"
}'| 규칙 | 요구사항 |
|---|---|
| 이미지 수 | 1-9개의 reference image |
| prompt 규칙 | character1, character2, character3 등을 사용 |
| 순서 | 첫 번째 URL이 character1, 두 번째가 character2 |
| 포맷 | JPEG, JPG, PNG, WEBP |
| 권장 품질 | 선명한 이미지, 짧은 변 400 px 이상, 짧은 변/긴 변 비율 0.4 이상 |
| 파일 크기 | 이미지당 10MB 이하 |
| URL | 공개 HTTP 또는 HTTPS |
명시적인
character1 / character2 참조가 없으면 인물이나 오브젝트가 혼동될 수 있습니다. 사용자가 본 순서와 최종 image_urls 배열을 함께 저장하세요.Async status와 callback_url
task를 생성하면 앱은 task ID를 받습니다. 즉시 저장한 뒤 상태를 조회합니다.
curl --request GET \
--url https://api.evolink.ai/v1/tasks/<TASK_ID> \
--header 'Authorization: Bearer <EVOLINK_API_KEY>'Task response에는 status, progress, model, task information, result details, usage information이 포함될 수 있습니다.
| 방식 | 사용할 때 | tradeoff |
|---|---|---|
| Polling | 로컬 테스트 또는 작은 admin workflow | 단순하지만 queue load를 늘릴 수 있음 |
callback_url | 사용자 대상 생성 기능을 프로덕션에서 운영 | 더 깔끔하지만 안전한 HTTPS endpoint 필요 |
callback_url은 HTTPS를 사용해야 하며 private IP를 가리키지 않아야 합니다. handler는 idempotent하게 설계하세요.비용 계획
HappyHorse 1.1은 EvoLink에서 생성 초 단위로 과금됩니다. 이 글은 실시간 가격 출처가 아니므로 프로덕션 rollout 전 HappyHorse 1.1 가격표을 확인하세요.
| 비용 요인 | 중요한 이유 | practical guardrail |
|---|---|---|
| Duration | 생성 초가 늘수록 비용 증가 | 기본 테스트는 3-5초 |
| 해상도 | 높은 해상도는 과금에 영향 | prompt 품질은 720p에서 먼저 검증 |
| 재시도 | 무분별한 재시도는 비용을 증폭 | 명확한 일시적 실패만 재시도 |
| 라우트 선택 | reference workflow는 운영 복잡도 증가 | first frame 하나로 충분하면 image-to-video 사용 |
| 배치 크기 | batch job은 비용 spike를 숨길 수 있음 | user/job 단위 limit 설정 |
프로덕션 체크리스트
| 영역 | 체크리스트 |
|---|---|
| 모델 라우팅 | product action을 올바른 HappyHorse 1.1 model ID에 매핑 |
| 입력 검증 | prompt length, image count, public URL, format, size 검증 |
| 큐 설계 | 모든 video job을 async job으로 처리하고 task ID 저장 |
| 콜백 보안 | HTTPS, payload validation, idempotent handler |
| 비용 제어 | duration, quality, account limit 기본값 설정 |
| asset 저장 | 24시간 결과 링크 유효기간 안에 자체 storage로 이동 |
| fallback 모델 | 다른 EvoLink video route 준비 |
| 모니터링 | failure rate, completion time, retry rate, spend 추적 |
EvoLink의 통합 API gateway를 사용하면 HappyHorse, Seedance, Kling, Sora 또는 다른 video model 간 전환은 새 vendor integration이 아니라 model selection 문제가 됩니다.
Troubleshooting
| 증상 | 가능한 원인 | 해결 |
|---|---|---|
model_access_denied | API key에 model access가 없음 | 계정 권한 확인 및 HappyHorse 1.1 페이지의 model ID 사용 |
| Image-to-video 요청 실패 | image_urls 누락 또는 URL 비공개 | 공개 이미지 URL 1개 전달 |
| Reference output이 인물 혼동 | prompt가 character1, character2를 사용하지 않음 | prompt reference와 image array 순서 일치 |
| aspect ratio가 예상과 다름 | image-to-video에서 명시 제어를 기대 | 원본 이미지 비율 조정 |
| 비용이 예상보다 높음 | duration, resolution, retry, batch 증가 | 짧은 720p 테스트와 spend limit 사용 |
| 사용자 요청 timeout | 앱이 비디오 생성을 동기 처리 | task ID 저장 후 polling 또는 callback 사용 |
구현 패턴
type HappyHorseRoute =
| 'text-to-video'
| 'image-to-video'
| 'reference-to-video'
const happyHorseModelIdByRoute: Record<HappyHorseRoute, string> = {
'text-to-video': 'happyhorse-1.1-text-to-video',
'image-to-video': 'happyhorse-1.1-image-to-video',
'reference-to-video': 'happyhorse-1.1-reference-to-video',
}Routing layer는 product logic 뒤에 두는 것이 좋습니다. UI는 사용자가 가진 asset을 묻고, backend는 이를 model ID와 검증된 request body로 변환합니다.
다른 EvoLink 비디오 모델을 고려할 때
| 필요 | 고려할 모델 |
|---|---|
| video 또는 audio reference | Seedance 2.0 |
| 반복 가능한 short-form production | Kling 3.0 |
| 다른 creative style | EvoLink model catalog에서 다른 route 비교 |
FAQ
HappyHorse 1.1에는 어떤 endpoint를 사용하나요?
POST /v1/videos/generations를 사용하고 입력 타입에 맞는 HappyHorse 1.1 model ID를 전달합니다.HappyHorse 1.1 model ID는 무엇인가요?
happyhorse-1.1-text-to-video, happyhorse-1.1-image-to-video, happyhorse-1.1-reference-to-video입니다.prompt만 있을 때 어떤 model ID를 쓰나요?
happyhorse-1.1-text-to-video를 사용합니다.첫 프레임 이미지 animation에는 무엇을 쓰나요?
happyhorse-1.1-image-to-video를 사용합니다.여러 reference image에는 무엇을 쓰나요?
1-9개의 순서 있는 이미지에는
happyhorse-1.1-reference-to-video를 사용하고 prompt에서 character1, character2 등을 참조합니다.Image-to-video는 aspect_ratio를 지원하나요?
아니요. output ratio는 원본 이미지에서 결정됩니다. 명시적 aspect ratio 계획이 필요하면 text-to-video 또는 reference-to-video를 사용하세요.
callback_url을 사용할 수 있나요?
네. HTTPS를 사용하고 callback handler를 idempotent하게 설계하세요.
현재 가격은 어디서 확인하나요?
HappyHorse 1.1 가격표을 확인하세요. 이 가이드는 비용 요인을 설명하지만 가격 출처는 모델 페이지입니다.
같은 EvoLink API key를 사용할 수 있나요?
네. HappyHorse 1.1은 같은 EvoLink API key와 과금 시스템을 사용합니다.
HappyHorse 1.1은 video-edit를 지원하나요?
현재 HappyHorse 1.1 페이지와 API 레퍼런스는 text-to-video, image-to-video, reference-to-video를 노출합니다. HappyHorse 1.0 video-edit route를 HappyHorse 1.1처럼 사용하지 마세요.
