무인 AI 에이전트 지출 상한: Sume가 실행별 지출을 제한하는 법

지출 상한은 무인 에이전트 실행 한 번이 생성에 쓸 수 있는 최대 금액입니다. Sume에서는 모든 Agent Completion이 generation_spend_cap_usd를 보내야 하고, 모든 Format 실행에는 유효 상한(Format 자체의 상한, 또는 플랫폼 최대치 $500 이하로 직접 정한 상한)이 있으며, 실행은 절대 그 상한을 넘어 쓸 수 없습니다.

아래 규칙은 2026-09-25에 확인한 Sume 문서 Format 호출하기 (영문), 오류와 비용 (영문), Agent Completions, MCP 도구와 게이트 페이지에서 가져왔습니다.

무인 에이전트에는 왜 지출 상한이 필요한가요?

에이전트 채팅에서는 대화형 지출 승인 프롬프트가 여러분을 보호합니다. 백엔드 호출자에게는 그런 프롬프트가 없습니다. Agent Completion은 도구를 쓰고 생성 지갑에 접근할 수 있는 무인 에이전트이므로, 상한이 그 프롬프트를 대신합니다.

API로 실행하는 Format도 마찬가지입니다. 채팅용으로 쓴 레시피는 사람의 승인을 기다리며 멈출 수 있지만, API에는 승인할 사람이 없습니다. 그래서 실행에는 그런 승인이 이미 허용됐다고 알려 주고, 실행은 지출 상한 안에서 유료 단계까지 계속 진행합니다.

Format 실행에 지출 상한은 어떻게 설정하나요?

POST /v1/formats/{handle}/{slug}/runs에 generation_spend_cap_usd를 보내세요. 모든 Format에는 자체 상한이 있으며, GET /v1/formats/…의 generation_spend_cap_usd_micros로 읽을 수 있습니다. 상한을 한 번도 지정하지 않은 Format은 플랫폼 기본값인 $400을 보고합니다. 프로덕션의 긴 영상 실행은 보통 $120 안팎의 상한으로 만들고, 장면 하나를 재시도하는 실행은 몇 달러 상한으로 만듭니다.

curl -sS -X POST "https://api.sume.com/v1/formats/acme/product-promo/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8823-promo-v1" \
  -d '{
    "input": { "product_url": "https://shop.example.com/p/8823" },
    "generation_spend_cap_usd": 120
  }'

Agent Completions에서는 지출 상한이 필수인가요?

네. Agent Completions에서 POST /v1/agent/completions의 generation_spend_cap_usd에는 기본값이 없어서, 생략하면 요청이 400 invalid_request로 실패합니다. 실행 한 번에 쓸 의향이 있는 최대 금액으로 설정하고, 크기는 API 요금의 계량 요율을 보고 정하세요.

실행이 상한에 도달하면 어떻게 되나요?

두 게이트가 서로 다른 시점에 적용됩니다. 상한을 넘어 쓰려던 Format 실행은 일반 코드인 format_run_failed로 끝나므로, 상한 때문에 멈췄는지 알려면 영수증의 usage.billable_amount_usd_micros와 usage.generation_spend_cap_usd_micros를 비교하세요.

• 취소나 실패 전에 끝난 생성은 과금되며, 이후 단계가 실패해도 환불되지 않습니다.
• 생성 시점의 4xx, 멱등 200 재전송, skipped 실행은 비용이 들지 않습니다.

상한은 무엇을 세고, 무엇을 빼나요?

상한은 API 요금의 요율로 계량되는 생성(영상, 이미지, 아바타, 음성, 타임라인 작업)을 제한합니다. 영수증은 이를 usage.billable_amount_usd_micros로 보고하며, 이 값은 실행이 진행되는 동안 올라가고, 예약된 금액과 확정된 금액을 모두 세며, 실행이 종료되면 정산됩니다.

에이전트 자체의 LLM 턴은 빠지므로 실행의 총비용이 아니며, 청구서가 아니라 영수증의 숫자입니다. 청구 기록은 GET /v1/usage와 GET /v1/balance입니다. 지출을 읽지 못하면 usage는 null이며, 이는 0과 다릅니다. 요금제와 지갑은 Sume 요금제는 어떻게 동작하나요에서 설명합니다.

호스팅 MCP 서버에서는 지출 한도가 어떻게 동작하나요?

호스팅 MCP 도구는 유료 호출마다 게이트를 둡니다. mcp:paid 스코프는 없으며, 지출은 지갑과 접수 단계에서 관리됩니다.

• 쓰기·유료 도구에는 idempotency_key가 필수입니다. 전송과 중복 제거를 위한 고정 키이며, 사람의 승인이 아닙니다.
• dry_run=true는 Job을 제출하지 않고 접수·비용 프리뷰를 돌려줍니다. 제출하려면 dry_run을 빼거나 false로 두고 다시 호출하세요.
• max_spend_usd는 선택 사항이며, 넘겼을 때만 강제됩니다.
• generation_admission_preview는 비싼 버스트 전에 쓰는 프리뷰입니다. 평범한 단일 생성에는 필요 없습니다.

{
  "idempotency_key": "avatar-create-2026-07-21-001",
  "dry_run": true,
  "max_spend_usd": 2,
  "payload": {
    "avatar_handle": "studio_presenter",
    "input": { "type": "prompt", "prompt": "A friendly studio presenter in neutral lighting" }
  }
}