AI 이미지 대량 생성 API: 스크립트로 수백 장 만들기

스크립트로 이미지를 대량 생성하는 일은 루프입니다. 목록의 행마다 이미지 요청을 하나씩 보내고, 행마다 자체 프롬프트를 씁니다. Sume에서는 각 행을 고유한 Idempotency-Key와 mode: "async"를 담아 POST /v1/images로 보내고, 호출당 최대 네 장을 요청한 뒤, Job이 끝나는 대로 결과를 모으세요. 한 번에 몇 개가 실행될지는 워크스페이스의 동시성 한도가 정하며, 나머지는 큐에서 기다립니다.

아래 Sume 관련 사실은 Image API (영문), Generation admission, Job과 결과 (영문) 문서에서 가져왔으며, 2026-09-27에 확인했습니다.

프롬프트 목록으로 이미지를 대량 생성하려면 어떻게 하나요?

prompt는 요청당 문자열 하나이므로 행마다 별도의 호출이 됩니다. 행마다 다음과 같이 하세요.

• Idempotency-Key는 catalog-v1-sku-4411처럼 행에서 만드세요. 같은 키와 본문으로 재시도하면 두 번째 Job을 과금하는 대신 원래 Job이 반환되고, 같은 키에 다른 페이로드를 보내면 409 idempotency_conflict가 됩니다.
• mode: "async"를 보내세요. 그러면 제출은 요청을 최대 30초 동안 열어 두는 대신, Job 봉투와 함께 곧바로 202로 응답합니다.
• Job ID를 행 옆에 저장하세요. GET /v1/jobs/{id}/status를 백오프하며 폴링한 뒤 GET /v1/jobs/{id}/result에서 이미지를 가져오거나, webhook_url과 함께 mode: "webhook"을 보내 Job마다 종료 콜백을 한 번 받으세요.
• 본문 형태가 아니라 상태 코드로 분기하세요. 200은 이미지 응답이고 202는 Job 봉투입니다.
• 보관할 파일은 내려받으세요. Image API 결과 URL은 Sume가 호스팅하는 서명된 URL입니다.

import os, requests

API = "https://api.sume.com/v1/images"
KEY = os.environ["SUME_API_KEY"]
rows = [
    {"id": "sku-4411", "prompt": "a matte black bottle on marble, studio light"},
    {"id": "sku-4412", "prompt": "a jar of honey on an oak table, soft light"},
]

jobs, done = {}, {}
for row in rows:
    r = requests.post(
        API,
        headers={"Authorization": f"Bearer {KEY}",
                 "Idempotency-Key": f"catalog-v1-{row['id']}"},
        json={"model": "bytedance-seed/seedream-4.5", "prompt": row["prompt"],
              "n": 2, "mode": "async"},
        timeout=60,
    )
    r.raise_for_status()
    body = r.json()
    if r.status_code == 200:  # the image response
        done[row["id"]] = [image["url"] for image in body["data"]]
    else:  # 202: the job envelope
        jobs[row["id"]] = body["data"]["job"]["id"]

요청 하나로 이미지를 몇 장까지 받을 수 있나요?

n은 요청당 이미지 수를 정합니다. 문서는 호출당 최대 10장을 허용하면서 모델별 상한은 그보다 낮다고 설명하며, 현재 코드에서는 대부분의 모델이 4장, Grok Imagine(x-ai/grok-image)이 1장입니다. 큰 n은 30초 대기를 넘기기 가장 쉬운 설정 중 하나이기도 하므로, 비동기로 제출할 이유가 하나 더 생깁니다. 모델별 설정은 4K, 품질, 이미지 수를 참고하세요.

이미지 Job은 한 번에 몇 개까지 실행되나요?

워크스페이스의 생성 동시성 한도만큼 실행되며, 이 한도는 요금제가 정합니다. 현재 코드에서 POST /v1/images는 호출마다 image_generation Job을 하나 만들고, 유료 생성 Job은 큐 우선(queue-first) 방식으로 접수됩니다. 한도를 넘은 Job은 queued 상태로 기다리며, 제출이 429 queue_full로 실패하는 것은 큐까지 가득 찼을 때뿐입니다. 요금제별 수치와 전체 접수 규칙은 영상 Job 동시성과 큐에 있습니다. 일괄 스크립트에서는 다음을 지키세요.

• 각 제출 묶음(wave)의 크기는 실시간 generation_limits 스냅샷으로 정하세요. Sume가 계산할 수 있을 때 생성 제출 응답에 이 스냅샷이 담깁니다. 새로 진행할 작업의 예산은 max(0, concurrency_limit - active_generation_jobs - queued_generation_jobs)이며, queue_capacity_remaining을 넘지 않아야 합니다.
• 읽기와 쓰기는 분당 예산이 따로 있으므로, 폴링이 제출에 필요한 예산을 써 버리지 않습니다. retry-after에 따라 백오프하세요.

요청이 실패하거나 스크립트가 멈추면 어떻게 되나요?

스크립트를 다시 실행하세요. 이미 제출한 행은 같은 키로 원래 Job을 돌려받으며, 두 번 과금되는 것은 없습니다. 실패하거나 취소된 생성은 과금되지 않지만 원래 Job이 계속 그 키에 응답하므로, 실패한 행을 다시 만들려면 버전을 올리는 식으로 새 키를 주세요. 각 행에 무슨 일이 있었는지는 제출 응답 자체가 알려 줍니다.

이미지 대량 생성 비용은 얼마인가요?

일괄 처리 비용은 이미지당 가격 × n × 행 수이며, 기본적으로 5.5% 에이전트 수수료가 더해집니다. ChatGPT Image 모델에서는 이미지당 가격이 크기와 quality에 따라서도 달라집니다. Sume는 제출을 수락할 때 Job마다 예상 금액을 예약하므로 잔액은 큐에서 대기 중인 Job까지 감당해야 하며, 실패한 Job의 예약은 해제되거나 환불됩니다. 모델별 가격은 AI 이미지 생성 API 비용에 있습니다.

각 이미지를 모델 호출 한 번이 아니라 저장된 Format으로 만든다면, Format 대량 요청 하나로 실행을 1개에서 100개까지 큐에 넣을 수 있습니다. Format 대량 실행을 참고하세요.