Medeo 비디오 생성 스킬
텍스트로 AI 비디오를 생성합니다. Medeo는 AI 비디오 에이전트로서 전체 스토리라인, 다중 장면 내러티브, 시나리오를 단일 호출로 처리합니다. 샷 구성, 전환, 페이싱, 음악은 모두 자동으로 처리됩니다.
⚠️ 스토리를 여러 호출로 분할하지 마세요. 전체 시나리오를 하나의
--message로 전달하세요.
0. 사전 점검 (필수 — 다른 작업 전에 실행)
명령어를 실행하기 전에 API 키가 설정되어 있는지 확인하세요:
python3 {baseDir}/scripts/medeo_video.py config 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); print('ok' if d.get('apiKey') else 'missing')"
- 출력이
ok→ 정상 진행 - 출력이
missing(또는 명령어 실패) → 즉시 중단, 다른 명령어를 실행하지 마세요. 채널에 적합한 방법으로 설정 메시지를 보내세요:
Feishu — Feishu API를 직접 사용하세요 (message 도구 사용 금지 — 카드가 렌더링되지 않음):
import json, urllib.request
cfg = json.loads(open("/home/ec2-user/.openclaw/openclaw.json").read())
feishu = cfg["channels"]["feishu"]["accounts"]["default"]
token = json.loads(urllib.request.urlopen(urllib.request.Request(
"https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal",
data=json.dumps({"app_id": feishu["appId"], "app_secret": feishu["appSecret"]}).encode(),
headers={"Content-Type": "application/json"}
)).read())["tenant_access_token"]
card = {
"config": {"wide_screen_mode": True},
"header": {"title": {"tag": "plain_text", "content": "🎬 비디오 생성 — API 키 필요"}, "template": "blue"},
"elements": [{"tag": "div", "text": {"tag": "lark_md", "content": "비디오를 생성하려면 **Medeo API 키**가 필요합니다.\n\n**단계:**\n1. https://medeo.app/dev/apikey 로 이동하세요.\n - 계정이 없으면 가입 절차가 안내됩니다. 로그인 후 키가 표시됩니다.\n2. 키를 복사하여 (`mk_`로 시작) 저에게 보내주세요.\n\n키를 받으면 모든 것을 설정하겠습니다."}}],
}
urllib.request.urlopen(urllib.request.Request(
"https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id",
data=json.dumps({"receive_id": "<USER_OPEN_ID>", "msg_type": "interactive", "content": json.dumps(card)}).encode(),
headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
))
Telegram / Discord / 기타 채널 — message 도구를 사용하여 일반 텍스트로 보내세요 (이 채널들은 마크다운을 기본 지원함):
🎬 비디오 생성 — API 키 필요
단계:
1. https://medeo.app/dev/apikey 로 이동하세요 (필요시 가입 — 로그인 후 키가 표시됨)
2. 키를 복사하여 (mk_로 시작) 저에게 보내주세요
키를 받으면 모든 것을 설정하겠습니다.
키를 받으면: python3 {baseDir}/scripts/medeo_video.py config-init --api-key "mk_..."
1. 최초 설정
API 키가 설정되지 않은 경우 스크립트는 "setup_required": true를 출력합니다.
- 사용자에게 다음 정확한 링크를 보내세요: https://medeo.app/dev/apikey (이 페이지는 로그인되어 있지 않으면 자동으로 등록을 안내한 후 API 키를 표시합니다)
- 키를 제공하면:
python3 {baseDir}/scripts/medeo_video.py config-init --api-key "mk_..."
2. 비디오 생성 (5-30분, 항상 비동기)
사용자는 비디오를 생성하는 3가지 방법만 알면 됩니다:
- 텍스트 전송 → 비디오 생성
- 텍스트 + 이미지 업로드 → 사용자 이미지를 사용하여 비디오 생성
- 텍스트 + 이미지 URL → URL 이미지를 사용하여 비디오 생성
에이전트가 나머지 작업을 자동으로 처리합니다.
중요: 생성 작업을 시작하기 전에 즉시 사용자에게 다음과 같은 확인 메시지를 보내세요: "🎬 비디오 생성 시작 — 약 5~10분 후 결과를 보내드리겠습니다." 조용히 기다리지 마세요. 사용자는 요청이 접수되었음을 알아야 합니다.
사용법 1: 텍스트만
python3 {baseDir}/scripts/medeo_video.py spawn-task \
--message "사용자의 비디오 설명" \
--deliver-to "oc_xxx" \
--deliver-channel "feishu"
사용법 2: 텍스트 + 업로드된 이미지 (사용자가 채팅으로 이미지 전송)
# 먼저: upload-file을 사용하여 media_id 획득 (섹션 3 참조)
python3 {baseDir}/scripts/medeo_video.py spawn-task \
--message "사용자의 비디오 설명" \
--media-ids "media_01..." \
--asset-sources my_uploaded_assets \
--deliver-to "oc_xxx" \
--deliver-channel "feishu"
사용법 3: 텍스트 + 이미지 URL
python3 {baseDir}/scripts/medeo_video.py spawn-task \
--message "사용자의 비디오 설명" \
--media-urls "https://example.com/photo.jpg" \
--asset-sources my_uploaded_assets \
--deliver-to "oc_xxx" \
--deliver-channel "feishu"
에이전트 자동 동작: 사용자가 이미지를 제공하면(사용법 2 또는 3), 항상
--asset-sources my_uploaded_assets를 전달하여 Medeo가 새 이미지를 생성하는 대신 사용자의 이미지를 사용하도록 합니다. 사용자는 이 플래그의 존재를 알 필요가 없습니다.
내부 매개변수 (에이전트 전용 — 사용자에게 절대 노출 금지)
이러한 매개변수는 에이전트가 자동으로 처리합니다. 사용자에게 언급하거나 제공을 요청하지 마세요.
| 플래그 | 사용 시기 | 기본 동작 |
|---|---|---|
--voice-id "voice_01..." | 특정 음성이 필요할 때 | Medeo가 자동 선택 |
--video-style-id "style_01..." | 특정 시각 스타일이 필요할 때 | Medeo가 자동 선택 |
--asset-sources | 사용자가 이미지를 제공할 때: my_uploaded_assets 전달 | Medeo가 결정 |
--recipe-id "recipe_01..." | 템플릿을 사용할 때 | 없음 |
--aspect-ratio "9:16" | 사용자가 세로/가로를 지정할 때 | 16:9 |
--duration-ms 30000 | 사용자가 길이를 지정할 때 | Medeo가 결정 |
--no-render | 디버그 전용 — 렌더링 건너뛰기 | 항상 렌더링 |
전달 대상 (--deliver-to)
매우 중요 — 생성된 비디오가 전송될 위치를 결정합니다.
| 컨텍스트 | --deliver-to 값 | 예시 |
|---|---|---|
| Feishu 그룹 채팅 | 그룹의 chat_id (oc_로 시작). 수신 메타데이터의 conversation_label 또는 chat_id에서 추출 — chat: 접두사가 있으면 제거 (예: chat:oc_xxx → oc_xxx) | oc_158fd3e54407cbe170697c6c954bd4f2 |
| Feishu 개인 채팅 | 사용자의 open_id (ou_로 시작). 수신 메타데이터의 sender_id에서 추출 — user: 접두사가 있으면 제거 | ou_f7f458f4d7b4ff49ec1b8de22a1e3206 |
| Telegram | 수신 메시지 컨텍스트의 chat_id | -1001234567890 |
| Discord | 수신 메시지 컨텍스트의 channel_id | 1234567890123456 |
Feishu에서 그룹 vs 개인 채팅 구분 방법:
- 수신 메타데이터의
is_group_chat확인 true→conversation_label/chat_id(oc_값) 사용false→sender_id(ou_값) 사용
2단계: 반환된 args로 sessions_spawn 사용 (label: "medeo: <간략한 설명>", runTimeoutSeconds: 2400`)
3단계: 사용자에게 생성 중이라고 알립니다. 하위 에이전트가 완료 시 자동으로 알림.
3. 에셋 업로드
3a. URL에서 (이미지에 공개 URL이 있는 경우)
python3 {baseDir}/scripts/medeo_video.py upload \
--url "https://example.com/photo.jpg" \
--project-id "project_01..." # 선택 사항: 미디어를 기존 프로젝트와 연결
--no-wait # 선택 사항: 폴링 없이 즉시 job_id 반환
3b. IM 첨부 파일에서 (사용자가 직접 이미지 전송) ← 새 기능
사용자가 Telegram, Discord, Feishu 또는 로컬 파일로 이미지를 보낼 때 upload-file을 사용하세요.
URL 기반 업로드 대신 직접 업로드 API(준비 → S3 presigned PUT → 등록)를 사용합니다.
트리거: 사용자가 비디오 생성을 명시적으로 요청하고 동일한 메시지에 이미지 첨부 파일을 보낼 때만 (예: "이 사진으로 비디오 만들어 줘"). 모든 이미지 메시지에 대해 자동으로 업로드하지 마세요. 다른 스킬이나 대화에 비디오 생성과 관련 없는 이미지가 포함될 수 있습니다.
# 로컬 파일에서 (OpenClaw가 첨부 파일에서 다운로드)
python3 {baseDir}/scripts/medeo_video.py upload-file \
--file /tmp/user_photo.jpg
# 직접 URL에서 (Discord CDN 등)
python3 {baseDir}/scripts/medeo_video.py upload-file \
--url "https://cdn.discordapp.com/attachments/..."
# Telegram에서 (message.photo[-1].file_id)
# TELEGRAM_BOT_TOKEN이 환경 변수로 설정되어 있어야 함 — 절대 CLI 인수로 전달하지 마세요 (ps aux로 누출됨)
TELEGRAM_BOT_TOKEN="$TELEGRAM_BOT_TOKEN" python3 {baseDir}/scripts/medeo_video.py upload-file \
--telegram-file-id "AgACAgIAAxk..."
# Feishu에서 (message_id + message content의 image_key)
python3 {baseDir}/scripts/medeo_video.py upload-file \
--feishu-message-id "om_xxx" \
--feishu-image-key "img_v3_xxx" \
--feishu-app-token "$FEISHU_APP_TOKEN"
출력: {"media_id": "media_01...", "filename": "photo.jpg"}
그런 다음 media_id를 생성에 전달:
python3 {baseDir}/scripts/medeo_video.py spawn-task \
--message "이 사람이 나오는 비디오 만들어 줘" \
--media-ids "media_01..."
플랫폼별 이미지 추출 가이드
| 플랫폼 | 이미지 소스 얻는 방법 | upload-file 인수 |
|---|---|---|
| Telegram | message.photo[-1].file_id | --telegram-file-id |
| Discord | message.attachments[0].url (공개 CDN URL) | --url |
| Feishu | 메시지 콘텐츠 JSON의 message_id + image_key | --feishu-message-id + --feishu-image-key |
첨부 파일 바이너리 다운로드 → /tmp에 저장 | --file | |
| 일반 URL | 모든 직접 이미지 URL | --url |
참고: Discord 첨부 파일 URL은 공개 CDN 링크입니다. --url이 직접 작동합니다. 다른 모든 플랫폼은 다운로드에 인증이 필요합니다.
3c. 생성 파이프라인에 인라인으로 포함
# URL 기반 (기존 동작)
python3 {baseDir}/scripts/medeo_video.py spawn-task \
--message "이 운동화의 제품 쇼케이스" \
--media-urls "https://example.com/front.jpg" "https://example.com/side.jpg"
.jpg, .png, .webp, .mp4, .mov, .gif를 지원합니다. 더 높은 해상도와 여러 각도가 더 나은 결과를 제공합니다.
3d. 업로드 상태 확인
upload 또는 upload-file 후 업로드 작업을 확인해야 하는 경우:
python3 {baseDir}/scripts/medeo_video.py upload-status --job-id "job_01..."
완료 시 미디어 상태(processing, completed, failed)와 media_id를 반환합니다.
4. 저수준 파이프라인 명령어 (에이전트 내부 — 사용자에게 절대 노출 금지)
이 명령어들은 에이전트 디버깅 또는 수동 개입 전용입니다. 사용자는 이러한 명령어를 절대 볼 수 없어야 합니다.
파이프라인 흐름:
spawn-task (권장, 비동기)
└── generate (차단, 동일 파이프라인)
├── upload (--media-urls가 있는 경우)
├── compose → compose-status (폴링)
└── render → render-status (폴링)
| 명령어 | 기능 | 주요 인수 |
|---|---|---|
generate | 차단 전체 파이프라인 (upload→compose→render) | deliver 플래그를 제외한 spawn-task와 동일 |
compose | 프로젝트만 생성 (렌더링 없음) | --message, --media-ids, --recipe-id |
compose-status | compose 작업 폴링 | --task-id "task_01..." |
render | 기존 프로젝트 렌더링 | --project-id "project_01..." |
render-status | 렌더링 작업 폴링 | --job-id "render_01..." |
upload-status | 업로드 작업 폴링 | --job-id "job_01..." |
모든 명령어는 폴링 없이 즉시 반환하는 --no-wait를 지원합니다.
5. 레시피 탐색
python3 {baseDir}/scripts/medeo_video.py recipes # 템플릿 목록
python3 {baseDir}/scripts/medeo_video.py recipes --cursor <c> # 페이지네이션
생성에 사용: --recipe-id "recipe_01...". docs/recipes.md 참조.
6. 빠른 명령어 참조 (에이전트용, 사용자 대상 아님)
| 명령어 | 설명 | 사용자 표시? |
|---|---|---|
recipes | 비디오 템플릿 목록 | 예 — "어떤 템플릿이 있나요?" |
last-job | 최신 작업 상태 | 예 — "내 마지막 비디오 완료됐나요?" |
history | 작업 기록 (최근 50개) | 예 — "내 비디오 기록 보여줘" |
config | 현재 설정 표시 | 아니요 |
config-init --api-key "mk_..." | API 키 초기화 | 설정 중에만 |
upload --url "URL" | 공개 URL에서 업로드 | 아니요 (에이전트 내부) |
upload-file --file PATH | 로컬 파일에서 업로드 | 아니요 (에이전트 내부) |
upload-file --url "URL" | URL 다운로드 → 업로드 | 아니요 (에이전트 내부) |
upload-file --telegram-file-id "..." | Telegram 첨부 파일 업로드 | 아니요 (에이전트 내부) |
upload-file --feishu-image-key "..." | Feishu 첨부 파일 업로드 | 아니요 (에이전트 내부) |
upload-status --job-id "..." | 업로드 작업 상태 확인 | 아니요 (에이전트 내부) |
compose-status --task-id "..." | compose 작업 진행 확인 | 아니요 (에이전트 내부) |
render-status --job-id "..." | 렌더링 작업 진행 확인 | 아니요 (에이전트 내부) |
7. 주요 규칙
- 항상 비동기 — 생성을 위해
spawn-task+sessions_spawn사용 - 스토리는 한 번에 — 전체 스토리라인을 하나의
--message로, 절대 분할 금지 - 크레딧 부족 — 오류 출력에서 충전 링크 공유
- IM 이미지 업로드 — 사용자가 해당 이미지로 비디오 생성을 명시적으로 요청할 때만 이미지를 업로드하세요. 모든 이미지 메시지를 자동으로 업로드하지 마세요 (사용자가 다른 스킬을 설치했을 수 있음). 트리거되면:
upload-file을 먼저 실행 →media_id획득 →--media-ids를 통해 생성에 전달. 사용자가 이미 이미지를 보냈는데 URL을 요청하지 마세요. - IM 네이티브 전달 — 생성 후, IM 채널의 네이티브 방법을 사용하여 비디오를 전달하세요 (URL만 전달하지 마세요). 각 채널에는 전용 전달 스크립트가 있습니다:
- Feishu:
python3 {baseDir}/scripts/feishu_send_video.py --video /tmp/result.mp4 --to "oc_xxx_or_ou_xxx" --cover-url "<thumbnail_url>" --duration <ms>(그룹 채팅에는oc_chat_id, 개인 채팅에는ou_open_id 사용;chat:oc_xxx및user:ou_xxx접두사 형식도 허용됨) - Telegram: 비디오 다운로드 후
telegram_send_video.py를 통해 전송 (토큰은 환경 변수에서만):curl -sL -o /tmp/medeo_result.mp4 "<video_url>" TELEGRAM_BOT_TOKEN="$TELEGRAM_BOT_TOKEN" python3 {baseDir}/scripts/telegram_send_video.py \ --video /tmp/medeo_result.mp4 \ --to "<chat_id>" \ --cover-url "<thumbnail_url>" \ --duration <ms> - 기타 채널:
message도구를 통해 URL 전송
- Feishu:
- 비디오가 준비되면 하위 에이전트가 사용자에게 대화형 링크를 표시하므로 추가 작업이 필요하지 않습니다.
- 확인 메시지 — 생성 작업을 시작한 후 즉시 사용자에게 "비디오 생성 시작" 메시지를 보내세요. 절대 조용히 기다리지 마세요.
- 수동 개입 — 생성 시간 초과 또는 실패 시에만 (비디오는 일반적으로 5-10분 소요)
8. 예제 워크플로우
예 1: "자동차가 달리는 비디오 만들어 줘"
- 사전 점검 실행 →
ok spawn-task --message "자동차가 고속도로를 달리는 비디오" --deliver-to "oc_xxx" --deliver-channel "feishu"- 사용자에게 "🎬 비디오 생성 시작 — 약 5~10분 후 결과를 보내드리겠습니다."라고 알림
- 하위 에이전트가 완료를 처리
예 2: "이 사진으로 비디오 만들어 줘" + 사진 첨부
- 사전 점검 실행
upload-file로 사진 업로드 →media_id획득- 사용자에게 "사진을 업로드했습니다. 이제 비디오를 생성하겠습니다."라고 알림
spawn-task --message "이 사진을 사용한 비디오" --media-ids "media_01..." --asset-sources my_uploaded_assets --deliver-to "oc_xxx" --deliver-channel "feishu"- 사용자에게 생성이 시작되었음을 알림
예 3: "어떤 템플릿이 있나요?"
- 사전 점검 실행
recipes실행- 레시피 목록을 사용자에게 표시
- 사용자가 선택하면 해당
--recipe-id로 생성