Agnes AI 전체 모달 생성 Skill

개요

이 Skill은 Agnes AI (Sapiens AI)의 모든 생성 기능을 하나의 CLI 스크립트로 통합하여 제공합니다:

텍스트 생성: agnes-2.5-flash (Thinking 추론 모드 지원, $0)
이미지 이해/Vision: agnes-2.5-flash (OpenAI Vision API 호환, 이미지 내용 분석 가능)
텍스트->이미지/이미지->이미지: agnes-image-2.5-flash (최신 세대, 높은 정보 밀도 최적화; --model agnes-image-2.1-flash로 이전 세대로 전환 가능)
비디오 엔진 1 (V2.0): agnes-video-v2.0 — 텍스트->비디오 / 이미지->비디오 / 키프레임 애니메이션, 자유로운 프레임 속도와 해상도, $0/초
비디오 엔진 2 (Video 2.5 Flash): agnes-video-2.5-flash — 새로운 세대 모델, text/keyframe/reference 세 가지 모드, 다중 모달 참조, 한정 기간 무료 720P; 유료 업그레이드 --model agnes-video-2.5로 960P/2K 및 비디오 참조 해제 가능
자동 번역: 중국어 프롬프트를 자동으로 영어로 번역하여 API 호출
비동기 폴링: 비디오 작업을 자동으로 완료될 때까지 폴링

사전 조건

API Key가 설정되었는지 확인:
- 우선 scripts/agnes_client.py에 하드코딩된 API_KEY를 읽음
- 자리 표시자 YOUR_AGNES_API_KEY_HERE인 경우, 환경 변수 AGNES_API_KEY로 대체
- 둘 다 설정되지 않은 경우, 코드나 환경 변수에 API Key를 설정하도록 사용자에게 알림
Python 3.8+, 표준 라이브러리 urllib + json만 있으면 되며, 추가 종속성 없음.

CLI 명령어 빠른 참조

스크립트 위치: scripts/agnes_client.py

# 텍스트 생성
python scripts/agnes_client.py text "your prompt"
python scripts/agnes_client.py text "안녕하세요" --stream
python scripts/agnes_client.py text "퀵 정렬을 작성해 주세요" --thinking  # 2.5 추론 모드

# 텍스트->이미지 (agnes-image-2.5-flash, 기본 1K; 권장 방식 size + ratio)
python scripts/agnes_client.py image "A futuristic city at sunset, cinematic realism" --size 2K --ratio 16:9
python scripts/agnes_client.py image "달빛 아래 산책하는 고양이"
python scripts/agnes_client.py image "..." --model agnes-image-2.1-flash   # 이전 세대로 전환

# 이미지->이미지 (자동 비율 감지 — 기본적으로 주요 참조 이미지 비율에 따라 출력)
python scripts/agnes_client.py image "Transform to cyberpunk night" --image-url "https://...input.png" --image-url "https://...ref.png"

# 이미지->이미지 + 수동 ratio 지정 (자동 감지 안 함)
python scripts/agnes_client.py image "Transform to cyberpunk night" --image-url "https://...input.png" --ratio 16:9

# ── 비디오 엔진 1: V2.0 (자유 프레임 속도/해상도, $0) ──
python scripts/agnes_client.py video "A drone flying over mountains at sunrise" --poll          # 텍스트->비디오
python scripts/agnes_client.py video "Add motion to this scene" --image-url "https://...frame.png" --poll  # 이미지->비디오
python scripts/agnes_client.py video --keyframes "https://a.com/1.png,https://a.com/2.png,https://a.com/3.png" --poll  # 키프레임 애니메이션

# ── 비디오 엔진 2: Video 2.5 Flash (새로운 세대, 무료 720P) ──
python scripts/agnes_client.py video25 "비가 내린 후의 미래 도시 거리, 네온사인 반사, 영화 품질 카메라 움직임" --poll          # text 텍스트->비디오
python scripts/agnes_client.py video25 "인물이 자연스럽게 돌아서 창문으로 걸어가다" --first-frame "https://.../f.png" --last-frame "https://.../l.png" --poll  # keyframe 첫 번째 및 마지막 프레임
python scripts/agnes_client.py video25 "<Picture 1>을 캐릭터 참조로 꽃밭에서 달리기" --image-url "https://.../char.png" --poll  # reference 이미지 참조
python scripts/agnes_client.py video25 "<Audio 1>의 리듬에 따라 야경 생성" --audio-url "https://.../music.mp3" --poll  # reference 오디오 참조
python scripts/agnes_client.py video25 "..." --model agnes-video-2.5 --size 960P               # 유료 업그레이드 (960P/2K)

# 비디오 작업 제출 후 대기하지 않음
python scripts/agnes_client.py video "..." --no-poll
python scripts/agnes_client.py video25 "..." --no-poll

# 비디오 작업 상태 조회 (V2.5 작업은 --model 사용 권장)
python scripts/agnes_client.py video-status TASK_ID
python scripts/agnes_client.py video-status TASK_ID --model agnes-video-2.5-flash

# 중국어 프롬프트 번역
python scripts/agnes_client.py translate "고양이 한 마리"

# 이미지 이해 / Vision (agnes-2.5-flash로 이미지 내용 분석)
python scripts/agnes_client.py vision --image-url "https://example.com/photo.png"
python scripts/agnes_client.py vision --image-url "https://example.com/photo.png" --prompt "이 시계는 어느 브랜드입니까?"

# 스모크 테스트 (API 연결 확인)
python scripts/agnes_client.py smoke-test

전체 워크플로우

텍스트->이미지 워크플로우

사용자로부터 중국어/영어 프롬프트를 받음
중국어 포함되고 --no-translate가 지정되지 않은 경우, 자동으로 agnes-2.5-flash를 사용하여 영어로 번역
POST /v1/images/generations 호출 (모델 기본값: agnes-image-2.5-flash)
응답 data[0].url에서 이미지 URL 추출
결과를 사용자에게 반환 (URL 표시, 또는 curl/브라우저로 열기 시도)

크기 권장: 텍스트->이미지의 경우 --size 2K --ratio 16:9와 같은 "사양 + 비율" 형식을 권장하여 예측 가능한 크기 얻기; 지원되지 않는 정확한 크기(예: 1920x1080)는 서버 측에서 표준화되므로 직접 자르기가 필요.

이미지->이미지 워크플로우

사용자가 입력 이미지 URL 또는 로컬 경로를 제공했는지 확인
프롬프트 번역이 필요한 경우 실행
동일한 엔드포인트 호출, extra_body.image에 입력 이미지 URL 배열 전달
생성 결과 반환

비디오 생성 워크플로우 (엔진 선택)

Skill에는 두 개의 비디오 엔진이 내장되어 있으며, 필요에 따라 선택:

엔진	하위 명령	모델	특징	가격
V2.0	`video`	`agnes-video-v2.0`	t2v/ti2vid/keyframes, 자유 프레임 속도(num_frames 8n+1) 및 해상도	$0/초
Video 2.5	`video25`	`agnes-video-2.5-flash` (기본값) / `agnes-video-2.5` (유료)	새로운 세대: text/keyframe/reference, 참조 이미지/오디오, 더 제어 가능한 카메라	flash 한정 기간 무료

Video 2.5 Flash (video25) 워크플로우:

자료에 따라 자동으로 모드 추론 (--mode auto), 명시적으로 지정 가능:
- text: 순수 텍스트 → 미디어 매개변수 없음
- keyframe: --first-frame / --last-frame (최소 하나)으로 시작 및 끝 구성 제한
- reference: --image-url (≤5장) / --audio-url (≤3개); 프롬프트에서 <Picture N> / <Audio N> 자리 표시자로 자료 참조
POST /v1/videos 제출, 매개변수: mode + seconds("4"~"12") + size(flash는 720P만) + aspect_ratio + seed
GET /agnesapi?video_id=<ID>&model_name=agnes-video-2.5-flash 폴링 (keyframe/reference는 model_name 필수)
상태 completed 후 응답에서 비디오 URL 추출

⚠️ video25와 video는 매개변수 체계가 완전히 다름: video25는 num_frames/width/height/fps/negative_prompt를 받지 않음 (400 반환).

비디오 매개변수 제약 (엔진 1 V2.0)

num_frames는 8n + 1을 만족해야 하며, 최대 441
기본값: num_frames=121, frame_rate=24 (약 5초)
빠른 테스트는 --num-frames 81 사용 (약 3.4초)

비디오 매개변수 제약 (엔진 2 Video 2.5)

seconds는 문자열 "4"~"12", 기본 "5"
size: flash는 고정 720P; 유료 모델 agnes-video-2.5는 720P/960P/2K 선택 가능
aspect_ratio: 21:9 / 16:9(기본) / 4:3 / 1:1 / 3:4 / 9:16
flash 제한: 참조 이미지 ≤5장, 오디오 ≤3개, 비디오 참조 불가 (유료 버전은 videos 지원)
실제 테스트 720P 16:9 출력은 약 1280x704

이미지 이해 (Vision) 워크플로우

agnes-2.5-flash는 OpenAI Vision API 형식의 다중 모달 입력을 지원하여 이미지 내용을 분석하고 텍스트 설명을 반환합니다. 이는 "시각 능력이 없는 모델에 눈을 제공하는" 브리징 솔루션입니다. 2.5 버전의 이미지 이해 능력은 2.0보다 강력하며, 세부 사항 인식이 더 정확합니다.

이미지가 공용 인터넷에서 접근 가능한 HTTP(S) URL에 업로드되었는지 확인
vision 명령 호출, 이미지 URL + 선택적 분석 프롬프트 전달
텍스트 설명 반환, 이를 다른 모델에 컨텍스트로 직접 전달 가능 (예: "이 이미지에서 시계 디자인에 대한 개선 제안을 해 주세요" — 먼저 vision으로 설명을 얻은 후, 임의의 텍스트 모델에 전달하여 분석)

Vision 명령 매개변수:

--image-url (필수, 여러 번 지정 가능): 분석할 이미지 URL
--prompt (선택): 분석 프롬프트, 기본값 "Describe this image in detail."
--system (선택): 시스템 프롬프트
--max-tokens (선택): 최대 출력 토큰, 기본값 1000
--no-translate (선택): 자동 번역 건너뛰기 (영어 프롬프트 권장)

프롬프트 모범 사례

이미지 Prompt 구조

[주제] + [장면] + [스타일] + [조명] + [구성] + [품질]

예시:

A luxury watch with a black leather strap on a marble surface, soft studio lighting, macro photography, 8K detail, high visual density

이미지->이미지 Prompt

변경할 대상 + 유지할 대상을 명확히 설명:

Transform the background to a dark luxury setting while preserving the watch design and angle.

비디오 Prompt

카메라 움직임과 시간 요소 포함:

A slow 360-degree rotation around the watch, revealing every detail, cinematic lighting, smooth movement

가격

모델	가격
`agnes-2.5-flash` (텍스트/Vision/추론)	무료 ($0/1M 토큰)
`agnes-image-2.5-flash` (이미지, 최신 세대)	무료 ($0/이미지, 모든 1K~4K 사양)
`agnes-image-2.1-flash` (이미지, 이전 세대)	무료 ($0/이미지)
`agnes-video-v2.0` (비디오 엔진 1)	무료 ($0/초)
`agnes-video-2.5-flash` (비디오 엔진 2)	한정 기간 무료 ($0/초, 720P)
`agnes-video-2.5` (비디오, 유료 업그레이드)	$0.025/초(720P) / $0.040/초(960P) / $0.055/초(2K)

가격은 공식 웹사이트 https://www.agnes-ai.com/ko-KR/docs/pricing 를 기준으로 하며, 무료 정책은 플랫폼 공지에 따라 변경될 수 있습니다.

알려진 제한 사항

2.5 Thinking 모드는 reasoning_content 필드(사고 과정)를 반환하며, 출력 토큰이 약간 증가
비디오 생성 시 가끔 division by zero 서버 오류 발생
V2.0 다중 이미지 비디오/키프레임 애니메이션은 아직 완전히 종단 간 검증되지 않음
이미지 API는 입력으로 HTTP(S) URL만 허용, base64는 허용하지 않음 (입력); 출력은 URL 또는 Base64 선택 가능
agnes-video-2.5-flash는 720P만, 비디오 참조 미지원; 960P/2K 또는 비디오 참조가 필요한 경우 유료 --model agnes-video-2.5 사용
video25의 keyframe/reference 작업 조회는 반드시 --model agnes-video-2.5-flash를 포함해야 함

자동 비율 감지 (i2i)

i2i 시 --ratio가 지정되지 않은 경우, 스크립트는 주요 참조 이미지(첫 번째 --image-url)의 가로세로비를 자동으로 감지하여 agnes-image-2.5-flash가 지원하는 8가지 공식 ratio 중 하나( 1:1 / 3:4 / 4:3 / 16:9 / 9:16 / 2:3 / 3:2 / 21:9 )에 매핑하여 출력 캔버스 비율이 입력 주제와 일치하지 않아 인물이 왜곡되는 것을 방지합니다.

# 자동 감지: [INFO] Main reference image: ... → auto ratio: ... 출력
python scripts/agnes_client.py image "prompt" --image-url MODEL_URL --image-url REF_URL --size 2K

# 수동 지정 (자동 감지 건너뛰기)
python scripts/agnes_client.py image "prompt" --image-url MODEL_URL --ratio 16:9

주요 참조 이미지 규칙: 첫 번째 --image-url은 구성/비율을 결정하는 주체(보통 모델/제품 이미지)로 간주되며, 두 번째부터는 스타일/세부 참조로 간주됩니다. 주요 참조 이미지를 변경하려면 --image-url 순서를 바꾸면 됩니다.

참조

API 상세 문서: references/api_reference.md
공식 웹사이트: https://agnes-ai.com/
API 플랫폼: https://platform.agnes-ai.com/

Agnes 멀티모달