# Happy Horse 1.1 API Alibaba Happy Horse 1.1 비디오 생성 모델을 위한 전체 API 레퍼런스입니다. ## 모델 변형 이 API는 세 가지 모델 변형을 지원합니다. | 모델 | ID | 설명 | | --------------------------------------- | ------------------------------------ | ---------------------------------------------------- | | **Happy Horse 1.1 Text to Video** | `happyhorse-1.1-text-to-video` | 텍스트 프롬프트에서 바로 비디오를 생성합니다 | | **Happy Horse 1.1 Image to Video** | `happyhorse-1.1-image-to-video` | 프롬프트 안내에 따라 단일 첫 프레임 이미지를 움직이게 합니다 | | **Happy Horse 1.1 Reference to Video** | `happyhorse-1.1-reference-to-video` | 최대 9장의 참조 이미지 안내에 따라 비디오를 생성합니다 | ## 빠른 비교 | 기능 | Text to Video | Image to Video | Reference to Video | | -------------- | ------------------------- | ------------------------- | ------------------------- | | 입력 | 텍스트 프롬프트 | 첫 프레임 이미지 + 프롬프트 | 참조 이미지 + 프롬프트 | | 길이 범위 | 3-15초 | 3-15초 | 3-15초 | | 해상도 | 720p, 1080p(기본값 1080p) | 720p, 1080p(기본값 1080p) | 720p, 1080p(기본값 1080p) | | 종횡비 | 9가지 비율 지원(기본값 16:9) | 지원하지 않음(입력 이미지 따름) | 9가지 비율 지원(기본값 16:9) | | Seed | 선택 사항 | 선택 사항 | 선택 사항 | ### 지원되는 종횡비(Text to Video 및 Reference to Video) | 비율 | 설명 | | ------ | ---------------------- | | `16:9` | 가로(와이드스크린) | | `9:16` | 세로(버티컬) | | `3:4` | 표준 세로 | | `4:3` | 표준 가로 | | `4:5` | 세로 | | `5:4` | 가로 | | `1:1` | 정사각형 | | `9:21` | 초고세로 | | `21:9` | 초광각 가로 | ## Happy Horse 1.1 Text to Video ### 엔드포인트 ``` POST /api/v1/video/task ``` ### 요청 파라미터 #### 필수 | 파라미터 | 유형 | 설명 | | -------------- | ------ | ------------------------------------------------------------------ | | `model_name` | string | `"happyhorse-1.1-text-to-video"`여야 합니다 | | `prompt` | string | 비디오 생성 프롬프트 | | `duration` | number | 비디오 길이(초, 3-15) | | `resolution` | string | 출력 해상도: `"720p"` 또는 `"1080p"`(기본값 `"1080p"`) | | `aspect_ratio` | string | 비디오 종횡비(위 표 참조, 기본값 `"16:9"`) | #### 선택 사항 | 파라미터 | 유형 | 설명 | | -------- | ------ | ---------------------------------------------------------------------------------- | | `seed` | number | 재현 가능한 생성을 위한 랜덤 시드, `0`부터 `2147483647` 범위의 정수 | ### 요청 예시 ```javascript const response = await fetch('https://api.flaq.ai/api/v1/video/task', { method: 'POST', headers: { Authorization: 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ model_name: 'happyhorse-1.1-text-to-video', prompt: 'A cat playing with a ball of yarn on a sunny windowsill', duration: 5, resolution: '1080p', aspect_ratio: '16:9', seed: 42, }), }); const { data } = await response.json(); const taskId = data.task_id; ``` ## Happy Horse 1.1 Image to Video ### 요청 파라미터 #### 필수 | 파라미터 | 유형 | 설명 | | ------------ | ------ | ------------------------------------------------------------------ | | `model_name` | string | `"happyhorse-1.1-image-to-video"`여야 합니다 | | `prompt` | string | 비디오 생성 프롬프트 | | `duration` | number | 비디오 길이(초, 3-15) | | `resolution` | string | 출력 해상도: `"720p"` 또는 `"1080p"`(기본값 `"1080p"`) | | `image_url` | string | 첫 프레임 이미지 URL(첫 프레임만) | #### 선택 사항 | 파라미터 | 유형 | 설명 | | -------- | ------ | ---------------------------------------------------------------------------------- | | `seed` | number | 재현 가능한 생성을 위한 랜덤 시드, `0`부터 `2147483647` 범위의 정수 | > **참고:** image-to-video는 `aspect_ratio`를 지원하지 않습니다. 출력 프레이밍은 업로드된 첫 프레임 이미지를 따릅니다. ### 요청 예시 ```javascript const response = await fetch('https://api.flaq.ai/api/v1/video/task', { method: 'POST', headers: { Authorization: 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ model_name: 'happyhorse-1.1-image-to-video', image_url: 'https://example.com/first-frame.jpg', prompt: 'Gentle motion; cinematic lighting', duration: 5, resolution: '1080p', seed: 42, }), }); const { data } = await response.json(); const taskId = data.task_id; ``` ## Happy Horse 1.1 Reference to Video ### 요청 파라미터 #### 필수 | 파라미터 | 유형 | 설명 | | -------------- | -------- | ------------------------------------------------------------------ | | `model_name` | string | `"happyhorse-1.1-reference-to-video"`여야 합니다 | | `prompt` | string | 비디오 생성 프롬프트. 플레이스홀더가 없는 일반 프롬프트를 작성하거나, 선택적으로 @ (AT) 참조 기능을 사용하여 `<<>>`으로 `images` 배열의 항목을 명시적으로 참조할 수 있습니다 | | `duration` | number | 비디오 길이(초, 3-15) | | `resolution` | string | 출력 해상도: `"720p"` 또는 `"1080p"`(기본값 `"1080p"`) | | `aspect_ratio` | string | 비디오 종횡비(위 표 참조, 기본값 `"16:9"`) | | `images` | string[] | 참조 이미지 URL(이미지 1-9장) | #### @ (AT) 참조 플레이스홀더 @ (AT) 참조 기능은 번호가 지정된 `<<>>` 플레이스홀더를 통해 참조 이미지를 프롬프트에 연결합니다. 번호는 `1`부터 시작하며 `images` 배열의 순서를 따릅니다. | 플레이스홀더 | 참조 값 | |-------------|------------------| | `<<>>` | `images[0]` | | `<<>>` | `images[1]` | | `<<>>` | `images[2]` | #### 선택 사항 | 파라미터 | 유형 | 설명 | | -------- | ------ | ---------------------------------------------------------------------------------- | | `seed` | number | 재현 가능한 생성을 위한 랜덤 시드, `0`부터 `2147483647` 범위의 정수 | ### 참조 이미지 요구 사항 - 지원 형식: `JPEG`, `JPG`, `PNG`, `WEBP` - 최대 파일 크기: 이미지당 20 MB - 최소 짧은 변: 400 px - 개수: 최소 1장, 최대 9장 ### 요청 예시 ```javascript const response = await fetch('https://api.flaq.ai/api/v1/video/task', { method: 'POST', headers: { Authorization: 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ model_name: 'happyhorse-1.1-reference-to-video', prompt: 'Subject moves naturally while preserving reference style and appearance', duration: 5, resolution: '1080p', aspect_ratio: '16:9', images: [ 'https://example.com/ref-1.jpg', 'https://example.com/ref-2.jpg', ], seed: 42, }), }); const { data } = await response.json(); const taskId = data.task_id; ``` ### @ (AT) Reference-to-Video 요청 예시 ```javascript const response = await fetch('https://api.flaq.ai/api/v1/video/task', { method: 'POST', headers: { Authorization: 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ model_name: 'happyhorse-1.1-reference-to-video', prompt: 'Show the person from <<>> walking beside the bicycle from <<>> through the street in <<>>, preserving all reference details', duration: 5, resolution: '1080p', aspect_ratio: '16:9', images: [ 'https://example.com/person-reference.jpg', 'https://example.com/bicycle-reference.jpg', 'https://example.com/street-reference.jpg', ], seed: 42, }), }); const { data } = await response.json(); const taskId = data.task_id; ``` ## 응답 형식 ### 초기 응답 ```json { "code": 0, "message": "success", "data": { "task_id": "{task_id}", "response_url": "https://api.flaq.ai/api/v1/video/{task_id}", "task_status": "submitted" } } ``` ### 폴링 응답 상태를 확인하려면 `GET /api/v1/video/{taskId}`를 폴링하세요. ```json { "code": 0, "message": "success", "data": { "task_id": "{task_id}", "response_url": "https://api.flaq.ai/api/v1/video/{task_id}", "task_status": "succeed", "task_status_msg": null, "task_result": { "credit": 0.2, "videos": [ { "url": "https://example.com/generated-video.mp4" } ] } } } ``` ### 상태 값 - `submitted`: 작업이 접수되어 처리 대기 중입니다 - `processing`: 비디오 생성이 진행 중입니다 - `succeed`: 비디오 생성이 완료되었습니다 - `failed`: 비디오 생성에 실패했습니다 ## 처리 시간 일반적인 처리 시간은 길이와 대기열 부하에 따라 2-5분입니다. ## 모범 사례 1. **동작을 명확히 설명하세요**: 비디오의 역동성을 개선하려면 피사체 움직임, 카메라 움직임, 장면 진행을 추가하세요. 2. **먼저 짧은 반복을 사용하세요**: 더 긴 클립을 실행하기 전에 3-5초 생성으로 시작해 프롬프트 방향을 검증하세요. 3. **적절한 입력 이미지를 선택하세요**: image-to-video의 경우 선명하고 조명이 좋으며 피사체 초점이 뚜렷한 첫 프레임 이미지를 사용하세요. 4. **참조 이미지를 선별하세요**: reference-to-video의 경우 보존하려는 피사체 또는 스타일을 명확히 나타내는 일관된 고품질 참조 이미지를 제공하세요. 5. **변형에는 시드를 재사용하세요**: 프롬프트 개선을 테스트할 때 동일한 `seed`를 유지하면 출력을 더 일관되게 비교할 수 있습니다. 6. **전달 채널에 비율을 맞추세요**: 가로 비디오는 `16:9`, 쇼츠와 Reels는 `9:16`, 정사각형 배치는 `1:1`을 사용하세요.