Img-Video —素材 생성 브리지(다중 공급업체)
Claude는 직접 픽셀을 생성할 수 없지만 외부 모델 서비스를 호출할 수 있습니다. 이 Skill은 이 연결을 하나의 스크립트로 캡슐화합니다:
프롬프트 입력 → 이미지/비디오 획득 → assets/에 저장 → 상대 경로 출력, 이후 HTML, PPT, Markdown 또는 디자인 파일에 바로 사용할 수 있습니다.
모델 계층은 플러그 가능합니다: 기본적으로 接口AI(jiekou.ai) 중계를 사용하며, 특정 업체의 키가 없거나 연결이 안 될 때 자동으로 폴백 체인의
즉몽(Jimeng) / 컬링(Kling) / Gemini 등으로 전환됩니다. 전체 목록은 references/providers.md를 참조하세요.
사용 시기
최종 결과물에 이미지나 비디오가 있어야 하고 텍스트나 플레이스홀더로는 부적합할 때 항상 이 Skill을 사용하여 생성하세요. 일반적인 시나리오:
- 웹페이지 / 랜딩 페이지 / 이메일 템플릿: 배너, 히어로 이미지, 보조 이미지, 아이콘 배경
- PPT / 슬라이드: 표지, 섹션 페이지, 콘텐츠 보조 이미지
- 그래픽 디자인: 포스터, 표지, 소셜 미디어 카드, 썸네일
- UI 프로토타입: 스케치 이미지, 제품 스크린샷 플레이스홀더
- 짧은 비디오: 동적 배경, 제품 전시, 단일 이미지 기반 애니메이션
한 마디 원칙: 빈 공간을 남기거나 "(여기에 이미지 삽입)"이라고 쓰지 말고 바로 생성하세요.
사전 준비: 설정
첫 사용 전에 Skill 루트 디렉토리에 config.json을 준비해야 합니다(파일이 없으면 스크립트가 오류를 표시합니다):
- 템플릿 복사:
cp config.example.json config.json - 최소 하나의 공급업체를 구성하세요 — API 키는 사용자에게 요청해야 하며 절대 임의로 만들지 마세요. 각 업체마다 입력:
type: 공급업체 유형(아래 표 참조)base_url: API 주소(기본값이 있으면 생략 가능)- 자격 증명: 대부분은
api_key; 컬링(Kling)은access_key+secret_key image_model/video_model: 모델 이름(필요 없는 기능은null로 설정)
default_provider(기본)와fallback(폴백 체인, 배열)을 설정하세요.
API 키는 로컬 config.json에만 저장되며(.gitignore에 포함됨), 코드, SKILL.md 또는 버전 관리 시스템에 절대 넣지 마세요.
작업 시작 전에 항상 가용성을 확인하세요(키/기능 준비 확인, 시도 순서 확인):
python <skill>/scripts/generate.py providers
사용법
프로젝트 작업 디렉토리에서 실행하여 출력된 assets/ 상대 경로가 웹페이지/PPT에서 바로 참조될 수 있도록 합니다.
텍스트-이미지 생성
python <skill>/scripts/generate.py image \
--prompt "플랫 일러스트 스타일의 기술 회사 랜딩 페이지 히어로 이미지, 블루-퍼플 그라데이션, 깔끔하고 여백이 많은 디자인" \
--size 1024x1024 --n 1 --output-dir assets/images
| 매개변수 | 필수 | 기본값 | 설명 |
|---|---|---|---|
--prompt | ✅ | — | 구체적으로 작성(스타일+주제+색조+구성)할수록 결과가 좋습니다 |
--size | 1024x1024 | 일부 중계는 비율에 따라 이미지를 조정하며 자동으로 1:1 등으로 변환됩니다 | |
--n | 1 | 생성할 이미지 수 | |
--output-dir | assets/images | 출력 디렉토리 | |
--provider | 폴백 체인 따름 | 특정 업체를 강제 지정하여 폴백 체인 건너뜀 |
이미지-비디오 생성
python <skill>/scripts/generate.py video \
--image assets/images/xxxx.png \
--prompt "카메라가 천천히 확대되며 배경의 빛 반점이 부드럽게 움직임" --output-dir assets/videos
| 매개변수 | 필수 | 기본값 | 설명 |
|---|---|---|---|
--image | ✅ | — | 로컬 경로 또는 http(s) URL |
--prompt | 비어 있음 | 움직임/장면 설명, 입력 권장 | |
--output-dir | assets/videos | 출력 디렉토리 | |
--provider | 폴백 체인 따름 | 특정 업체를 강제 지정 |
이미지-비디오 생성은 대부분 비동기 작업이며, 스크립트가 자동으로 완료를 폴링합니다.
공급업체 지정 / 전환
--provider를 생략하면default_provider → fallback순서로 자동 시도(키가 없거나 지원되지 않으면 건너뜀).--provider <name>(예:kling/ark/gemini/relay)을 추가하면 특정 업체를 강제 지정하고 폴백 체인을 건너뜁니다. 예: 사용자가 "컬링으로 생성" →--provider kling.
지원되는 모델 서비스
type | 서비스 | 텍스트-이미지 | 이미지-비디오 |
|---|---|---|---|
jiekou | 接口AI 중계(Midjourney/Flux/Seedance/컬링/Sora/Veo 통합, 기본값) | ✅ | ✅ |
ark / jimeng | 바이트댄스 즉몽 Seedream/Seedance(직접 연결) | ✅ | ✅ |
kling | 콰이쇼우 컬링(직접 연결) | ✅ | ✅ |
gemini | Google Imagen/Veo(직접 연결) | ✅ | ✅ |
relay | 기타 OpenAI 호환 중계 | ✅ | ⚠️ 게이트웨이에 따라 다름 |
실전 추천 조합(jiekou): 텍스트-이미지 mj-txt2img(Midjourney, 한 번에 4장 생성), flux-2-pro;
이미지-비디오 veo-3.1-generate-img2video(Veo 3.1, 네이티브 오디오 지원), sora-2-img2video, seedance-v1-pro-i2v.
⚠️ 모델 변경 시 필독: 각 모델의 프롬프트 필드명, 지속 시간/해상도 열거형, 필수 항목이 모두 다릅니다(예: Midjourney는
text사용, Veo는duration_seconds+generate_audio사용). 모델명만 변경하고 이러한 필드를 수정하지 않으면 400 오류가 발생합니다. config에 이미 스위치가 준비되어 있습니다(prompt_field/send_aspect_ratio/duration/resolution/video_extra),references/providers.md의 "각 모델 필드 차이" 빠른 참조표를 참조하여 조정하세요.
출력
- 이미지는
assets/images/에, 비디오는assets/videos/에 저장됩니다. - 파일명:
{타임스탬프}_{프롬프트 앞 몇 글자}.{png|jpg|mp4|…}(파일 헤더로 실제 형식을 식별하고 자동으로 덮어쓰기 방지). - 종료 시 생성된 파일의 상대 경로 목록이 출력됩니다 —
<img src="assets/images/…">, PPT 플레이스홀더 또는 Markdown에 직접 사용 가능.
일반적인 워크플로우
providers하위 명령으로 사용 가능한 서비스와 시도 순서를 확인합니다.- 최종 결과물에 필요한 이미지/비디오, 각각의 용도와 스타일을 계획합니다.
- 하나씩
image(또는 먼저image그 다음video)를 생성하고, 특정 서비스가 필요하면--provider를 추가합니다. - 출력된 상대 경로를 수집하여 최종 결과물에 작성합니다.
예시: 사용자가 "커피 브랜드 랜딩 페이지를 만들어 줘"
→ image --prompt "따뜻한 색조의 핸드드립 커피 클로즈업, 아침 햇살, 얕은 심도"로 히어로 이미지 생성
→ 제품 보조 이미지 두 장 더 생성 → 이 assets/images/*.png 파일들을 사용하여 HTML 작성.
예외 및 폴백(스크립트에 내장됨)
- config.json 부족 / providers 섹션 부족: 오류를 표시하고 설정하도록 안내.
- 기본 공급업체에 키/해당 모델 미구성: 자동으로 건너뛰고 다음 업체 시도.
- 실행 실패(4xx/5xx/타임아웃): 5xx 및 네트워크 예외는 지수 백오프로 재시도; 그래도 실패하면 폴백 체인의 다음 업체로 다운그레이드; 모두 실패할 때만 오류를 표시하고 각 업체의 실패 이유를 요약.
- 비디오 타임아웃:
poll_timeout초과 시 명확한 타임아웃 오류 표시. - 입력 이미지 없음(이미지-비디오 생성 시): 바로 오류 표시,
--image확인 요청.
의존성 및 확장
- 의존성: Python 3 +
requests(pip install requests). 컬링 JWT 인증은 표준 라이브러리로 구현되어 추가 의존성 없음. - 새 공급업체 추가:
scripts/providers.py에서 새로운Provider하위 클래스를 추가하고generate_image/generate_video를 구현한 후REGISTRY에 등록하기만 하면 됩니다 — 폴백 체인, 저장, 파일명 등은 수정할 필요 없음. 자세한 내용은references/providers.md끝부분을 참조하세요.