명확한 제품 이미지 하나, 클로드 코드, 그리고 AIHubMix API를 사용하여 Seedream에서 캐릭터 참조를 생성하고, 이를 가상 인물 자산으로 등록한 후 Seedance를 사용하여 AI 제품 광고를 만들 수 있습니다.
이 튜토리얼은 실제 알로에 미스트 캠페인을 기반으로 하며, 프로젝트 구조, 구성, 명령어 및 완전한 비디오 프롬프트를 포함합니다. 목표 출력은 20초, 720p, 9:16 세로 광고 로 AI 생성 인물과 설정을 포함합니다.
클로드 코드와 AIHubMix가 전체 워크플로우를 지원합니다. 클로드 코드는 프로젝트 개요를 읽고, 프롬프트를 수정하며, 실행을 조직합니다. AIHubMix는 이미지와 비디오 생성이 동일한 프로젝트 내에서 작동할 수 있도록 하나의 모델 진입점을 제공합니다.
모델 ID, 매개변수 및 오류 처리는 2026년 9월 16일자 프로젝트 스냅샷에서 가져옵니다. 재사용하기 전에 현재 API를 확인하세요. 명령어는 포함된 flow.py 를 사용하며 프로젝트 루트에서 실행해야 합니다.전체 스타터 다운로드
코드, 프롬프트, 구성 및 샘플 이미지를 다운로드하세요.
압축을 푼 후 seedance-starter 디렉토리로 들어가세요. 패키지에는 flow.py, 두 개의 스키마 스냅샷, 다섯 개의 프롬프트 파일, 제품 이미지 및 세 개의 참조 이미지가 포함되어 있습니다. Python 스크립트는 표준 라이브러리만 사용합니다.
- 비디오 단계부터 시작: 포함된 세 개의 참조를 사용하고, 키를 구성한 후 4단계부터 시작하세요.
- 자신의 제품으로 시작: 제품 이미지를 교체하고 프롬프트 세부정보를 수정한 후 포함된 참조 이미지를
assets/에서 이동하고 3단계부터 시작하세요.
.env.example 파일을 .env 로 복사하고 자신의 API 키를 추가하세요. 계정은 관련 모델에 대한 접근 권한과 필요한 비동기 작업 권한, 충분한 할당량이 필요합니다. API 생성에는 사용 요금이 발생합니다.
1. 제품 이미지 및 프로젝트 준비
예제 제품은 네이처 리퍼블릭 알로에 베라 미스트입니다. 워크플로우를 조정할 때 이미지를 업데이트하고, 제품 설명 및 사용 동작을 함께 사용하세요.
| 파일 | 목적 |
|---|---|
assets/product.png | 원본 제품 이미지 |
prompts/prompt-a.txt | 주요 캐릭터 초상화 프롬프트 |
prompts/prompt-b.txt | 제품을 들고 있는 캐릭터 프롬프트 |
prompts/prompt-c.txt | 제품 사용 프롬프트 |
prompts/prompt-video.txt | 비디오 타임라인, 카메라 및 오디오 요구 사항 |
prompts.json | 치수, 지속 시간, 참조 종속성 및 프롬프트 경로 |
flow.py | API 요청, 자산 등록, 폴링 및 다운로드 |
seedream.schema.json, seedance.schema.json | 캐시된 API 스키마 스냅샷 |
클로드 코드는 프로젝트 개요를 읽고 구성 및 프롬프트를 수정하는 데 도움을 줍니다. flow.py 는 AIHubMix를 통해 실제 요청을 보냅니다.
AIHubMix가 이 워크플로우에 적합한 이유
AI 제품 광고 워크플로우는 일반적으로 하나 이상의 모델이 필요합니다. 이미지 모델은 인물과 제품 참조를 생성하고, 비디오 모델은 움직임과 카메라 동작을 생성합니다. AIHubMix는 대부분의 주류 모델을 포괄하므로, 각 공급자에 대해 별도의 계정, 인증 및 요청 진입점을 유지하는 대신 하나의 API 서비스로 작업별로 모델을 선택할 수 있습니다.
AIHubMix는 또한 여러 공급자에 연결하고 자동으로 사용 가능한 저지연 경로를 선택합니다. 이는 이미지 생성, 자산 처리 및 비디오 생성을 순차적으로 완료해야 하는 워크플로우에서 단일 공급자의 불안정성이 미치는 영향을 줄일 수 있습니다. 모델 가용성, 라우팅 및 응답 시간은 여전히 현재 서비스 조건에 따라 달라집니다.
프로젝트 루트에 .env 파일을 생성하거나 환경에서 동일한 변수를 제공하세요:
AIHUBMIX_API_KEY=replace_with_your_api_key
프로젝트는 .env 파일을 .gitignore 로 제외합니다. 실제 키는 절대 공유하지 말고 변수 이름과 예제만 공유하세요.
전체 워크플로우는 하나의 명확한 제품 이미지로 시작됩니다.
2. 출력 목표 설정 및 이미지와 비디오 매개변수 분리
관련 부분의 prompts.json 는 다음과 같습니다. 실제 파일을 편집할 때 기존 stills 배열 및 기타 필드를 유지하세요.
{
"size": "1080x1920",
"aspect_ratio": "9:16",
"duration": 20,
"resolution": "720p",
"generate_audio": true,
"video_prompt_file": "prompts/prompt-video.txt"
}
size 는 이미지 생성에 속합니다. aspect_ratio, duration, resolution, generate_audio 는 비디오 생성에 속합니다. 스크립트는 전체 구성 객체를 두 엔드포인트에 보내는 대신 별도의 요청을 빌드합니다.
프로젝트는 다음 모델 ID를 사용합니다:
- Seedream:
doubao-seedream-5-0-pro-260628 - Seedance:
doubao-seedance-2-5-260628
번들된 스키마 스냅샷은 이미지 엔드포인트가 size 를 수용하는 반면, 비디오 엔드포인트는 aspect_ratio 를 수용함을 보여줍니다. 이를 혼합하면 거부됩니다. flow.py 는 요청을 보내기 전에 캐시된 스키마 속성을 확인하지만, 이는 완전한 매개변수 검증이 아닙니다.
3. 세 개의 캐릭터 참조를 순서대로 생성
각 이미지는 다른 역할을 하며, 이후 이미지는 이전 이미지에 의존합니다:
| 참조 | 내용 | 입력 |
|---|---|---|
| A: 캐릭터 초상화 | 얼굴, 머리, 의상, 방 및 조명 설정 | 이 예제에서는 텍스트 프롬프트만 사용 |
| B: 제품을 들고 있는 모습 | 같은 인물이 카메라를 향해 라벨이 보이도록 병을 들고 있음 | 제품 이미지 + A |
| C: 제품 사용 모습 | 같은 인물이 스프레이 펌프를 누르고 있음 | 제품 이미지 + B |
프롬프트는 캐릭터 세부정보를 반복하고 제품의 형태, 색상, 라벨 배치 및 자연스러운 사용을 설명합니다.
실행:
python3 flow.py stills
결과는 assets/frame-01.jpg, frame-02.jpg, frame-03.jpg로 저장됩니다. 캐릭터 일관성, 포장 충실도 및 사용 동작의 사실성을 검토하세요.
스크립트는 기존 파일을 건너뜁니다. 프롬프트를 변경하면 백업하고 해당 출력을 이동한 후 다시 실행하세요. A를 변경하면 B와 C를 다시 생성해야 할 수도 있습니다.
참조는 캐릭터 정체성, 제품 프레젠테이션 및 제품 사용을 설정합니다.
4. 이미지를 호스팅하고 가상 초상화 자산 등록
스타터에는 저자의 계정에서 자산 ID가 포함되어 있지 않습니다. 참조를 자신의 계정에 등록하세요.
이 프로젝트는 등록을 위해 공개 이미지 URL을 사용합니다. 소스 워크플로우는 커밋 SHA에 고정된 GitHub 원시 URL을 사용했지만, 인증 없이 이미지를 직접 반환하는 모든 호스팅이 작동할 수 있습니다.
GitHub /blob/ URL은 HTML 페이지를 반환하므로 이미지 URL로 사용할 수 없습니다.
업로드한 파일의 실제 위치로 이 자리 표시자 호스트를 교체하세요:
IMAGE_BASE='https://your-public-image-host.example/campaign'
python3 flow.py check "$IMAGE_BASE/frame-01.jpg" "$IMAGE_BASE/frame-02.jpg" "$IMAGE_BASE/frame-03.jpg"
python3 flow.py assets "$IMAGE_BASE/frame-01.jpg" "$IMAGE_BASE/frame-02.jpg" "$IMAGE_BASE/frame-03.jpg"
check 는 HTTP 200 및 이미지 Content-Type을 확인합니다. assets 는 virtual_portrait 자산 그룹을 생성하거나 재사용하고, 각 이미지를 등록하며, 활성 상태가 될 때까지 기다리고 자산 ID를 state.json 에 기록합니다.
이 단계는 프로젝트에서 실제로 발생한 실패에서 비롯되었습니다: 포토리얼리스틱 캐릭터 URL을 비디오 엔드포인트에 직접 전달하면 doubao_real_person_required 가 반환되었습니다. 이 캠페인의 인물은 AI 생성이므로 virtual_portrait 가 올바른 분류였습니다. 실제 인물 사진은 해당 검증 프로세스를 따라야 하며 가상으로 레이블을 붙여서는 안 됩니다.
하나의 비디오 요청에 사용된 모든 자산은 동일한 그룹에 속해야 합니다.
참조가 생성되었고 세 개의 자산이 모두 활성 상태였으며, 이 스크린샷이 캡처될 때 비디오 작업이 여전히 실행 중이었습니다.
5. 비디오 프롬프트를 카메라 제한이 있는 타임라인으로 작성
최종 프로젝트 프롬프트는 하나의 연속적인 20초 샷을 네 단계로 나눕니다:
| 시간 | 캐릭터 동작 | 제품 위치 |
|---|---|---|
| 0–5초 | 카메라를 바라보며 병을 소개함 | 얼굴 옆에, 라벨이 카메라를 향함 |
| 5–10초 | 병을 들어 펌프를 누름 | 프레임 내에 유지됨 |
| 10–15초 | 눈을 감고 안개가 가라앉는 것을 느낌 | 프레임 하단 3분의 1 |
| 15–20초 | 눈을 뜨고 다시 제품을 소개함 | 얼굴 옆에 다시 위치, 라벨이 카메라를 향함 |
이전 결과는 카메라가 너무 가까워져 제품을 놓쳤습니다. 따라서 최종 프롬프트는 이동을 중간 근접 샷으로 제한하고, 제품이 보이도록 유지하며, 처음과 마지막 3초 동안 라벨이 읽을 수 있도록 요청합니다.
다음은 전체 prompts/prompt-video.txt 입니다. 다른 제품의 경우 브랜드, 포장 설명 및 사용 동작을 업데이트하세요. 이러한 지침은 생성 목표이며 여전히 출력 검토가 필요합니다.
하나의 연속적인 20초 세로 뷰티 광고 촬영, 컷 없음, 햇빛이 비치는 미니멀한 화장대 구석에서.
0-5초: 같은 24세 동아시아 여성이 흰색 리브 탱크탑 위에 오버사이즈 세이지 그린 린넨 셔츠를 입고, 투명한 연두색 네이처 리퍼블릭 알로에 베라 92% 수딩 젤 미스트를 뺨 옆에 들고, 라벨이 카메라를 향해 완전히 읽을 수 있도록 합니다. 그녀는 따뜻하고 편안한 미소로 카메라를 바라보며 병을 살짝 돌려 아침 햇빛을 받습니다.
5-10초: 그녀는 병을 눈높이 바로 위로 들어 미세 안개 펌프를 누릅니다. 부드러운 알로에 안개가 그녀의 얼굴을 가로질러 뿌려지고, 미세한 물방울이 빛을 받아 반짝입니다.
10-15초: 그녀는 눈을 감고 턱을 살짝 들어 작은 만족스러운 미소를 지으며 안개가 가라앉는 것을 느낍니다. 병은 이 비트 동안 프레임 하단 3분의 1에 계속 보입니다.
15-20초: 그녀는 눈을 뜨고 병을 다시 뺨 옆으로 가져와 라벨이 카메라를 향하게 하고, 렌즈를 향해 마지막으로 차분한 표정을 지어 보입니다.
카메라: 가슴 위 프레임에서 중간 근접 프레임으로 천천히 부드럽게 밀어 넣습니다. 중간 근접 샷을 넘지 마세요. 제품은 전체 촬영 동안 프레임 안에 있어야 하며, 라벨은 처음 3초와 마지막 3초 동안 명확하게 읽을 수 있어야 합니다.
모습: 카메라 왼쪽에서 부드럽게 확산된 아침 햇빛, 실제 수분이 있는 포토리얼리스틱 피부 질감, 디지털 입자가 아닌 실제 촬영된 스프레이로 표현된 안개, 프리미엄 K-뷰티 광고. 제품 포장, 색상, 재료, 라벨 배치 및 라벨 텍스트는 참조 이미지와 정확히 동일해야 하며, 제품을 재설계하거나 재문자화하지 마세요. 텍스트 오버레이, 캡션, 워터마크는 없습니다.
오디오: 조용하고 밝은 방, 부드러운 짧은 펌프 스프레이 소리, 부드러운 숨소리. 음악이나 내레이션은 없습니다.
오디오 생성이 활성화되어 있지만, 프롬프트는 방의 음색, 하나의 스프레이 소리 및 부드러운 숨소리만 요청합니다—음악이나 내레이션은 없습니다.
6. 비디오 생성 및 저장
자산 등록 후 asset:// 참조를 제출합니다. 이 명령은 저장된 ID를 읽고 각 ID를 별도의 인수로 전달합니다:
python3 - <<'PYCODE'
import json
import subprocess
import sys
from pathlib import Path
state = json.loads(Path("state.json").read_text())
refs = ["asset://" + asset_id for asset_id in state["asset_ids"]]
subprocess.run([sys.executable, "flow.py", "video", *refs], check=True)
PYCODE
인수 목록을 사용하면 여러 ID가 하나의 잘못된 인수로 스크립트에 도달할 수 있는 소스 프로젝트의 zsh 문제를 피할 수 있습니다.
스크립트는 비디오 작업 ID를 저장하고, completed 상태에 도달할 때까지 폴링하며, 출력을 out/video.mp4 로 다운로드합니다. 다른 다운로드가 해당 경로를 덮어쓸 수 있으므로 비교하고 싶은 버전을 백업하세요.
기존 작업을 재개하거나 결과를 다시 다운로드하려면:
python3 flow.py status
생성 응답이 손실된 경우 최근 작업을 나열하고 관련 ID를 재개하세요:
python3 flow.py tasks
python3 flow.py status VIDEO_TASK_ID
기존 작업을 생성하기 전에 확인하면 우발적인 중복 생성을 방지할 수 있습니다.
7. 출력 검토 및 반복
소스 프로젝트는 video-v1-10s.mp4 와 최종 video.mp4 를 보관합니다. 첫 번째 버전은 10초에 불과했으며 제품 사용이 충분히 나타나지 않았으므로 워크플로우는 두 번째 프롬프트 반복을 거쳤습니다.
모든 결과를 다음 체크리스트와 비교하여 검토하세요:
- [ ] 지속 시간, 해상도 및 종횡비가 목표와 일치합니다.
- [ ] 캐릭터의 얼굴, 의상 및 설정이 일관성을 유지합니다.
- [ ] 제품이 보이고 라벨이 시작과 끝에서 읽을 수 있습니다.
- [ ] 핸들링 및 스프레이 동작이 제품의 실제 사용과 일치합니다.
- [ ] 병 모양, 포장 및 텍스트가 눈에 띄게 변경되지 않습니다.
- [ ] 카메라가 너무 가까이 가지 않으며 오디오가 요청과 일치합니다.
지속 시간이 잘못된 경우 구성 및 실제 요청을 모두 확인하세요. 제품이 프레임을 벗어나는 경우 카메라 제한을 강화하세요. 사용 동작이 너무 짧은 경우 시간과 동작을 더 명확하게 할당하세요. 단지 prompts/prompt-video.txt 만 편집하는 것은 참조 이미지를 다시 생성할 필요가 없으며, 시각적 참조가 변경되어야 할 때만 다시 생성하고 등록하세요.
자주 묻는 질문
모델 이름이 올바르게 보이는데 왜 404가 반환되나요?
축약된 Seedream 이름은 소스 프로젝트에서 model_not_found 를 반환했습니다. 마케팅 표시 이름이 API 식별자라고 가정하지 말고 현재 엔드포인트에서 수용되는 전체 API 모델 ID를 사용하세요.
브라우저에서 이미지를 열 수 있지만 여전히 등록에 실패하는 이유는 무엇인가요?
URL이 HTML, 공유 페이지 또는 로그인 페이지가 아닌 이미지를 직접 반환하는지 확인하세요. 등록 전에 python3 flow.py check URL... 를 사용하세요.
프롬프트를 변경했는데 왜 참조 이미지가 변경되지 않았나요?
stills 는 기존 파일을 건너뜁니다. 재생성이 필요한 이미지를 백업하고 이동한 후, 하류 참조도 재생성해야 하는지 확인하세요.
HTTP 200이 비디오가 완료되었음을 의미하나요?
아니요. 스크립트는 작업의 status 에 따라 분기하며, 작업이 completed 에 도달한 후에만 다운로드합니다.
첫 번째 버전 시작하기
하나의 제품 이미지를 준비하고, AIHubMix 접근을 구성하며, 이미지 및 비디오 모델을 선택하세요. 그런 다음 클로드 코드가 제품 설명 및 프롬프트를 조정하도록 하세요. 세 개의 참조를 생성하고, 검토 및 등록한 후 비디오를 생성하고 체크리스트를 사용하여 다음 반복을 결정하세요.
미래 프로젝트에서 다른 모델이 필요할 경우 동일한 파일 구조와 워크플로우를 유지하고, AIHubMix 모델 선택 및 모델별 매개변수를 업데이트하세요. 이것이 여러 AI 모델을 사용하는 콘텐츠 팀을 위한 통합 API 서비스의 실질적인 가치입니다: 모델은 작업에 따라 변경될 수 있지만 워크플로우는 재사용 가능합니다.
