Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
mediagen은 Google Gemini, OpenAI 등 여러 AI 모델을 통합하여 코딩 에이전트가 이미지 및 비디오 생성을 할 수 있도록 돕는 스킬입니다. 사용자가 원하는 바를 대략적으로만 설명해도 에이전트가 최적의 프롬프트와 설정을 자동으로 결정합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Codex tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기Google Gemini, OpenAI, 그리고 Kie AI를 통해 에이전트가 이미지 및 비디오 생성을 할 수 있도록 지원합니다. 하나의 스킬로, 한 번의 설치만으로, API 키 설정 없이 사용할 수 있습니다.
원하는 바를 대략적으로 말하면 나머지는 에이전트가 결정하게 합니다:
You: 랜딩 페이지용 히어로 이미지를 만들어줘. 와이드하고, 분위기가 어둡고 산업적인 느낌이었으면 좋겠어.
Agent: npx -y mediagen image "해질 녘의 사용되지 않은 하역장, 젖은 콘크리트..."
...
에이전트는 프롬프트를 전체적으로 작성했고, OpenAI가 요구하는 21:9 비율을 알고 있었으며, --json으로부터 경로를 읽어왔습니다.
아니면 정확하게 지정할 수도 있고, 그러면 결정하는 것을 멈춥니다:
You: gemini-3-pro-image로 같은 걸 해줘. 21:9 비율에, 4K 고화질로, AI 생성물임을 표시하고,
hero.png로 저장해줘.
...
이것은 피사체가 어디에 위치했는지 확인한 후 두 번째 패스에서 레이블을 표시했고, 하역장 위가 아닌 평평한 지붕 라인 위에 배치했습니다.
CLI가 처리할 수 있는 모든 항목(제공자(provider), 모델(model), 종횡비(aspect ratio), 크기(size), 출력 이름 및 디렉토리(output name and directory), 품질 프리셋(quality preset), 비디오 지속 시간(video duration), 수정할 입력 이미지 여부, 결과에 워터마크를 표시할지 여부)을 말로 요청할 수 있습니다. 이 중 어떤 것을 명시하면 에이전트는 주어진 대로 사용하고; 생략하면 선택하거나 구성된 값으로 되돌아갑니다.
npx -y skills add Cripacx/mediagen --skill mediagen
이것이 전체 설치 과정입니다. 별도로 설정할 것이 없습니다. — 이 스킬은 npx를 통해 CLI를 실행하며, 첫 사용 시 가져와서 이후에 캐시합니다.
그런 다음 키를 제공하세요:
npx -y mediagen init
대화형 마법사(interactive wizard): 제공자를 선택하고, 각 키를 에코되지 않게 입력하며, 라이브 API와 각각 검증하고, 제공자별 모델을 선택하며, 기본값을 설정합니다. 시작하기에 충분한 키는 하나만 있어도 됩니다.
이제 에이전트에게 이미지 생성을 요청하기만 하면 됩니다.
mediagen models를 사용하세요.그리고 하지 않는 것: 채팅창에 API 키를 붙여넣으라고 요구하지 않습니다. 구성 오류가 발생하면 이 기능은 사용자 자신의 터미널에서 mediagen init을 실행하라고 알려줍니다.
mediagen init은 첫 사용 설정을 담당합니다. 나중에 무언가를 변경하려면:
npx -y mediagen config edit
현재 값과 해당 값이 어디서 왔는지(제공업체, 모델, 키, 출력 디렉토리, 품질 프리셋, 그리고 mediagen mark의 기본 동작)를 보여주는 모든 설정 메뉴가 있습니다. 변경 사항은 적용할 때마다 기록됩니다.
터미널이 없는 CI 및 스크립트의 경우, config set은 동일한 설정을 인수로 받습니다:
선호하는 순서를 설정하세요. 가장 선호하는 것을 먼저 지정합니다:
echo "$GEMINI_API_KEY" | npx -y mediagen config set gemini --stdin
npx -y mediagen config set gemini-model gemini-3-pro-image
npx -y mediagen config set provider-priority gemini,kie,openai
이것은 우선순위일 뿐, 화이트리스트는 아닙니다. --provider가 없는 요청은 키를 가지고 있고 작업을 수행할 수 있는 순서상 가장 첫 번째 제공업체로 전달됩니다. 따라서 OpenAI 키가 누락되어도 Gemini가 할 수 있는 작업은 중단되지 않으며, 비디오를 요청하면 아무것도 지원하지 않는 제공업체를 건너뜁니다. --provider로 이름을 지정하는 것이 모든 것을 무시합니다.
mediagen models는 결과적인 순서, 사용 가능한 제공업체, 그리고 요청이 무엇을 얻게 될지 보여줍니다:
1. Google Gemini (gemini) [선호됨, config 파일의 키 사용]
사용할 모델: gemini-3.1-flash-image (제공업체 기본값)
2. Kie AI (kie) [config 파일의 키 사용]
...
--json을 사용하면 wouldUse, usableProviders, 그리고 providerPriority가 추가됩니다. 이것이 스킬이 생성하기 전에 에이전트에게 읽히는 정보이며, 따라서 키가 없는 제공업체의 모델은 절대 선택하지 않습니다.
설정된 내용을 확인하고 키가 여전히 작동하는지 확인하려면:
npx -y mediagen doctor
doctor는 제공업체별로 키가 설정되었는지, 어느 레이어에서 왔는지, 그리고 해당 제공업체가 이를 수용하는지 보고합니다. 여기서 not configured, rejected, unreachable, 그리고 _no cheap way to check_를 구분하여 유지하는 이유는 네 가지 다른 수정 사항을 요구하기 때문입니다.
[!경고]
API 키를 인수로 받는 플래그는 의도적으로 없습니다. 인수는 셸 히스토리와 프로세스 목록에 남으며, 사용된 명령보다 더 오래 지속됩니다.
설정은 환경 변수에서 먼저, 다음으로 작업 디렉터리의 .env 파일에서, 그리고 마지막으로 설정 파일에서 순차적으로 해결됩니다:
⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.
| Variable | 목적 (Purpose) |
|---|---|
GEMINI_API_KEY, OPENAI_API_KEY, KIE_API_KEY | 자격 증명(credentials); 최소 하나 이상 필요 |
| ... |
[!TIP]
현재 설정한 키를 가리는 오래된 환경 변수(stale environment variable)가 이 도구에서 가장 비용이 많이 드는 실패 원인입니다.mediagen config list를 사용하면 모든 가려진 값(shadowed value)을 표시하므로 추측할 필요 없이 확인할 수 있습니다.
| 제공업체 | 이미지 (Images) | 비디오 (Video) | 편집 (Editing) | 키 검증 (Key verification) |
|---|---|---|---|---|
| Google Gemini | Nano Banana 계열, 최대 4K | 가능 (yes) | 가능 (yes) | 실시간 프로브 (live probe) |
| ... |
[!NOTE]
OpenAI는 종횡비(aspect ratios) 대신 픽셀 크기(pixel dimensions)를 사용하며, 실제로 16:9 비율을 생성할 수 없습니다. 가장 넓은 이미지는 1536×1024로 3:2입니다. 16:9를 요청하면 다른 것으로 조용히 제공되는 것이 아니라 이름으로 거부됩니다. 이 스킬(skill)은 이를 알고 있어 넓은 모양(wide shapes)을 Gemini로 라우팅합니다.
나열된 목록에 없는 모델이라도 해당 제공업체로 전송되므로, mediagen이 알기 전에 새로 출시된 모델도 작동합니다. Kie의 카탈로그는 수동으로 유지 관리되는 것이 아니라 Kie 자체 문서에서 생성됩니다.
EU AI Act(유럽연합 인공지능법)은 공개 의무를 두 가지로 나누므로, mediagen mark에는 두 개의 독립적인 스위치(switches)가 있습니다:
| 플래그 (Flag) | 의무 (Duty) | 기능 (What it does) |
|---|---|---|
| machine-readable | 도구로 찾을 수 있게 하기 (make it findable by tools) | IPTC/XMP DigitalSourceType을 작성하며, 기본적으로 활성화(on by default)됩니다. |
--visible-label | 사람에게 공개하기 (disclose it to people) | EU의 공식 AI 콘텐츠 라벨을 합성합니다 (composites the EU's official AI-content label). |
생성(Generating)은 절대 마킹하지 않습니다. 마킹은 항상 두 번째 명령어이며, 파일에 나중에 실행됩니다:
npx -y mediagen image "a wide banner" --aspect-ratio 21:9 --size 2K --json
npx -y mediagen mark ./output/image-….jpg --visible-label --label-position top-left
이것은 의식이 아닙니다. 가시적 라벨(visible label)은 피사체가 아닌 곳에 위치해야 하며, 그 위치는 완성된 이미지를 통해서만 알 수 있습니다. 기계가 읽을 수 있는 마커 역시 공짜가 아닙니다. JPEG나 WebP에 메타데이터를 추가한다는 것은 디코딩하고 재인코딩하는 것을 의미하므로, 라벨링은 비용이 드는 손실 압축 과정(lossy pass)입니다. 따라서 이는 의도적으로 지불할 가치가 있는 것이지, 이미지를 요청하는 부수적인 효과로 처리해서는 안 됩니다. mediagen은 이 비용을 작게 유지하기 위해 고품질로 재인코딩하지만, 0으로 만들 수는 없습니다.
`mediagen mark`가 매번 요청받지 않아도 가시적 라벨을 그리도록 하려면 다음을 수행해야 합니다:
```bash
npx -y mediagen config edit # "AI marking by default"
설정된 기본값은 여전히 --no-mark 또는 --no-visible-label을 사용해 실행별로 재정의할 수 있습니다.
가시적 라벨은 유럽 위원회 자체 아이콘이며, AI 생성 콘텐츠 투명성 관행(Code of Practice on Transparency of AI-generated Content)과 함께 발표되었으며 출처 표기 없이 자유롭게 사용할 수 있습니다. 세 가지 변형 중 두 가지가 사용됩니다: 기본값인 AI GENERATED, 사람이 만들고 모델을 변경한 미디어에 사용하는 --modified를 적용한 AI MODIFIED입니다. 밝은 버전 또는 어두운 버전은 라벨이 놓이는 모서리 부분의 실제 배경에 따라 선택되기 때문에, 아무도 읽을 수 없는 라벨은 공개(disclosure)로 간주되지 않습니다.
기본적으로는 오른쪽 하단에 위치합니다. --label-position을 사용하면 다른 모서리로 이동할 수 있으며, auto를 사용하면 이미지 디테일이 가장 적은 곳에 배치됩니다.
[!중요]
가시적 라벨은 절대 원본 소스 위에 덮어쓰지 않습니다.mediagen mark photo.png --visible-label을 실행하면photo.labelled.png를 생성하고,photo.png의 픽셀은 원래 그대로 유지하면서 기계가 읽을 수 있는 마커만 그 안에 기록합니다. 따라서 두 파일 중 어느 것을 출판하든 공개 정보(disclosure)를 담게 됩니다. 라벨이 잘못 배치된 경우, 손상되지 않은 원본과 아무것도 없는 상태에서 다시 만들 수 있습니다. 정말로 덮어쓰기를 원하는 경우에만--in-place를 사용하십시오.
이 스킬은 CLI(Command Line Interface)를 래핑한 것이며, 이 CLI는 독립적으로 작동합니다.
npx -y mediagen image "a wide banner" --aspect-ratio 21:9 --size 2K
npx -y mediagen image "make the sky stormy" --input ./photo.jpg
npx -y mediagen mark ./output/image-….jpg --visible-label
...
자주 사용해서 더 짧은 명령어를 원한다면 전역으로 설치하세요:
npm install -g mediagen
| 옵션 | 설명 |
|---|---|
--provider <name> | gemini, openai, kie |
| ... |
[!TIP]
스킬 없이 프롬프트 작성은 사용자에게 달려 있습니다. mediagen은 작성된 프롬프트를 정확하게 전송하며, 확장하거나 재작성하지 않습니다. 주제, 구도, 빛, 카메라 또는 매체, 재료 및 분위기를 결정하고, 원치 않는 것이 아니라 원하는 것을 말하세요.
--json을 사용하면 표준 출력(stdout)에 오직 하나의 JSON 객체만 포함됩니다. 그렇지 않으면 저장된 경로는 마지막 줄이며, 실패할 경우 stdout에 아무것도 기록되지 않습니다. 따라서 마지막 줄을 읽는다고 해서 기대했던 경로가 오류 메시지가 될 수는 없습니다.
{
"success": true,
"filePath": "./output/image-20260823T094107Z.png",
...
| 종료 코드 (Exit code) | 의미 (Meaning) |
|---|---|
0 | 성공 (success) |
| ... | |
실패할 경우 errorCode가 반환됩니다. 이 코드는 VALIDATION_ERROR, CONFIG_ERROR, API_ERROR, NETWORK_ERROR, FILE_ERROR, CONTENT_BLOCKED 또는 TIMEOUT 중 하나이며, 구체적인 다음 조치를 명시하는 hint를 포함합니다. |
스킬을 실행하는 대신 MCP(Message Communication Protocol)를 사용하는 호스트의 경우. 동일한 패키지이지만, mediagen mcp로 시작하여 generate_media, list_models, check_configuration 기능을 노출합니다.
claude mcp add mediagen --env GEMINI_API_KEY=your-api-key-here -- npx -y mediagen mcp
⚠️ --는 Claude 자체 플래그와 서버를 시작하는 명령어를 구분합니다.
진입점(entry)이 작성되는 위치를 변경하려면 --scope project 또는 --scope user를 추가하세요.
설정(Settings) → 개발자(Developer) → 구성 편집(Edit Config), 또는 직접 편집:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json{
"mcpServers": {
"mediagen": {
...
이후 Claude Desktop을 재시작하세요.
</details> <details> <summary><strong>VS Code</strong></summary>code --add-mcp "{"name":"mediagen","command":"npx","args":["-y","mediagen","mcp"]}"
또는 작업 공간에 .vscode/mcp.json을 생성하세요. 참고로 VS Code는 mcpServers가 아닌 servers를 사용합니다:
{
"servers": {
"mediagen": {
...