Sume Format 대량 실행: 요청 한 번에 렌더 100개까지

Sume Format 대량 실행은 일반 Format 실행을 담는 서버 측 큐입니다. POST …/bulk-runs 요청 하나에 최대 100개 항목을 담을 수 있고, 각 항목은 단일 실행과 같은 본문이며 여전히 샌드박스 하나, 에이전트 턴 하나, 실행 영수증 하나입니다. Sume는 목록을 모두 처리할 때까지 그중 concurrency개(1–16)를 동시에 진행합니다.

아래 내용은 2026-09-25에 확인한 Sume 문서 대량 실행과 Format 호출하기 (영문) 페이지에서 가져왔습니다.

대량 실행 큐는 어떻게 만드나요?

formats:write 스코프가 있는 API 키로 POST /v1/formats/{handle}/{slug}/bulk-runs를 보내세요. 짝을 이루는 불투명 경로 POST /v1/formats/{format_id}/bulk-runs도 같은 본문을 받고 같은 영수증을 돌려줍니다. 생성 요청이 수락되면 format.run_queue 객체와 함께 202로 응답합니다. 단일 Format 실행이 처음이라면 Sume Format이란?부터 읽어 보세요.

• concurrency: 필수 정수, 1–16. 동시에 진행할 자식 실행 수입니다.
• items: 필수 배열, 순서대로 나열한 항목 1–100개. 각 항목은 일반 실행 요청 본문 (영문)이므로 항목마다 output_schema, generation_spend_cap_usd, communication.webhook_url을 따로 담을 수 있습니다.
• 각 항목에는 instruction, input, previous_run_id, attachments 중 하나 이상이 있어야 합니다. 잘못된 항목이 하나만 있어도 큐가 생기기 전에 생성 요청이 400 invalid_request와 details.index로 실패합니다.
• 알 수 없는 최상위 필드는 거절되며, items 없이 보낸 { "concurrency": 3 }은 빈 큐가 아니라 400입니다.

curl -sS -X POST "https://api.sume.com/v1/formats/acme/product-promo/bulk-runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: spring-catalog-batch-1" \
  -d '{
    "concurrency": 3,
    "items": [
      { "instruction": "clip 1", "input": { "url": "https://example.com/1.jpg" } },
      { "instruction": "clip 2", "input": { "url": "https://example.com/2.jpg" } },
      { "instruction": "clip 3", "input": { "url": "https://example.com/3.jpg" } },
      { "instruction": "clip 4", "input": { "url": "https://example.com/4.jpg" } }
    ]
  }'

동시성 창은 어떻게 동작하나요?

팬아웃은 클라이언트가 아니라 서버가 진행합니다. 생성 요청이 이미 창을 채웁니다. concurrency: 3에 항목이 8개면 202 영수증에는 running 세 개와 queued 다섯 개가 보입니다. 자식이 완료되거나 실패하거나 취소되면 그 슬롯이 비고, 큐에 있던 다음 항목이 즉시 시작됩니다. 창은 절대 concurrency를 넘지 않습니다.

자식 실행도 일반 Format 실행의 접수 검사(지갑, 워크스페이스 생성 동시성, 지출 상한)를 그대로 거칩니다. 시작하지 못한 자식은 failed 항목이 되고, 창은 남은 대기 항목으로 다시 채워집니다. 이때 생성 요청은 이미 202를 반환한 뒤입니다. 모든 항목은 on_active_run: "allow"로 실행되므로, 항목에 skip이나 reject를 넣어도 창이 멈추지 않습니다.

큐 진행 상황은 어떻게 확인하나요?

formats:read 스코프가 있는 키로 큐의 status_url, 즉 GET /v1/format-run-queues/{queue_id}를 폴링하세요. 생성 때와 같은 객체가 돌아옵니다. 큐 status, counts(total, queued, running, completed, failed, canceled), 그리고 제출한 항목마다 index, status, run_id, error를 담은 items 행이 하나씩 들어 있습니다.

• 큐의 completed는 모두 성공했다는 뜻이 아니라 모든 항목이 종료됐다는 뜻입니다. counts.failed와 counts.canceled로 분기하세요.
• 자식 실행이 실패하거나 취소되면 그 항목의 error에는 format_run_failed나 format_run_canceled만 담깁니다. 이유는 GET /v1/format-runs/{run_id}에서 자식 실행의 영수증을 읽어 확인하세요.
• 폴링 사이에는 백오프하세요. Format이 영상을 만든다면 자식 하나도 몇 분짜리 작업이고, 폴링은 읽기 예산을 씁니다. 폴링 중의 429나 503은 일시적이며, 큐는 계속 동작합니다.

배치 전체에 대한 웹훅이 있나요?

없습니다. 큐 객체에는 웹훅이 없고, 큐 단위 콜백도 없습니다. 항목마다 communication.webhook_url을 설정하면 완료되거나 실패한 자식이 각자 서명된 format.run.terminal POST를 보냅니다. 이 내용은 Sume Format 실행 수명주기에서 다룹니다. 그렇지 않다면 큐의 status_url을 폴링하세요.

큐 목록이나 큐 취소를 위한 공개 엔드포인트도 없습니다. 자식 하나를 취소하려면 POST /v1/format-runs/{run_id}/cancel을 쓰세요. 그 항목이 canceled로 표시되고, 슬롯은 큐에 있던 다음 항목으로 넘어갑니다.

같은 배치를 두 번 보내면 어떻게 되나요?

생성 요청에 Idempotency-Key를 보내세요. 키의 범위는 Format 하나입니다. 같은 키에 같은 { concurrency, items }를 보내면 두 번째 큐가 생기지 않고 기존 큐와 함께 202가 돌아옵니다. 같은 키에 다른 페이로드를 보내면 409 idempotency_conflict이며, details.queue_id가 원래 큐를 가리킵니다. 단일 실행과 달리 대량 실행 재전송은 202 그대로이고 idempotency_hit 필드도 없으니, 새 배치마다 새 키를 만드세요. 키 설계는 AI 영상 API 멱등성 키에서 더 다룹니다.

대량 실행 큐에는 어떤 한도가 있나요?

• 요청당 항목은 최대 100개이고, 큐당 동시에 진행하는 자식 실행은 최대 16개입니다.
• 워크스페이스 생성 동시성, 지갑, 항목별 지출 상한은 모든 자식에 그대로 적용됩니다.
• 큐 단위 웹훅, 큐 목록 엔드포인트, 큐 취소 엔드포인트는 없습니다.
• 생성 요청은 쓰기 예산을 씁니다. 폴링은 읽기 예산을 쓰며, 읽기 예산은 쓰기 예산의 마흔 배입니다.
• 서비스 계정 키로는 대량 실행 큐를 만들 수 없고, 팀 Format에는 그 팀 워크스페이스에서 발급한 키가 필요합니다.
• 알 수 없는 큐 ID나 다른 소유자의 큐를 요청하면 404 format_run_queue_not_found로 응답합니다.