개발자 문서

CLI

생성하기

모델을 고르고 → 입력 규격을 보고 → 예상 크레딧을 확인한 뒤 → 생성합니다. CLI 와 MCP 가 같은 순서입니다.

기본 순서

  1. 모델 고르기 — aimz models -m video (MCP: list_models)
  2. 입력 규격 보기 — aimz model seedance_fast (MCP: model_info). 여기 나온 키만 넣을 수 있고, 그 밖의 키는 서버가 버립니다.
  3. 예상 크레딧 — aimz estimate … (MCP: estimate_credits). 화면에 보이는 값과 실제 차감 규칙이 같습니다.
  4. 생성 — aimz generate … (MCP: generate)
규격 예 (aimz model seedance_fast, 일부)
{
  "id": "seedance_fast", "modality": "video",
  "params": [
    { "key": "prompt", "type": "text", "max": 25000 },
    { "key": "aspect_ratio", "type": "enum", "options": ["21:9","16:9","4:3","1:1","3:4","9:16"], "default": "16:9" },
    { "key": "resolution", "type": "enum", "options": ["480p","720p"], "default": "720p" },
    { "key": "duration", "type": "int", "min": 4, "max": 15, "default": 5 },
    { "key": "start_frame", "type": "image" }, …
  ]
}

예제

이미지

터미널
aimz generate nanobanana --prompt "한옥 마당의 고양이, 아침 햇살" -p aspect_ratio=16:9 -p count=2 -o ./out

# 내 사진을 바탕으로 고치기 (init_image)
aimz generate nanobanana --prompt "배경을 노을 진 바다로" --image ./photo.png -o ./out

영상

터미널
aimz generate seedance_fast --prompt "카메라가 천천히 다가간다" -p start_frame=./first.png -p duration=5 -p resolution=720p -o ./out

영상은 몇 분 걸릴 수 있습니다. 기다리지 않으려면 --no-wait 로 접수만 하고, 나중에 이어서 받으세요.

터미널
aimz generate kling-3-turbo --prompt "…" -p duration=5 --no-wait
# 접수: j_3a313f12…
aimz jobs j_3a313f12… --wait -o ./out

오디오

터미널
aimz generate el_sfx --prompt "처마 끝에 떨어지는 빗소리" -p duration=10 -o ./out

텍스트

터미널
aimz generate gpt-4.1-mini --prompt "신제품 소개 문구 3개, 각 20자 이내"

텍스트 모델은 답변을 터미널에 바로 출력합니다(--json 이면 texts).

에이전트(MCP)로

에이전트에게 원하는 결과를 말하면 위 순서대로 도구를 부릅니다. 모델이나 값을 정해 주면 그대로 씁니다.

에이전트에게
nanobanana 로 21:9 배너 이미지를 만들어 줘. 프롬프트는 "가을 숲속 캠핑장, 따뜻한 조명".
결과는 ./banners 에 저장하고, 쓴 크레딧도 알려 줘.

기다리기와 작업 상태

모든 생성은 서버 대기열을 거칩니다. 사람이 많으면 queued 로 차례를 기다리며, 상태에 순번·예상 시간이 붙습니다 — 자세히는 대기열과 동시 생성.

상태뜻
queued접수됨, 차례를 기다리는 중
running생성 중
done완료 — outputs 에 결과
failed실패 — error 에 이유, 크레딧은 정산(환불)
canceled취소됨 (예: 관리자가 생성을 멈춤)
  • CLI generate 는 기본 900초까지 기다립니다(--timeout). 넘으면 aimz jobs <id> --wait 로 이어서.
  • MCP generate 는 기본 300초(timeout_sec). 넘으면 job_status(job_id, wait=true).
  • 같은 요청이 두 번 접수되지 않게 요청마다 고유 키를 붙입니다 — 응답이 끊겨 다시 보내도 한 번만 실행됩니다.

크레딧

  • 생성을 접수할 때 예상 상한(credits_max)만큼 먼저 잡고, 끝나면 실제 사용량으로 정산합니다.
  • 실패한 생성은 정산되어 크레딧이 돌아옵니다.
  • 잔액은 aimz whoami, 충전은 aimzlabs.com 에서 합니다.
팁
여러 장을 묶어 관리하려면 --session 이름(MCP: session_id)을 같은 값으로 주세요. 라이브러리에서 한 묶음으로 보입니다.