HiAPI 제품 대변인 비디오은(는) 무엇을 하나요?
로컬 CLI로 3~15초 길이의 단일 장면 제품 영상을 생성합니다. 유료 요청 전에 항상 --dry-run으로 예상 비용을 확인하세요. 사용자가 명시적으로 생성을 승인하고 명령어에 --spend가 포함된 경우에만 유료 작업을 생성합니다.
시나리오 라우팅
정확히 하나의 시나리오를 선택하세요:
| 시나리오 | 모델 | 필수 입력 | P0 기본값 |
|---|---|---|---|
synthetic-spokesperson | kling-3.0-omni/text-to-video | 프롬프트 및 선택적 대사 | 3초, 720p, 9:16, 오디오 |
talking-head | kling-3.0-omni/image-to-video | 승인된 인물 사진 1장, 프롬프트, 대사, 동의 | 3초, 720p, 오디오 |
product-intro | seedance-2.0-fast | 프롬프트 및 제품 이미지 1~9장 | 4초, 480p, 9:16, 오디오 |
brand-promo | seedance-2.0-fast | 프롬프트 및 브랜드/제품 이미지 1~9장 | 4초, 480p, 9:16, 오디오 |
요청을 구성하기 전에 대상 길이를 확인하세요. 사용자가 지정하지 않은 경우, 영상 길이를 몇 초로 할지 묻고 지원되는 범위(Kling 315초, Seedance 415초)를 알려주세요. 표에서 P0 기본값을 제안하되, 사용자가 길이를 선택하거나 기본값을 명시적으로 수락할 때까지 --dry-run으로 진행하지 마세요.
사용자가 승인을 확인하고 명령어에 --consent-confirmed가 포함된 경우에만 talking-head 생성을 허용합니다. 제품 주장, 보증, 가격, 인증 또는 브랜드 사실을 임의로 만들어내지 마세요.
소비 및 비밀 보호
먼저 무비용 점검을 실행하세요:
node scripts/hiapi-product-spokesperson-video.mjs --check --env-file "D:\path\to\.env.local"
그런 다음 의도한 요청을 --dry-run으로 실행하세요. --dry-run을 --spend로 대체하기 전에 공개 가격 견적이 사용자의 한도 내에 있는지 확인하세요. 기본 클라이언트 측 견적 한도는 $0.50이며, 명시적으로 사용자가 승인한 예산 내에서만 재정의할 수 있습니다. 호출당 하나 이상의 유료 작업을 생성하지 마세요.
이것은 서버에서 강제하는 최종 요금 상한이 아닌 견적 보호 장치로 취급하세요. HiAPI는 작업 선불 충전 중에 계정별 그룹 비율을 적용할 수 있습니다. 작업 API가 서버 측 최대 비용 필드를 지원할 때까지, 유료 생성 전에 이 제한 사항을 공개하고 사용자의 총 예산 아래에 충분한 여유를 유지하세요.
HIAPI_API_KEY를 프로세스 환경 또는 --env-file에서 읽어옵니다. 키를 미리보기, 아티팩트, 매니페스트, 오류 또는 로그에 절대 출력, 반환, 저장 또는 포함하지 마세요. P0에서는 임시 저장소를 사용하세요.
설치 후 .env.example을 무시된 .env에 복사하거나, --env-file을 기존의 무시된 환경 파일로 지정하세요. 채워진 파일을 절대 커밋하지 마세요. 포함된 이미지 데이터와 원격 이미지 URL을 미리보기 및 저장된 요청 아티팩트에서 모두 삭제하세요.
로컬에서 실행
비용을 지출하지 않고 승인된 토킹헤드 요청을 예상하려면:
node scripts/hiapi-product-spokesperson-video.mjs `
--scenario talking-head `
--image-file "D:\media\authorized-person.jpg" `
--prompt "고정 카메라, 자연스러운 아이컨택, 절제된 움직임" `
--dialogue "새로운 제품, 지금 만나보세요." `
--consent-confirmed `
--env-file "D:\path\to\.env.local" `
--max-cost-usd 0.50 `
--dry-run
synthetic-spokesperson의 경우 이미지 및 동의 옵션을 생략하세요. 제품 및 브랜드 시나리오의 경우 --reference-image-file 또는 --reference-image-url을 반복하세요. 로컬 JPEG, PNG, WebP 파일은 데이터 URI로 변환되며 각각 20MiB를 초과할 수 없습니다.
비용 재지출 없이 재개
CLI는 제출 전에 멱등성 키를 출력하고 작업 생성 직후 작업 ID를 출력합니다. 작업 ID가 반환되기 전에 제출이 중단된 경우 동일한 --idempotency-key로 재시도하세요. 생성 후 폴링이 중단된 경우 --task-id ID, --env-file 및 원하는 --output-dir만 실행하세요. 이렇게 하면 폴링이 재개되고 기존 결과를 다시 빌드하거나 재제출하지 않고 다운로드합니다.
출력 패키지 보존
--output-dir이 제공되지 않는 한 각 성공적인 실행을 outputs/ 아래에 기록하세요. 다음을 보존하세요:
final.mp4;script.md및captions.srt;- 포함된 미디어와 원격 이미지 URL이 삭제된
prompt.json; - 시나리오, 모델, 작업 ID, 상태, 견적, 요청 해시, 저장소, 타임스탬프 및 만료가 포함된
manifest.json; - 음성, 립싱크, 일관성, 연속성 및 주장 정확성에 대한 인간 검토를 위해 표시된
qc.json.
최종 성공적인 작업과 사용 가능한 로컬 비디오 없이 성공을 주장하지 마세요.
실패 처리
- HTTP
400,401,402또는403은 재시도하지 마세요. - HTTP
409,429또는503은 원본 멱등성 키로 최대 세 번까지 제출을 재시도하세요. --task-id로 폴링 중단을 재개하고, 자동으로 대체 작업을 제출하지 마세요.- 품질 실패 후 다른 유료 실행에 대한 명시적 승인 없이 재생성하지 마세요.
- 작업 ID, 최종 상태, 견적, 로컬 출력 경로 및 보류 중인 인간 QC 확인을 보고하세요.