사용 가이드
HiAPI API를 통한 Wan2.7 이미지-투-비디오 숏폼 워크플로 구현
개발자 가이드: 첫 프레임 선택, 샷과 리듬 프롬프트, 화면 비율, 길이 및 배치 생성
이 페이지에서
이미지-투-비디오가 숏폼 제작에 적합한 이유
숏폼은 물량으로 승부하는 사업입니다. 단일 클립이 최종 결과물인 경우는 드뭅니다. 진짜 결과물은 동일한 룩, 동일한 리듬, 동일한 게시 주기를 공유하는 클립의 연속입니다. 이 요구는 어떤 단일 출력 품질 지표보다도 도구 선택을 더 강하게 규정합니다.
이미지-투-비디오가 여기에 매우 잘 맞는 이유는 정지 프레임을 주요 제어 신호로 바꿔놓기 때문입니다. 장면 전체를 텍스트로 묘사하고 모델이 우연히 의도한 구도에 떨어지길 바라는 대신, 이미 검수를 통과한 프레임 하나를 모델에 넘깁니다. 피사체는 당신이 배치한 위치에 있고, 크롭은 당신이 설계한 구도이며, 빛은 당신이 조명한 대로 떨어집니다. 생성 단계는 그때부터 움직임에 집중합니다. 피사체가 어떻게 움직이는지, 카메라가 어떻게 움직이는지, 카메라 호흡이 얼마나 빠른지에 대한 것이지, 장면을 맨바닥에서 만들어내는 것이 아닙니다.
이 역할 분담은 팀에게 중요합니다. 정지 프레임은 구도에 능숙한 사람이 기존의 어떤 파이프라인을 쓰든 제작·검수·승인할 수 있습니다. 움직임은 더 작고 테스트하기 쉬운 문제입니다. 어떤 클립의 결과가 잘못됐을 때 보통 문제가 프레임에 있는지 프롬프트에 있는지 판단할 수 있으며, 이는 매주 수십 개의 클립을 만들 때 원하는 이분법적 문제 해결 방식입니다.
HiAPI에서의 엔드투엔드 파이프라인은 의도적으로 지루하게 유지됩니다.
- 각 샷마다 첫 프레임 정지 이미지를 제작하거나 선택합니다.
- 피사체 동작, 카메라 움직임, 리듬을 묘사하는 샷 프롬프트를 작성합니다.
- 정지 프레임과 프롬프트를 고정된 화면 비율 및 길이와 함께
wan2.7-video/image-to-video라우트로 전송합니다. - 반환된 클립을 검수 대기열에 수집합니다.
- 승인하거나, 프롬프트를 다시 작성하거나, 다시 프레이밍한 뒤 게시합니다.
이 가이드의 전체 내용은 위의 각 단계를 재현 가능하게 만드는 데 있습니다. 숏폼 파이프라인의 가치는 뛰어난 클립 하나가 아니라, 내일 새로운 프레임으로 동일한 절차를 돌려 비교 가능한 결과를 얻는 데 있기 때문입니다.
정지 프레임을 작업 단위로 삼기
정지 프레임을 버전 관리 대상 산출물로 취급하세요. 실무적으로는 프레임에 결정적인 방식으로 이름을 붙이고, 승인된 프레임을 그와 함께 사용한 프롬프트와 함께 보관한다는 뜻입니다. 나중에 같은 샷에 대해 다른 버전을 시도하고 싶다면 한 번에 변수 하나만 바꾸세요. 프롬프트 또는 프레임 중 하나만 바꾸고, 둘을 동시에 바꾸지는 마세요.
모델이 결정하는 것과 결정하지 않는 것
화면 비율과 길이는 프롬프트에서 자연스럽게 나오는 속성이 아니라 당신이 정하는 것입니다. 가능한 한 빨리 확정하세요. 하류의 모든 것—정지 프레임을 어떻게 프레이밍할지, 리듬을 어떻게 표현할지, 플랫폼에 맞게 클립을 어떻게 편집할지—은 이 두 값이 이미 고정되어 있다고 가정합니다.

첫 프레임 선택하기
첫 프레임이 일의 대부분을 담당합니다. 첫 프레임을 잘못 고르면 아무리 프롬프트를 다듬어도 클립을 완전히 구제할 수 없으며, 실제로는 정지 프레임에 있는 문제를 쫓으며 많은 반복을 허비하게 됩니다. 생성에 한 번이라도 비용을 쓰기 전에 짧고 명확한 체크리스트로 후보 프레임을 걸러내세요.
구도와 피사체 크롭
선택한 프레임은 단순히 그 비율로 잘라낸 것이 아니라, 전달할 화면 비율에 맞게 구도가 잡혀 있어야 합니다. 정지 프레임에서 피사체가 가장자리에 가깝다면 모델이 피사체를 화면 밖으로 밀어내지 않고 카메라를 움직일 공간이 거의 없다고 예상해야 합니다. 움직임이 일어날 공간을 남기세요. 예상되는 팬 방향의 리드 공간, 상승할 피사체 위의 공간, 시차를 만들 수 있는 전경 요소 등입니다.
원본 화면 비율이 아니라 전달 화면 비율에서 크롭을 확인하세요. 정사각형으로는 균형이 잘 맞는 프레임도 세로로 긴 프레임에 밀어 넣으면 피사체를 잃을 수 있습니다.
헤드룸과 프레이밍 일관성
한 배치의 클립들이 함께 편집되거나 연속으로 게시된다면 프레임 간 헤드룸을 일관되게 유지하세요. 각 클립이 개별적으로는 문제가 없어도 헤드룸이 일관되지 않으면 조잡한 편집으로 읽힙니다. 하나의 관례를 정하고—예를 들어 피사체 머리 꼭대기에서 화면 상단 가장자리까지의 고정 간격—그 그룹의 모든 정지 프레임에 적용하세요.
빛의 방향과 그림자 안정성
조명은 움직임이 얼마나 사실적으로 보이는지를 결정합니다. 강하고 방향성이 뚜렷한 빛과 선명한 그림자는 모델이 의지할 구조를 제공합니다. 평평하고 그림자 없는 빛은 종종 움직이는 것이 아니라 미끄러지는 것처럼 보이는 움직임을 만듭니다. 빛의 방향이 모호하지 않은 프레임을 우선 선택하고, 그림자가 두 방향으로 떨어질 수 있는 정지 프레임은 피하세요. 이러한 모호함은 종종 깜빡임으로 나타납니다.
움직임을 암시하는 정지감
좋은 첫 프레임은 다음에 무슨 일이 일어날지 암시합니다. 동작 중인 피사체, 화면 밖을 바라보는 시선, 열린 공간을 향해 기울어진 몸—이 모든 것이 모델에게 자연스러운 연속 방향을 제공합니다. 완벽하게 대칭이고 정면을 향한 정지된 인물 사진은 자연스럽게 애니메이션화하기 가장 어렵습니다. 내포된 방향이 없기 때문입니다.
프레임의 청결도
생성 전에 정지 프레임을 전체 해상도로 확인하여 결함이 없는지 점검하세요. 가장자리 번짐, 일관되지 않은 손, 반복되는 텍스처, 움직이기 시작하면 명백히 왜곡될 텍스트 등입니다. 정지 프레임의 작은 결함은 클립에서 명백한 결함이 됩니다. 프레임을 수정하거나 다시 생성하는 것이 영상을 다시 뽑는 것보다 거의 항상 저렴합니다.

샷과 리듬 프롬프트 작성하기
이미지-투-비디오에서 가장 흔한 프롬프트 실수는 프롬프트를 장면 묘사로 쓰는 것입니다. 장면은 이미 정해져 있습니다. 바로 그 프레임입니다. 모델에게 필요한 것은 샷 지시입니다. 무엇이 움직이는지, 어떻게 움직이는지, 얼마나 빠르게 움직이는지입니다.
프롬프트를 세 개의 절로 구성하기
안정적으로 사용 가능한 클립을 만들어내는 프롬프트는 보통 순서대로 세 가지를 다룹니다.
- 피사체 동작 — 피사체가 무엇을 하는지, 구체적인 물리적 묘사로.
- 카메라 움직임 — 카메라가 무엇을 하는지, 하나의 깔끔한 움직임으로.
- 리듬 — 동작이 클립 내에서 전개되는 속도.
예를 들어 방 안에 있는 사람을 묘사하는 대신, 피사체가 창문 쪽으로 고개를 돌리고, 카메라가 천천히 푸시인하며, 동작이 클립 전체 길이에 걸쳐 점진적으로 전개된다고 묘사하세요. 각 절은 모델이 실행할 수 있는 것에 대응합니다.
카메라 움직임을 하나로 유지하기
샷마다 움직임은 하나만 쓰세요. 푸시인, 팬, 핸드헬드 드리프트 중 하나를 고르세요. 푸시인과 동시에 서라운드하고 줌도 하라고 요구하는 프롬프트는 흐릿하고 불확실한 움직임을 만들어내는 경향이 있습니다. 한 샷에 두 가지 움직임이 필요하다면 그것은 두 개의 샷입니다.
모델 리듬이 아니라 플랫폼 리듬에 맞추기
숏폼 시청자는 빠르게 넘깁니다. 길이의 대부분을 정적인 장면 설정에 쓰는 클립은 무슨 일이 일어나기도 전에 시청자를 잃게 합니다. 리듬을 명시적으로 작성하세요. 처음 몇 순간에 약간의 움직임을 앞세우고, 그다음 카메라가 주요 동작으로 안정적으로 들어가게 하세요. 속도감을 전달하는 단어—점진적으로, 경쾌하게, 지속적으로, 점차 안정되게—가 형용사 목록보다 더 유용합니다.
감정이 아니라 움직임을 묘사하기
감정적인 단어는 값싸고 대부분 무시됩니다. 물리적 묘사는 그렇지 않습니다. 추상적인 특성이 아니라 신체, 사물, 카메라에 관한 관찰 가능한 진술을 우선 사용하세요. 특정한 감정적 룩을 원한다면 "시네마틱" 같은 단어가 아니라 동작과 리듬에서 얻으세요.
프롬프트를 코드처럼 버전 관리하기
각 프롬프트를 프레임 식별자, 화면 비율, 길이와 함께 코드 저장소나 데이터베이스에 보관하세요. 어떤 클립이 잘 나왔을 때, 어떤 조합이 그것을 만들었는지 알고 싶어지며, 나중에 그 조합을 비슷한 프레임 배치 전체에 다시 돌릴 수 있어야 합니다.
화면 비율과 길이 설정하기
화면 비율과 길이는 워크플로를 조용히 망칠 가능성이 가장 높은 두 매개변수입니다. 둘 다 프롬프트에 나타나지 않으면서 무엇이 좋은 결과인지를 바꾸기 때문입니다. 출력 형식별로 한 번씩 결정하고 나서 상수로 취급하세요.
화면 비율 선택하기
대상 플랫폼이 실제로 표시하는 비율을 선택하고 그에 맞게 정지 프레임의 구도를 잡으세요. 실질적인 결과는 이렇습니다. 세로와 가로 사이에서 재구도 없이 같은 프레임을 재사용해서는 안 됩니다. 세로에 맞는 크롭이 가로에 잘 맞는 경우는 드뭅니다. 둘 다 필요하다면 같은 촬영에서 나온 두 세트의 정지 프레임을 유지하고, 각 세트를 자기 비율에 맞게 구도화하세요.
선택한 후에는 그 비율을 모든 요청과 함께 기록하세요. 완료된 배치에서 비율이 섞여 있다는 것은 보통 누군가가 결정을 내린 것이 아니라 기본값을 바꿨다는 뜻입니다.
길이 선택하기
숏폼 클립은 짧습니다. 형식에 맞는 길이를 계획하세요. 하나의 명확한 동작을 완수하기에 충분히 길고, 유휴 시간이 없을 만큼 짧게요. HiAPI는 이미지-투-비디오를 출력 길이로 과금하므로 지나치게 긴 클립은 비용이 더 들고 검수 경험도 나빠집니다. 시청자는 할 말이 다한 클립의 끝부분을 거의 보지 않습니다.
프롬프트는 선택한 길이를 채우는 것처럼 작성하세요. 묘사된 동작이 클립보다 길면 동작 중간의 갑작스러운 컷이 생기고, 동작이 길이의 일부에서 끝나면 끝에 공백이 남습니다. 리듬 표현을 길이에 맞게 의도적으로 조정하세요.
확장 전에 둘 다 고정하기
이것이 이 가이드에서 가장 중요한 절차 규칙입니다. 프롬프트 튜닝은 고정된 화면 비율과 길이 안에서만 의미가 있습니다. 둘 다 움직임이 인식되는 방식을 바꾸기 때문입니다. 한 길이에서 프롬프트를 튜닝한 뒤 출력을 줄이면, 승인했던 모든 프롬프트가 검증되지 않은 추측이 됩니다. 매개변수 쌍을 고정하고, 그에 맞춰 튜닝하고, 의도된 재튜닝 이벤트로만 변경하세요.
실행마다 기록할 가치가 있는 매개변수
배치마다 작은 기록을 남기세요. 화면 비율, 길이, 모델 라우트, 프레임 그룹 식별자, 프롬프트 버전입니다. 이 네 필드 기록은 보통 몇 달 후에 로그를 뒤지지 않고도 어떤 클립이 왜 그렇게 나왔는지 재구성하기에 충분합니다.
HiAPI에서 배치 생성하기
프레임 그룹과 프롬프트 패턴이 승인되면 생성은 기계적인 작업입니다. 목표는 요청을 전개하고 결과를 결정적으로 수집하는 작은 스크립트로, 수동이 아니라 일정에 따라 실행할 수 있게 하는 것입니다.
자격 증명과 설정
API 자격 증명은 환경 변수에 보관하고 스크립트나 저장소에는 절대 두지 마세요. 엔드포인트와 모델 라우트는 설정에서 읽어서, 나중에 코드 경로를 수정하지 않고 같은 스크립트를 다른 라우트로 향하게 할 수 있게 하세요.
export HIAPI_API_KEY="your-key-here"
실행 가능한 요청
이 워크플로의 라우트는 wan2.7-video/image-to-video입니다. 최소 요청에는 첫 프레임, 샷 프롬프트, 화면 비율, 길이가 포함됩니다.
curl -X POST "https://api.hiapi.ai/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "wan2.7-video/image-to-video",
"image": "https://your-cdn.example/frames/shot-014.png",
"prompt": "Subject turns toward the window; slow push-in; gradual motion settling over the clip.",
"aspect_ratio": "9:16",
"duration": 5
}'
무엇이든 반복하기 전에 잘 작동하는 것으로 알려진 프레임 하나로 한 번 실행하세요. 성공한 요청 하나면 자격 증명, 라우트 이름, 요청 페이로드 구조를 확인할 수 있습니다.
프레임 세트 순회하기
배치 생성은 같은 요청을 다른 image와 그에 맞는 프롬프트로 반복 실행하는 것입니다. 입력을 레코드 목록으로 구성하고, 각 레코드가 프레임 URL, 그 프롬프트, 그리고 당신이 제어하는 출력 이름을 담게 하세요. 반복하고, 제출하고, 반환된 식별자를 입력 레코드에 기록하세요.
루프에 대한 두 가지 실용 규칙:
- 동시성을 제한하세요. 모든 요청을 한꺼번에 보내는 것은 속도 제한에 부딪히고 어떤 응답이 어떤 입력에 속하는지 파악할 수 없게 되는 가장 빠른 방법입니다. 재시도를 갖춘 적당한 작업 풀이 폭주보다 신뢰할 수 있습니다.
- 요청과 결과를 함께 기록하세요. 각 생성에 대해 프레임 URL, 프롬프트, 화면 비율, 길이, 반환된 클립 참조를 영구 저장하세요. 이것이 없으면 좋은 클립을 재현할 수도, 나쁜 클립을 설명할 수도 없습니다.
출력 수집하기
프레임 식별자와 프롬프트 버전을 키로 삼아 결정적인 폴더 구조에 클립을 다운로드한 뒤, 폴더를 검수로 넘기세요. 명명 체계를 안정적으로 유지하면 검수 단계는 대조 작업이 아니라 디렉터리 나열이 됩니다.
재실행 시 멱등성
각 프레임-프롬프트 쌍에 안정적인 해시를 부여하고, 의도적으로 다시 뽑는 것이 아니라면 이미 생성된 쌍은 건너뛰세요. 세 개의 공백을 메우기 위해 전체 배치를 다시 생성하는 것은 팀이 이미지-투-비디오 파이프라인에서 할당량을 낭비하는 가장 흔한 방식입니다.

출력 검수 및 반복
검수는 형식이 아니라 제작 단계입니다. 요점은 각 클립을 세 가지 결과 중 하나로 빠르게 분류하는 것입니다. 승인, 프롬프트 재작성, 재프레이밍. 그래야 배치 전체가 계속 진행됩니다.
간단한 검수 체크리스트
모든 반환 클립을 동일한 순서의 점검 과정에 통과시키세요.
- 첫 프레임 충실도 — 시작 순간이 승인한 정지 프레임과 일치합니까? 즉시 어긋난다면 보통 문제는 프롬프트가 아니라 프레임에 있습니다.
- 동작 타당성 — 피사체의 움직임이 신체와 사물이 실제로 움직이는 방식과 일치합니까? 미끄러짐, 팔다리 변형, 형태가 바뀌는 사물을 주의하세요.
- 카메라 규율 — 카메라가 요청한 단일 움직임을 수행합니까, 아니면 흔들립니까?
- 리듬 적합성 — 동작이 길이 안에서 완료됩니까, 불필요한 꼬리도 동작 중간 컷도 없이?
- 결함 스캔 — 가장자리, 손, 얼굴, 배경 텍스트, 세부 묘사가 미세한 영역을 확인하세요.
- 형식 점검 — 화면 비율이 올바르고, 피사체가 플랫폼 UI 오버레이의 안전 여백 안에 있습니까?
분류 결정
- 승인 — 클립이 여섯 가지 점검을 통과하거나, 전달 크기에서 보이지 않는 측면에서만 실패한 경우.
- 프롬프트 재작성 — 프레임은 좋지만 동작, 카메라 또는 리듬이 잘못된 경우. 프롬프트의 한 절만 수정하고 다시 생성하세요.
- 재프레이밍 — 동작 결함이 정지 프레임의 모호함으로 거슬러 올라갈 수 있는 경우. 빛의 방향이 불분명하거나, 크롭이 어색하거나, 피사체에 내포된 움직임이 없는 경우입니다.
반복마다 변수는 하나만 바꾸세요. 프레임과 프롬프트를 동시에 바꾸면 어떤 수정이 효과가 있었는지 알 수 없습니다.
저렴한 검수가 완벽한 클립보다 낫다
숏폼 대량 생산에서는 많은 클립에 대한 빠른 통과/불통과 검수가 단일 클립을 여러 번 다시 뽑으며 다듬는 것보다 낫습니다. 시청자가 실제로 클립을 보는 크기로 검수하고 전체 해상도로 하지 마세요. 그리고 곧 승인할 클립만 확대해서 보세요. 이렇게 하면 검수 단계가 당신의 불안에 비례하는 것이 아니라 배치 규모에 비례하게 됩니다.
발견을 피드백하기
어떤 프롬프트 패턴과 프레임 품질이 승인율과 연관되는지 계속 기록하세요. 몇 배치가 지나면 이것이 내부 스타일이 됩니다. 검수자가 오래 논쟁하지 않고 승인할 클립을 안정적으로 만들어내는 짧은 프롬프트 절과 프레이밍 규칙의 집합입니다.
피해야 할 함정
프로덕션에서 정체되는 이미지-투-비디오 프로젝트 대부분은 모델 문제가 아니라 절차 문제로 실패합니다. 다음은 반복적으로 나타나는 몇 가지입니다.
움직이는 목표에 맞춰 프롬프트 튜닝하기
튜닝 도중에 길이나 화면 비율을 바꾸면 그때까지 해온 모든 비교가 무효가 됩니다. 먼저 둘을 고정한 뒤 튜닝하세요. 이해관계자가 다른 형식을 요구한다면, 그것은 매개변수 미세 조정이 아니라 승인된 자체 프롬프트가 있는 새로운 튜닝 주기로 취급하세요.
정지 프레임을 사후 고려 사항으로 취급하기
프레임을 빠르게 생성하고 모든 에너지를 프롬프트에 쏟는 팀은 곧 한계에 부딪힙니다. 프레임이 제어 신호입니다. 정지 프레임에 실제 검수 시간을 할애하고, 약한 프레임은 생성 단계에 들어가기 전에 거부하세요.
샷 지시 대신 장면 묘사 쓰기
감정과 배경 이야기로 가득하지만 물리적 동작이 없는 프롬프트는 예쁘지만 아무 일도 일어나지 않는 클립을 만듭니다. 모든 프롬프트는 무엇이 얼마나 빠르게 움직이는지 명시해야 합니다.
무제한 동시성과 누락된 로그
요청을 폭주시키고 응답 식별자를 버리면 배치를 되살릴 수 없게 됩니다. 입력과 출력을 함께 기록하고, 작업 스레드 수를 제한하며, 재실행을 멱등적으로 만드세요.
승인 기록 없음
승인된 클립을 만들어낸 정확한 프레임, 프롬프트, 비율, 길이를 지적할 수 없다면 그것을 반복할 수 없습니다. 이 대가는 처음으로 시리즈를 확장해야 하는데 최고의 클립을 재현할 수 없다는 것을 깨달을 때 드러납니다.
작은 공백을 메우기 위한 과잉 생성
세 개의 클립이 실패했다고 배치 전체를 다시 돌리는 것은 시간과 예산을 모두 낭비합니다. 각 항목의 상태를 추적하고 누락된 부분만 다시 생성하세요.
플랫폼 안전 영역 무시하기
기술적으로는 올바르지만 피사체가 플랫폼 인터페이스 오버레이 아래에 놓이는 클립은 손상된 것으로 읽힙니다. 다른 자산을 전달할 때와 동일한 안전 여백을 사용해 정지 프레임의 구도를 잡으세요.
이 중 어느 것도 낯설지 않습니다. 이는 생산 파이프라인의 일상적인 규율을, 그 규율에 보답하는 모델에 적용한 것일 뿐입니다.
승인된 프레임 하나와 프롬프트 하나로 시작해 wan2.7-video/image-to-video 라우트에서 엔드투엔드로 실행한 뒤, 루프를 전체 배치로 확장하세요.