개발자 문서

MCP · AI 에이전트

대기열과 동시 생성

수업처럼 여러 사람이 한꺼번에 생성해도 실패하지 않도록, 모든 생성은 서버 대기열을 거칩니다. 몰리면 실패 대신 차례를 기다립니다.

왜 기다리나요

동시에 실제로 만들 수 있는 수에는 두 가지 한도가 있습니다.

  • 서버 실행 칸 — 서버가 동시에 돌리는 생성 작업 수.
  • 공급사 동시 실행 칸 — 모델을 제공하는 회사(공급사)의 API 키마다 정해진 동시 작업 수. 영상 모델은 특히 적습니다.

한도를 넘는 작업은 실패하지 않고 대기열에서 차례를 기다립니다. 공급사 칸이 꽉 차 시작하지 못한 작업도 실패 처리하지 않고,공급사를 부르기 전 상태 그대로 대기열로 돌아가 다시 시도합니다. 그래서 크레딧이 두 번 나가지 않습니다.

차례를 정하는 규칙

규칙내용
공정 배분지금 실행 중인 작업이 가장 적은 사람의 작업부터 — 한 사람이 20개를 넣어도 나중에 온 학생이 바로 다음 차례를 받습니다
한 사람 몫한 사람은 실행 칸의 약 3/4까지만 동시에 씁니다. 나머지는 다른 사람 몫으로 남깁니다
한 모델 몫한 모델은 실행 칸의 절반까지 먼저 씁니다. 다른 모델 작업이 없으면 나머지도 씁니다
공급사 칸이 꽉 찬 모델그 모델만 잠시(몇 초~30초) 쉬고 다른 모델은 계속 돕니다. 그 모델 작업이 하나 끝나면 기다리던 것 하나가 바로 들어갑니다
순서 유지다시 시도하는 작업은 처음 접수한 시각을 그대로 갖고 있어 새 작업에 밀리지 않습니다

한도

항목기본값넘으면
한 사람이 줄 세울 수 있는 작업(대기+진행)30개429 + Retry-After — 몇 개 끝난 뒤 다시 넣습니다 (CLI·MCP 가 잠시 자동으로 기다렸다 다시 보냄)
대기 최대 시간60분크레딧 차감 없이 취소
잔액 확인이번 작업 + 대기 중인 내 작업 예상액422 “대기 중인 생성까지 합치면 크레딧이 부족합니다”
생성 요청 속도분당 30회(관리자 제외)429

실제 값은 서버 설정에 따라 다를 수 있습니다. queue_status(CLI: aimz queue)가 지금 값을 알려 줍니다.

참고
서버가 다시 시작돼도 대기 중이던 작업은 이어서 진행됩니다. 참고 영상이 붙은 작업만 예외로, 과금 근거를 다시 알 수 없어 크레딧 차감 없이 취소됩니다.

대기 정보 읽기

작업 상태(job_status, aimz jobs <id>)에 queue 정보가 붙습니다.

queue (대기 중)
{
  "state": "queued",
  "position": 3,            // 내 앞에 2개
  "ahead": 2,
  "waiting_for": "capacity", // turn: 차례 대기 · capacity: 공급사 칸이 꽉 참 · user_limit: 내 다른 작업이 먼저
  "retries": 1,             // 공급사 칸이 없어 다시 줄 선 횟수
  "eta_sec": 85,            // 대략 예상 (최근 소요 시간 기준)
  "waited_sec": 40
}

실행 중이면 {"state": "running", "running_sec": 12, "eta_sec": 18} 처럼 나옵니다. 예상 시간은 최근 실제 소요 시간으로 계산한 대략값입니다.

에이전트는 이렇게 조율합니다

  1. 큰 작업 전에 queue_status — 실행 칸·대기 수·새 작업 예상 시작 시간을 보고 사용자에게 알립니다.
  2. 여러 개는 generate_batch — 한 번 승인으로 최대 20개를 접수합니다. generate 를 병렬로 여러 번 부르지 않습니다.
  3. 결과는 wait_jobs — 여러 작업을 함께 기다립니다. 서버에 묻는 간격은 예상 시간에 맞춰 자동으로 늘었다 줄었다 합니다.
  4. 시간 안에 안 끝나도 다시 접수하지 않습니다 — 다시 넣으면 크레딧이 두 번 듭니다. wait_jobs 로 이어서 기다립니다.
에이전트에게
지금 대기열 상황 보고, 제품 사진 배경 8가지 버전을 한 번에 만들어 줘.
오래 걸리면 예상 시간 알려 주고, 끝나면 ./out 에 저장해.

CLI 로

터미널
aimz queue                                  # 실행 칸·대기 수·내 작업 순번
aimz batch jobs.json --wait -o ./out        # 여러 개를 한 번 승인으로 (JSON 배열)
aimz wait j_3a31… j_8f02… -o ./out          # 여러 작업 함께 기다리기
jobs.json
[
  {"model_id": "nanobanana", "params": {"prompt": "한옥 마당의 고양이", "aspect_ratio": "16:9"}},
  {"model_id": "nanobanana", "params": {"prompt": "한옥 마당의 강아지", "aspect_ratio": "16:9"}},
  {"model_id": "gpt-4.1-mini", "params": {"prompt": "두 그림에 어울리는 제목 3개"}}
]

수업에서 쓸 때

영상은 미리 예상 시간을 보세요

대기 시간 ≈ (내 앞 작업 수 ÷ 동시 실행 수) × 작업 하나 시간. 이미지(10~20초)는 한 반이 1분 안팎이지만, 영상(1~3분)은 30명이 한꺼번에 넣으면 마지막 학생이 몇 분을 기다릴 수 있습니다. 실패가 아니라 차례를 기다리는 것이니 다시 누르지 않도록 안내해 주세요.

한 명이 많이 넣어도 괜찮습니다

공정 배분 덕분에 한 학생이 일괄로 여러 개를 넣어도 다른 학생의 첫 작업이 먼저 시작됩니다.