Agnes 이미지 생성
agnes-img는 agnes image generate의 래퍼입니다: 동일한 파라미터에 2.5 모델과 자동 다운그레이드를 추가로 지원합니다.
현재 2.5(agnes-image-2.5-flash)가 기본값이며, 2.1(agnes-image-2.1-flash)은 다운그레이드 및 호환용입니다.
사전 확인
agnes key status
"status": "missing"은 Key가 설정되지 않았음을 의미합니다. 사용자에게 https://platform.agnes-ai.com 에서 API Key를 생성하도록 한 후,agnes key set <KEY>(로컬 설정에 기록)를 실행하거나 환경 변수AGNES_API_KEY를 설정하도록 안내하세요.- Key를 임의로 만들거나 프로젝트 파일이나 응답 본문에 Key를 포함하지 마세요.
모델 선택
| 요구 사항 | 사용법 |
|---|---|
| 기본 (정식 제출) | 아무것도 전달하지 않음 → agnes-image-2.5-flash |
| 2.1 지정 | --model 2.1 |
| 기본값 변경 | 환경 변수 AGNES_IMAGE_MODEL=2.1 |
| 자동 다운그레이드 끄기 | --no-fallback (또는 AGNES_IMAGE_FALLBACK=0) |
- 우선순위:
--model>AGNES_IMAGE_MODEL> 기본값 2.5. - 2.5가 5xx를 반환하면 자동으로 2.1로 한 번 재시도하며, stderr에
role=fallback이 출력됩니다. 응답에는 실제 사용된 모델을 명시해야 합니다. - stderr에는 항상
generated with <model>이 출력되며, 이를 기준으로 응답에 모델을 표시합니다.
텍스트-이미지 생성
agnes-img --prompt "설명" --size 2K
- 성공 시 stdout에는 이미지 URL만 출력되며, 모델명/작업 ID/다운그레이드 정보/오류는 stderr로 출력됩니다.
--size는1K/2K/3K/4K단위를 지원하며,1024x768같은 정확한 값도 호환됩니다 (기본값1024x768).- 단위는 기본적으로 1:1 비율입니다. 16:9, 9:16 등 다른 비율이 필요한 경우 해당하는 원본 크기를 전달하세요. 예를 들어 16:9는
1312x736(1K) 또는2624x1472(2K), 9:16은736x1312를 사용합니다.
이미지-이미지 및 다중 이미지 합성
agnes-img --prompt "사이버펑크 야경으로 바꿔줘" --image ./ref.png
agnes-img --prompt "이 두 참조 이미지를 합쳐서 포스터 만들어줘" --image ./a.png --image ./b.png
--image는 반복 가능하며, 로컬 경로, 공개 URL 또는 Data URI를 지원합니다. 로컬 파일은 자동으로 Data URI로 변환됩니다.- 이미지 수정 시 프롬프트에 "무엇을 유지하고, 무엇을 바꿀지"를 명시하면 결과가 더 안정적입니다.
저장 및 표시 (필수)
URL은 임시 링크이므로 반드시 작업 공간에 다운로드해야 합니다:
mkdir -p output output/drafts
curl -sSL "<URL>" -o "output/agnes-$(date +%Y%m%d-%H%M%S).png"
ls -l output/*.png
- 파일이 비어 있지 않은지(
file/ 크기 > 0) 확인한 후 전달하세요. read_image를 사용하여 생성된 이미지를 미리보고, 응답에서로 표시하거나 필요에 따라present하세요.
출력 디렉토리 규칙 (반드시 준수)
output/ 최종 제출 이미지, 영구 보관
<subject>.png 주제의 메인 이미지 (예: eagle-hare.png)
<subject>-<variant>.png 같은 주제의 다른 스타일 제출본 (예: eagle-hare-ink.png)
output/drafts/ 중간 작업물 / 교체된 버전, 7일 후 정리 가능
<subject>-<variant>-<YYYYMMDD-HHMM>.png
규칙:
- 최종 제출 이미지는
output/<주제>.png에 바로 저장합니다. 이름은 소문자와 하이픈을 사용하고 영어로 의미 있게 작성하며-v2,-final,-복사본같은 임시 접미사를 사용하지 마세요. - 새 버전으로 교체된 이전 이미지는 새 이미지가 최종 확인된 후
mv명령어로output/drafts/<주제>-<타임스탬프>.png로 이동시키고,output/에 남겨 혼동을 주지 않도록 합니다. - 최종 제출하지 않은 실험본(구성 테스트용, 파라미터 테스트용)은 바로
output/drafts/에 저장합니다. - 정리는 항상
agnes-gc를 사용하며,rm으로output전체를 수동으로 삭제하지 마세요:
agnes-gc # 미리보기: drafts에서 7일 초과된 항목
agnes-gc --apply # 실행
agnes-gc --all # 미리보기: drafts 전체 비우기
agnes-gc는 이름이 drafts인 디렉토리에만 적용됩니다. output/ 안의 최종 제출 이미지는 절대 삭제되지 않습니다.
자주 묻는 질문
{"ok":false,"error":{"type":"auth",...}}: Key가 설정되지 않았거나 유효하지 않습니다. 먼저agnes key status를 실행하세요.type: "validation": 파라미터가 유효하지 않습니다(예: 지원되지 않는 model,--prompt누락).hint에 따라 수정하고, 무작정 재시도하지 마세요.- 2.5에서 5xx 오류: 자동으로 2.1로 다운그레이드됩니다. stderr에
role=fallback이 나타나면 다운그레이드된 결과물이므로 전달 시 설명해야 합니다. - 생성은 보통 10~60초가 소요되며, Bash 타임아웃은 최소 180000ms로 설정하세요.
- 한 번에 하나의 생성 작업만 실행하여 동시 실행으로 인한 할당량 소진을 방지하세요.
호환성 참고
이전 agnes image generate 명령어도 여전히 사용 가능하지만, --model은 agnes-image-2.1-flash / agnes-image-2.0-flash만 허용하며 2.5를 지원하지 않습니다. 2.5 또는 자동 다운그레이드가 필요할 때는 항상 agnes-img를 사용하세요.