개발자 문서

예시

자동화·서버

사람이 지켜보지 않는 곳(서버·예약 작업·CI)에서 aimz 를 돌리는 방법입니다. 핵심은 로그인 한 번, 크레딧 상한, 종료 코드 확인 세 가지입니다.

Linux 서버에 설치·로그인

설치는 venv 방법이 서버에 잘 맞습니다(관리자 권한 불필요). 로그인은 브라우저 없이 합니다.

서버 (SSH)
aimz login --no-browser
# 아래 주소를 브라우저(휴대폰 포함)에서 열어 로그인하세요.
#   https://aimzlabs.com/app-login?challenge=…&client=cli
# → 내 PC 브라우저로 열어 로그인하고, 화면의 코드를 여기에 붙여 넣는다

aimz whoami

데스크톱이 없는 서버에는 OS 자격 증명 저장소가 없어서 토큰을 ~/.aimz/credentials.json(본인만 읽기) 에 둡니다. 그 계정으로만 서버에 들어올 수 있게 관리하세요. 세션은 30일이며 쓰는 동안 자동으로 연장됩니다.

무인 실행의 안전장치

  1. 1회 상한을 겁니다. 예상 크레딧이 상한을 넘는 생성은 실행하지 않고 종료 코드 3 으로 멈춥니다.
    터미널
    aimz agent limit 200
  2. 터미널에서 한 장을 직접 만들어 크레딧 사용에 동의합니다. 기본 모드(once)는 계정마다 처음 한 번만 묻고, 그 뒤 스크립트는 묻지 않고 진행합니다.
  3. 스크립트에는 --yes 를 붙이지 않습니다. --yes 는 사람이 이미 승인했다는 뜻이라 1회 상한 확인까지 건너뜁니다.
주의
대량 생성 스크립트는 반복 횟수 × 한 장 값만큼 크레딧을 씁니다. 먼저 aimz estimate 로 한 장 값을 보고, 횟수를 작게 시험한 뒤 늘리세요. 여러 개는 generate 를 반복하지 말고 aimz batch 파일.json 으로 한 번에 넣으면 예상 합계를 한 번에 확인하고 서버 대기열이 차례로 돌립니다(batch 예시, 대기열 규칙). 한 사람이 줄 세울 수 있는 작업은 30개, 생성 요청은 분당 30회까지입니다.

매일 정해진 시각에 생성

macOS·Linux — cron

~/aimz-daily.sh
#!/usr/bin/env bash
# ~/aimz-daily.sh — 매일 아침 오늘의 이미지 한 장
set -u
OUT="$HOME/aimz-daily/$(date +%F)"
mkdir -p "$OUT"
"$HOME/.local/bin/aimz" generate nanobanana \
  --prompt "오늘의 하늘을 닮은 수채화 풍경, 날짜 $(date +%F)" \
  -p aspect_ratio=16:9 --session daily -o "$OUT" < /dev/null
code=$?
case $code in
  0) echo "ok $(date)";;
  3) echo "확인 필요 — 1회 상한을 넘었거나 아직 크레딧 사용 동의가 없음";;
  4) echo "로그인 필요 — 서버에서 aimz login --no-browser";;
  *) echo "실패 ($code) — aimz failures 로 이유 확인";;
esac
exit $code
crontab
# crontab -e — 매일 오전 9시 (cron 은 PATH 가 짧아 전체 경로를 쓴다)
0 9 * * * /bin/bash $HOME/aimz-daily.sh >> $HOME/aimz-daily.log 2>&1

cron 에서는 PATH 가 짧아서 aimz 를 못 찾습니다. 스크립트처럼 전체 경로(which aimz 로 확인)를 쓰세요. 스크립트에 실행 권한도 주세요: chmod +x ~/aimz-daily.sh.

Windows — 작업 스케줄러

C:\aimz\daily.ps1
# C:\aimz\daily.ps1 — 매일 아침 오늘의 이미지 한 장
$out = Join-Path $HOME ("aimz-daily\" + (Get-Date -Format yyyy-MM-dd))
New-Item -ItemType Directory -Force $out | Out-Null
aimz generate nanobanana --prompt "오늘의 하늘을 닮은 수채화 풍경" -p aspect_ratio=16:9 --session daily -o $out
switch ($LASTEXITCODE) {
  0 { "ok" }
  3 { "확인 필요 — 1회 상한을 넘었거나 아직 크레딧 사용 동의가 없음" }
  4 { "로그인 필요 — aimz login" }
  default { "실패 ($LASTEXITCODE) — aimz failures 로 이유 확인" }
}
exit $LASTEXITCODE
PowerShell (한 번만)
# 작업 스케줄러에 등록 — 매일 오전 9시
schtasks /Create /SC DAILY /ST 09:00 /TN "AIMZ daily" /TR "powershell -NoProfile -ExecutionPolicy Bypass -File C:\aimz\daily.ps1"

결과를 프로그램에서 쓰기 (--json)

모든 명령은 --json 을 붙이면 사람이 읽는 문장 대신 JSON 하나를 표준 출력으로 냅니다. 진행 상황·업로드 알림은 표준 오류로 나가서 섞이지 않습니다.

# 저장된 파일 경로만 뽑기
(aimz generate nanobanana --prompt "가을 숲 캠핑장" -p aspect_ratio=21:9 -o ./out --json | ConvertFrom-Json).saved

# 잔액이 500 보다 적으면 멈추기
$bal = (aimz whoami --json | ConvertFrom-Json).balance
if ($bal -lt 500) { "잔액 부족: $bal"; exit 1 }

# 진행 중인 작업 수
(aimz jobs --json | ConvertFrom-Json).jobs.Count
generate --json 의 키내용
job작업 상태 전체 — job_id · state · credits · error 등
urls결과 파일 주소 목록
texts텍스트 모델의 답변 목록
saved-o 로 저장한 파일 경로 목록

whoami --json 은 계정 정보와 balance(잔액)·agent_mode 를, jobs --json 은 {"jobs": [...]} 를 돌려줍니다.

종료 코드로 갈라 처리하기

코드뜻스크립트에서 할 일
0성공다음 단계로
1오류·생성 실패aimz failures 로 이유를 남기고 알림
2명령·옵션이 틀림스크립트 수정
3확인 필요 (상한 초과·동의 없음)사람에게 알리고 멈춤 — 자동으로 --yes 를 붙여 재시도하지 않기
4로그인 필요사람이 aimz login 다시

CI·다른 프로그램에서

  • CI 에는 개인 계정 토큰을 올리지 마세요. 토큰이 새면 그 계정으로 30일 동안 무엇이든 할 수 있습니다. 자동화 전용 계정을 따로 받아 쓰는 것을 권합니다.
  • 설정·토큰 위치를 작업마다 분리하려면 AIMZ_HOME 을 지정합니다(예: AIMZ_HOME=/srv/aimz-bot).
  • 다른 서버를 쓰려면 AIMZ_SERVER 또는 --server 를 씁니다.