Communitygithub.com

talki-io/img-video-skill

Claude Code Agent Skill,让 Claude 通过 jiekou.ai 多模型中转站一键生成图片与视频素材,支持文生图、图生视频等创作流程,可接入 Midjourney、Veo 3、Sora 2、Seedance、Flux 等模型。安装到 ~/.claude/skills 即可使用

img-video-skill란 무엇인가요?

이 스킬은 Claude Code와 같은 AI 에이전트가 외부 모델 서비스를 호출하여 이미지와 비디오를 생성할 수 있도록 합니다. jiekou.ai라는 다중 모델 중계 플랫폼을 사용하여 Midjourney, Veo 3, Sora 2, Seedance, Flux 등 다양한 공급업체의 모델을 하나의 인터페이스로 통합합니다. 개발자는 프롬프트만 제공하면 생성된 미디어 파일이 자동으로 'assets/' 디렉토리에 저장되고 상대 경로가 출력되어 HTML, PPT, 마크다운 문서 등에 바로 사용할 수 있습니다. 이 스킬은 이미지 생성, 이미지 기반 비디오 생성을 지원하며, 자동 장애 조치 체인을 통해 서비스 중단 시 대체 공급업체로 전환합니다. 또한 상세한 설정, 사용 예시, 문제 해결 가이드를 포함하여 엔지니어링 작업 흐름에 매끄럽게 통합됩니다.

지원 대상✓Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add talki-io/img-video-skill

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

미리보기

스킬 README에서

img-video-skill preview

문서

Img-Video —素材 생성 브리지(다중 공급업체)

Claude는 직접 픽셀을 생성할 수 없지만 외부 모델 서비스를 호출할 수 있습니다. 이 Skill은 이 연결을 하나의 스크립트로 캡슐화합니다: 프롬프트 입력 → 이미지/비디오 획득 → assets/에 저장 → 상대 경로 출력, 이후 HTML, PPT, Markdown 또는 디자인 파일에 바로 사용할 수 있습니다.

모델 계층은 플러그 가능합니다: 기본적으로 接口AI(jiekou.ai) 중계를 사용하며, 특정 업체의 키가 없거나 연결이 안 될 때 자동으로 폴백 체인의 즉몽(Jimeng) / 컬링(Kling) / Gemini 등으로 전환됩니다. 전체 목록은 references/providers.md를 참조하세요.

사용 시기

최종 결과물에 이미지나 비디오가 있어야 하고 텍스트나 플레이스홀더로는 부적합할 때 항상 이 Skill을 사용하여 생성하세요. 일반적인 시나리오:

  • 웹페이지 / 랜딩 페이지 / 이메일 템플릿: 배너, 히어로 이미지, 보조 이미지, 아이콘 배경
  • PPT / 슬라이드: 표지, 섹션 페이지, 콘텐츠 보조 이미지
  • 그래픽 디자인: 포스터, 표지, 소셜 미디어 카드, 썸네일
  • UI 프로토타입: 스케치 이미지, 제품 스크린샷 플레이스홀더
  • 짧은 비디오: 동적 배경, 제품 전시, 단일 이미지 기반 애니메이션

한 마디 원칙: 빈 공간을 남기거나 "(여기에 이미지 삽입)"이라고 쓰지 말고 바로 생성하세요.

사전 준비: 설정

첫 사용 전에 Skill 루트 디렉토리에 config.json을 준비해야 합니다(파일이 없으면 스크립트가 오류를 표시합니다):

  1. 템플릿 복사: cp config.example.json config.json
  2. 최소 하나의 공급업체를 구성하세요 — API 키는 사용자에게 요청해야 하며 절대 임의로 만들지 마세요. 각 업체마다 입력:
    • type: 공급업체 유형(아래 표 참조)
    • base_url: API 주소(기본값이 있으면 생략 가능)
    • 자격 증명: 대부분은 api_key; 컬링(Kling)은 access_key + secret_key
    • image_model / video_model: 모델 이름(필요 없는 기능은 null로 설정)
  3. 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✅—구체적으로 작성(스타일+주제+색조+구성)할수록 결과가 좋습니다
--size1024x1024일부 중계는 비율에 따라 이미지를 조정하며 자동으로 1:1 등으로 변환됩니다
--n1생성할 이미지 수
--output-dirassets/images출력 디렉토리
--provider폴백 체인 따름특정 업체를 강제 지정하여 폴백 체인 건너뜀

이미지-비디오 생성

python <skill>/scripts/generate.py video \
  --image assets/images/xxxx.png \
  --prompt "카메라가 천천히 확대되며 배경의 빛 반점이 부드럽게 움직임" --output-dir assets/videos
매개변수필수기본값설명
--image✅—로컬 경로 또는 http(s) URL
--prompt비어 있음움직임/장면 설명, 입력 권장
--output-dirassets/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콰이쇼우 컬링(직접 연결)✅✅
geminiGoogle 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에 직접 사용 가능.

일반적인 워크플로우

  1. providers 하위 명령으로 사용 가능한 서비스와 시도 순서를 확인합니다.
  2. 최종 결과물에 필요한 이미지/비디오, 각각의 용도와 스타일을 계획합니다.
  3. 하나씩 image(또는 먼저 image 그 다음 video)를 생성하고, 특정 서비스가 필요하면 --provider를 추가합니다.
  4. 출력된 상대 경로를 수집하여 최종 결과물에 작성합니다.

예시: 사용자가 "커피 브랜드 랜딩 페이지를 만들어 줘" → 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 끝부분을 참조하세요.

관련 스킬