비디오 생성대
오직 한 가지 일만 합니다: 이미 확정된 화면을 움직이게 만들고, 추적 가능한 기록을 남깁니다.
비디오 모델은 여기서 세 가지 역할을 담당합니다: 동작, 카메라 움직임, 그리고 내레이션 읽기. 피사체의 외형, 의상, 장면, 색상 팔레트, 조명, 구도, 화면 속 텍스트는 S1/S2 단계에서 이미 확정되었으며, 이 단계에서는 재창작이 허용되지 않습니다. 모델이 '창의력을 발휘'하기 시작하면 전체 영상의 일관성이 무너집니다.
내레이션은 더 이상 독립적인 음성 더빙을 사용하지 않습니다. 대사는 프롬프트에 작성되며, 모델이 직접 읽습니다. 이것이 이 워크플로우와 기존 방식의 가장 큰 차이점이며, 이 단계에서 가장 주의해야 할 부분입니다.
1. 입력 전제 조건
네 가지 요소가 필수이며, 하나라도 없으면 이전 단계로 돌아갑니다:
| 요건 | 위치 | 누락 시 결과 |
|---|---|---|
03-생성-목록.md | short-video-prompt 산출물, G2 통과 필수 | 몇 개의 클립을, 각각 몇 초 동안 생성해야 할지 알 수 없음 |
| 각 클립의 대사 원문 | 목록의 클립별 프롬프트 내 | 모델이 무엇을 읽어야 할지 몰라 임의로 생성함 |
| 에셋 이미지 / 첫 프레임 | 04-素材/01-에셋-이미지/, 04-素材/02-첫-프레임/ | 피사체가 클립마다 달라짐 |
KIE_API_KEY | 환경 변수 | 태스크 제출 불가 |
첫 프레임이 없다고 해서 할 수 없는 것은 아닙니다: 순수한 분위기, B-roll, 전환 장면은 텍스트-비디오로 직접 생성할 수 있습니다. 하지만 피사체가 등장하는 클립에는 반드시 이미지가 있어야 합니다. 이것은 절대적인 규칙입니다.
대사가 없는 클립은 내레이션을 생략할 수 있습니다. 예를 들어 B-roll, 순수 음악 섹션 등이 있습니다. 하지만 해당 클립에 대사가 있다면 반드시 프롬프트에 포함되어야 합니다. 이것이 현재 유일한 소리 출처입니다.
2. 세 가지 모드, 상호 배타적이며 혼용 불가
플랫폼 요청 하나는 한 가지 모드만 선택할 수 있습니다. 필드가 범위를 벗어나면 다른 모드가 되어 태스크가 바로 실패합니다.
| 모드 | 필수 필드 | 사용 시기 | 명확히 금지 |
|---|---|---|---|
text 텍스트-비디오 | prompt | B-roll, 분위기, 순수 배경 조명 효과, 전환 장면 | first_frame_url / last_frame_url 포함 금지 |
first 첫 프레임 이미지-비디오 | prompt + first_frame_url | 기본값: 시작 구도를 고정해야 할 때 사용 | last_frame_url 포함 금지 |
first-last 첫-마지막 프레임 | prompt + 첫 프레임 + 마지막 프레임 | 시작과 끝을 동시에 고정하고 인접 클립이 자연스럽게 연결되도록 해야 할 때 사용 | — |
목록의 '참조 이미지' 모드 매핑 방법
short-video-prompt의 목록 모드 열에는 '첫-마지막 프레임 / 참조 이미지 / 텍스트-비디오'가 있을 수 있습니다. 현재 모델에는 참조 이미지 모드가 없습니다. reference_image_urls와 같은 필드는 이 모델에서 사용할 수 없습니다. 따라서 다음과 같이 매핑해야 합니다:
| 목록에 명시된 모드 | 실제 제출 모드 | 설명 |
|---|---|---|
| 첫-마지막 프레임 | first-last | 직접 연결 |
| 참조 이미지 | first | 참조 이미지를 첫 프레임으로 사용하여 시작 구도 고정 |
| 텍스트-비디오 | text | 직접 연결, 단 피사체가 없는 장면에만 해당 |
이 단계는 타협이 아니라 능력의 한계입니다. 특정 클립에 '참조 이미지로 피사체 고정 + 자유로운 구도'가 정말 필요하다면, 첫 프레임을 사용하여 구도도 함께 고정하거나 S2 단계로 돌아가 분할을 수정해야 합니다.
3. 매개변수 규격
| 매개변수 | 값 | 기본값 | 설명 |
|---|---|---|---|
duration | 4–15 정수 초 | 5 | 15초 초과 시 분할, 4초 미만 시 후반 작업에서 모션 효과 또는 자르기 |
aspect_ratio | 9:16 / 16:9 / 1:1 / 3:4 / 4:3 / 21:9 / adaptive | 9:16 | adaptive는 텍스트-비디오에만 해당, 이미지-비디오는 고정 비율 필수 |
resolution | 480p / 720p | 480p | 기본값으로 생성 비용 제어; 정식 납품 해상도 필요 시 명시적으로 720p 전달 |
generate_audio | true / false | true | 끌 수 없음. 내레이션이 이 오디오 트랙에 있으므로 끄면 소리가 나지 않음 |
web_search | true / false | false | 텍스트-비디오에만 사용 가능, 일반적으로 사용하지 않음 |
세 가지 주의사항:
- 비율은 실제 출력과 일치해야 합니다. 모델이 반환한 결과의 비율이 명백히 일치하지 않거나 검은 테두리가 있는 경우 품질 실패로 판정하며, 레터박스 후 최종본으로 제출하는 것을 허용하지 않습니다.
- 오디오는 반드시 켜야 합니다. 내레이션과 배경음이 모두 이 트랙에 있습니다. 순수한 B-roll로 소리가 정말 필요 없는 경우에만
--no-audio를 사용합니다. duration은 정수로 입력합니다. 5.5를 전달하면 거부됩니다.
4. 7단계 프로세스
① 목록 읽기 → ② 모드 결정 → ③ 비디오 프롬프트 작성 → ④ 제출 → ⑤ 폴링 및 다운로드 → ⑥ 미디어 검사 → ⑦ 프레임 추출 품질 검사
① 목록 읽기, 실행 가능 여부 먼저 판단
클립별로 세 가지를 확인하고, 맞지 않으면 멈추고 질문하며 추측하지 마세요:
- 각 클립의
duration이 4–15 사이인지 (초과 시 먼저 분할) - 명시된 첫 프레임 파일이 실제로 존재하는지
- 참조된 에셋 번호가 모두 에셋 목록에 있는지
② 모드 결정
섹션 2의 표에 따라 클립별로 결정하며, 전체 프로젝트는 가능한 한 통일하는 것이 좋습니다. 혼용이 오류는 아니지만, 인접 클립의 연결이 더 어색해집니다.
③ 비디오 프롬프트 작성
references/video-prompt.md의 7단계 구조에 따라 작성합니다. 두 가지 핵심 원칙:
- '변화'만 설명하고, '무엇인지'를 다시 설명하지 마세요. 첫 프레임이 이미 모델에게 제품의 모습을 보여주었는데, 프롬프트에서 다시 설명하면 모델이 텍스트를 기반으로 다시 그리게 되어 일관성이 즉시 손실됩니다.
- 대사는 원고 그대로, 한 글자도 바꾸지 마세요. 내레이션이 이제 모델에 의해 직접 읽히므로, 대사 원문이 반드시 프롬프트에 포함되어야 합니다. 한 글자만 바꿔도 자막과 소리가 맞지 않게 됩니다.
④ 제출
python scripts/kie_seedance.py create \
--prompt "…" --mode first \
--first 04-素材/02-첫-프레임/S01_f01_v1.png \
--duration 6 --out 04-素材/03-클립/S01_v1.mp4 --wait
제출 성공 후 즉시 taskId와 지문을 台账에 기록한 후 다른 작업을 진행합니다. 먼저 기록하고 나중에 하지 않으면 중간에 끊겨서 찾을 수 없습니다.
④-2 전체 영상 배치 실행 (기본 5개 동시 실행)
클립을 하나씩 직렬로 실행하면 6개 클립에 30분 이상이 소요되며, 대부분의 시간을 대기하는 데 씁니다. 배치로 동시에 실행하면 총 시간은 가장 오래 걸리는 클립 하나와 비슷합니다.
# 먼저 미리보기로 조립된 요청 본문 확인
python scripts/kie_seedance.py batch --tasks tasks.json --out-dir 04-素材/03-클립 --dry-run
# 확인 후 실제 실행, 기본 5개 동시
python scripts/kie_seedance.py batch --tasks tasks.json --out-dir 04-素材/03-클립
# 속도 제한 시 감소
python scripts/kie_seedance.py batch --tasks tasks.json --out-dir 04-素材/03-클립 --concurrency 2
태스크 테이블 형식은 assets/batch-tasks-example.json을 참조하며, 클립당 하나의 항목입니다. mode / first / last / duration / prompt의 의미는 단일 명령과 동일합니다.
동시 실행이 항상 더 빠른 것은 아닙니다. 실제로 한 가지 함정이 있습니다: 台账이 엉망이 될 수 있습니다.
5개의 클립이 동시에 완료되면, 각 클립이 끝날 때마다 00-生成台账.md를 수정하려고 하면 다섯 번의 쓰기가 서로 덮어쓰기 되어 마지막 클립의 기록만 남게 됩니다. 올바른 방법은:
① 배치 실행 완료 후, 집계된 items 수집 (목록 순서대로 정렬됨)
② 台账에 한 번에 기록: 다섯 클립을 한 번에 기록하고, 하나씩 기록하지 않음
③ 기록 후 즉시 확인: 목록에 있는 클립 수와 台账의 행 수가 일치해야 함
실행하면서 기록하는 것을 선호한다면 동시성을 1로 낮추세요. 직렬 실행 + 실행 중 기록이 유일하게 엉망이 되지 않는 방법입니다. 이 트레이드오프는 스스로 결정해야 하지만, 동시 실행과 산발적 기록을 동시에 할 수는 없습니다.
속도 제한의 징후는 code != 200 또는 HTTP 429이며, '화면 품질 저하'가 아닙니다. 이러한 오류가 보이면 먼저 동시성을 낮추고 프롬프트를 수정하지 마세요.
실패 시 중단되지 않음: 하나의 클립이 실패해도 나머지는 계속 실행되며, 마지막에 집계된 failed 목록을 확인합니다. '오류 시 중단'을 원하면 --stop-on-error를 추가하세요. 그러면 새 태스크 제출을 중단하고, 이미 실행 중인 태스크에는 영향을 미치지 않습니다.
⑤ 폴링 및 다운로드
--wait는 다운로드가 완료될 때까지 기다립니다. 분리하여 수행할 수도 있습니다: create로 taskId 획득 → wait --task-id.
폴링 간격은 6초부터 시작하여 최대 30초까지 점진적으로 늘어나고, 최대 시간은 15분입니다. 시간 초과가 실패를 의미하는 것은 아니므로, 먼저 상태를 확인한 후 결정하세요.
⑥ 미디어 검사 (스크립트 판단)
# 대사가 있는 클립: 오디오 트랙이 반드시 존재해야 함
python scripts/inspect_clip.py --file 04-素材/03-클립/S01_v1.mp4 \
--ratio 9:16 --duration 6 --expect-audio
# 대사가 없는 B-roll: 오디오 트랙이 없어야 함
python scripts/inspect_clip.py --file S02_v1.mp4 --no-expect-audio
다섯 가지 객관적 사실을 확인합니다: 파일 존재 여부, 크기 정상 여부, 길이 일치 여부, 비율 일치 여부, 오디오 트랙 존재 여부. 통과는 '재생 가능한 파일을 다운로드했다'는 의미일 뿐, 화면을 사용할 수 있거나 대사가 올바르게 읽혔다는 것을 의미하지 않습니다.
오디오 트랙 항목은 이전보다 더 중요해졌습니다: 내레이션이 이 오디오 트랙에 있습니다. 오디오 트랙 없음 = 해당 클립에 소리가 없음 = 폐기물; 오디오 트랙이 있지만 대사를 잘못 읽은 경우 스크립트로는 찾을 수 없으며, 직접 들어야 합니다.
⑦ 프레임 추출 품질 검사 + 오디오 확인 (사람 판단)
화면: 최소 세 지점(시작, 중간, 끝)에서 프레임을 추출하고 references/clip-review.md의 7가지 항목을 확인합니다.
소리: 이제 내레이션을 모델이 읽으므로, 대사가 있는 모든 클립은 반드시 한 번 들어야 합니다. 원고와 비교하여 세 가지를 확인합니다:
| 확인 사항 | 판단 기준 |
|---|---|
| 문장 누락 여부 | 원고에 몇 문장인지, 그만큼 들리는지 확인 |
| 단어 오류 여부 | 키워드, 브랜드명, 숫자가 정확한지 확인 |
| 불필요한 소리 여부 | 나타나서는 안 되는 배경 음악, 다른 사람 목소리, 잡음 등 |
읽은 내용이 원고와 일치하지 않으면 타협하지 마세요. 두 가지 처리 방법: 해당 클립을 다시 생성하거나, 자막을 실제 읽은 내용에 맞게 수정합니다. 절대 할 수 없는 것은 원고 그대로 자막을 넣는 것입니다. 시청자가 듣는 것과 보는 것이 일치하지 않으면, 잘못 읽은 것보다 더 나쁩니다.
이 항목은 반드시 들어야 합니다. 모호한 키워드는 최소 세 번 이상 반복 전사하여 비교를 돕고, 문장별로 최종 사람 검토를 거친 후 결론을 04-素材/00-대사-확정.json에 기록합니다. references/clip-review.md 참조.
5. 세 가지 상태, 혼동하지 마세요
| 상태 | 판단 주체 | 의미 |
|---|---|---|
| 미디어 통과 | 스크립트 | 파일 완전, 매개변수 일치, 오디오 트랙 있음 |
| 화면 통과 | 사람 확인 | 피사체 변형 없음, 기형 없음, 다음 클립과 연결 가능 |
| 대사 통과 | 사람 청취 | 대사 전부 읽음, 키워드 오류 없음 |
세 가지를 모두 통과해야 상태를 '품질 통과'로 기록할 수 있습니다.
'다운로드 완료'를 '사용 가능'으로 혼동하는 것은 이 체인에서 가장 흔한 실수입니다. 클립을 편집 타임라인에 올렸는데 4번째 클립의 피사체가 바뀌어 앞의 작업이 모두 무용지물이 되는 경우가 발생합니다. 이제 한 단계가 더 추가되었습니다: 화면은 모두 정확하지만 대사에서 한 글자를 잘못 읽으면 전체 클립이 폐기물이 됩니다. 자막을 맞출 수 없기 때문입니다.
대사 검증 단계는 가장 쉽게 건너뛰어집니다. 눈으로 훑어보는 것이 아니라 조용히 헤드폰을 끼고 들어야 하기 때문입니다.
6. 台账: 04-素材/00-生成台账.md에 기록
클립당 한 줄, 여섯 가지 항목을 기록합니다: 요청 지문, 모드, taskId, 상태, 출력 파일, 실패 사유.
台账의 역할은 기록 보관이 아니라 중복 제출 방지입니다. 같은 영상을 하루 간격으로 다시 작업할 때 台账을 읽으면 어떤 클립이 완료되었는지, 어떤 클립이 제출되었지만 다운로드되지 않았는지, 어떤 클립이 실패했는지 알 수 있습니다.
규칙은 references/task-ledger.md를 참조하며, 네 가지 요약:
- 상태가 '품질 통과'이고 파일이 존재하면 → 건너뜀
- taskId가 있고 상태가 '대기 중 / 생성 중'이면 → 조회만 하고 새로 만들지 않음
- 상태가 '생성 성공, 다운로드 대기'이면 → 다운로드만 수행; URL이 만료되었으면 동일한 taskId로 새 URL 조회
- 상태가 '실패'이면 → 자동 재시도하지 않음, 사용자가 명시적으로 재시도를 요청할 때까지 대기
7. 실패 처리 방법
먼저 어느 계층에서 문제가 발생했는지 파악한 후, 무엇을 수정할지 결정하세요. 프롬프트부터 수정하지 마세요.
| 현상 | 근본 원인 | 수정할 곳 |
|---|---|---|
| 피사체 변형, 제품 외형 변화 | 첫 프레임이 없거나 첫 프레임 자체가 잘못됨 | 첫 프레임 추가 / 교체 |
| 화면 떨림, 깜빡임 | 동작을 너무 많이 작성함 | 하나의 동작만 남기고 삭제 |
| 텍스트 오류, 손가락 과다 생성 | 모델에게 텍스트 쓰기/복잡한 손 동작 요구 | 텍스트는 후반 작업에 위임, 손 동작 단순화 |
| 비율 불일치, 검은 테두리 | 매개변수와 반환 결과 불일치 | 실패 판정, 재생성, 검은 테두리 자르지 않음 |
| 클립 간 연결 부자연스러움 | 마지막 프레임과 다음 클립의 첫 프레임 불일치 | 첫-마지막 프레임 모드 사용 또는 연결 프레임 추가 |
| 대사 누락, 반만 읽음 | 해당 클립의 대사 길이가 영상 길이를 초과 | 대사 삭제 또는 해당 클립을 두 개로 분할 |
| 단어 오류, 다른 단어로 읽음 | 생소한 한자, 다의어, 브랜드명이 긴 문장에 포함됨 | 일반적인 표현으로 변경; 브랜드명은 별도 문장으로 분리 |
| 대사가 배경 음악에 묻힘 | 프롬프트에 '배경 음악 없음' 또는 '음성이 묻히지 않도록' 미작성 | 소리 관련 제약 조건 추가 후 재생성 |
| 소리가 완전히 없음 | --no-audio를 잘못 사용했거나 오디오가 꺼져 있음 | 제출 매개변수 확인 후 재생성 |
| 제출 즉시 오류 / 429 | 동시성 높음으로 인한 속도 제한 | --concurrency 2로 재실행, 프롬프트 수정 금지 |
| 동일 클립 반복 실패 | 여러 변수가 동시에 변경됨 | 한 번에 하나의 변수만 변경 |
대사 관련 문제가 절반 이상을 차지합니다. 이러한 문제의 공통점은 화면은 괜찮아 보이지만, 들어야만 발견된다는 것입니다. 따라서 각 클립은 반드시 듣고 나서 통과 여부를 결정해야 합니다.
재수정 시 한 번에 하나의 변수만 변경하세요. 프롬프트, 길이, 첫 프레임을 동시에 변경하면 성공하더라도 어떤 변경이 효과를 보았는지 알 수 없어, 다음에 같은 문제가 다시 발생합니다.
자세한 진단은 references/clip-review.md를 참조하세요.
8. 경계
- 비주얼 재설계 금지: 피사체, 장면, 색상 팔레트, 조명은 S2에서 이미 고정되었으며, 여기서는 움직이게만 만듦
- 대사 텍스트 수정 금지: 원고 그대로 읽어야 함. 단어를 변경해야 한다면 S1/S2로 돌아가서 수정하고, 여기서 임시 조정하지 않음
- 자막 추가 금지: 텍스트는 모두 후반 작업에서 처리. 모델은 중국어를 '읽을' 수 있지만 '쓸' 수는 없음
- 오디오 수정 금지: 잘못 읽은 클립은 재생성하거나 자막을 수정해야 함. 여기서 오디오 믹싱이나 추가 녹음하지 않음
- 편집 금지: 클립 연결, 비트 맞춤, 색보정은 S4에서 처리
- '예쁜지' 판단 금지: '사용 가능한지'만 판단. 미적 감상은 검토 단계의 역할
- 한 번에 통과한다고 보장하지 않음: 생성은 확률적 이벤트이며, 2–4개의 후보가 일반적이며 실패가 아님
9. 참고 자료
| 파일 | 언제 읽는가 |
|---|---|
references/api-and-modes.md | 인터페이스, 매개변수, 세 가지 모드 필드, 오류 응답 조회 시 |
references/video-prompt.md | 비디오 프롬프트 작성 및 수정 시 |
references/task-ledger.md | 台账 생성, 이어서 작업, 재제출 여부 판단 시 |
references/clip-review.md | 프레임 추출 품질 검사, 실패 판정, 재수정 방향 결정 시 |
| references/assembly-ops.md | S4 연결, 자막 및 오디오 믹싱의 FFmpeg 구현 세부 사항 |
assets/gen-ledger-template.md | 台账 생성 시 |
| assets/dialogue-final-template.json | 확정 대사 기록, 전사 보조 및 최종 사람 검토 시 |
assets/batch-tasks-example.json | 배치 실행 목록 작성 시 |
스크립트:
| 스크립트 | 용도 |
|---|---|
scripts/kie_seedance.py | 제출 / 배치 / 조회 / 다운로드 대기 / 참조 프레임 업로드 |
scripts/inspect_clip.py | 미디어 검사 (ffprobe 필요) |