409 Conflict 오류: 의미와 재시도해야 할 때
409 Conflict는 요청이 서버의 현재 상태와 충돌했다는 뜻입니다. 오류 코드를 읽고 다시 보낼지, Job을 기다릴지, 호출을 고칠지 정하세요.
개발자
Sume API로 개발할 때 필요한 글입니다. API 키와 호스트, 작업과 실행, 폴링, 웹훅, 멱등성, 오류와 요청 한도, SDK, CLI, MCP 인증을 다룹니다.
먼저 읽을 글: Sume API 빠른 시작: 다섯 단계로 첫 영상 생성 호출하기
API 키가 노출됐다면? 먼저 폐기하고 사용 내역 확인하기
노출된 API 키는 폐기하기 전까지 누구나 쓸 수 있습니다. 새 키로 교체하고 이전 키를 폐기한 뒤, 그 키의 최근 사용과 지출, 여러분의 Job을 확인하세요.
여러 사람이 같은 API 키를 써도 되나요?
쓸 수는 있지만, 그러면 키의 요청 한도와 사용 기록, 폐기까지 함께 나누게 됩니다. 사람이나 서비스마다 키를 따로 주고, 그래도 공유되는 것이 무엇인지 알아 두세요.
무료 웹훅 테스터: 코딩 전에 웹훅이 보내는 내용 보기
무료 웹훅 테스터는 공개 HTTPS URL을 주고, 들어온 요청마다 헤더와 본문을 보여 줍니다. Sume의 테스트 보내기(Send test)를 그 URL로 보내면 서명된 페이로드를 볼 수 있습니다.
Python으로 말하는 아바타 만들기: Sume API 활용
Python Requests로 말하는 아바타를 만드세요. 아바타를 생성하고 Job을 폴링한 뒤, 말할 스크립트를 보내고 완성된 영상의 URL을 읽습니다.
AI 이미지 대량 생성 API: 스크립트로 수백 장 만들기
행마다 이미지 요청을 하나씩 보내되, 요청마다 고유한 Idempotency-Key와 async 모드를 쓰고 호출당 최대 네 장을 요청하세요. 속도는 요금제의 동시성이 정합니다.
Python 이미지 생성 API: AI 이미지 생성하고 저장하기
Python에서 Requests로 이미지를 생성하세요. 이미지 API에 프롬프트를 POST하고, 200이면 URL을 읽고 202면 Job을 폴링한 뒤 파일을 하나씩 저장합니다.
Sume API 상태 값 정리: Job, 실행, 큐, 웹훅
Sume API 상태 값을 한곳에 모았습니다. Job, /v1/videos, Format·Agent 실행, 대량 실행 큐, 웹훅 전달, 사용량 행, 공유 권한, 잔액까지 다룹니다.
Sume API 오류 코드 총정리: 표면별 색인과 다음 조치
Sume API 오류 코드를 표면별로 정리했습니다. 공통 코드, 유료 생성, Format, Scheduled 실행, Agent Completions, 미디어 도구, 호스팅 MCP를 다룹니다.
Sume API 페이지네이션: cursor·starting_after·한도
Sume 목록 엔드포인트별 페이지 넘김 방식입니다. Format과 실행 목록은 cursor와 has_more, /v1/jobs는 starting_after를 쓰고, limit만 받는 목록에는 커서가 없습니다.
Sume API 헤더: 인증, 멱등성 키, If-Match, 요청 한도
Sume API가 읽거나 보내는 모든 HTTP 헤더를 정리했습니다. API 키, Content-Type, Idempotency-Key, If-Match, 요청 ID, 요청 한도, 웹훅 서명을 다룹니다.
Sume API 용어집: Format 실행, 지출 상한, 멱등성 키
Sume API 용어를 한두 문장씩 설명합니다. Format, 실행, Job, 지출 상한, 멱등성 키, 지갑, 에이전트 수수료, 웹훅, 아티팩트 등을 관련 글 링크와 함께 정리했습니다.
개발자용 AI 영상 생성 API 추천: 고르는 방법
모든 개발자에게 가장 알맞은 AI 영상 생성 API 하나는 없습니다. 과금 단위, 모델, API 구조, 한도를 비교한 뒤 돌려받을 결과물로 고르세요.
AI 생성 영상 URL은 만료되나요? Sume의 결과물 보관 방식
Format 실행과 Agent Completions에서는 만료되지 않습니다. Sume는 그 미디어를 만료되지 않는 media.sume.com URL로 돌려주며, 링크를 가진 누구나 열 수 있습니다.
Sume API에서 생성한 영상 다운로드하기: 401과 302
Sume의 unsigned_urls는 API 키가 필요하고 302 리다이렉트로 응답합니다. curl -L이나 코드로 MP4를 내려받고, 401, 404, 409를 각각 해결하세요.
웹훅 URL이 유효하지 않다고 거부되나요? Sume 웹훅 URL 규칙
웹훅 URL이 공개 HTTPS가 아니면 Sume는 400 invalid_request로 응답합니다. 스킴, 호스트, 포트, 자격 증명 규칙과 전달 시점의 검사를 정리했습니다.
Sume API 미디어 URL 규칙: 엔드포인트별 허용 URL
Sume 생성 엔드포인트는 공개 HTTPS 미디어 URL을 가져옵니다. 트림, 필터, 프레임, 검사, Timeline은 워크스페이스에 있는 media.sume.com URL만 받습니다.
Sume Job 타입과 동시성: 슬롯을 차지하는 호출
Sume 엔드포인트별 Job 타입과 슬롯 사용 여부입니다. 트림과 Timeline을 포함한 모든 생성 Job은 동시성 슬롯을 차지하고, 프레임과 검사는 차지하지 않습니다.
Sume API 엔드포인트 목록: 경로, 스코프, 멱등성
Sume API의 공개 경로를 계열별로 정리한 색인입니다. 키가 필요 없는 경로, 계열별 스코프, Idempotency-Key 적용 위치, 계열별 설명 글을 담았습니다.
Sume API 출력 파일 형식: MP4·PNG·WebP·WAV·MP3
Sume API 엔드포인트별로 반환하는 파일입니다. Timeline과 편집 도구는 MP4, 이미지는 PNG·JPEG·WebP, 오디오는 WAV나 MP3, 전사문은 JSON입니다.
브라우저에서 Sume API 호출 시 CORS 오류: 해결 방법
브라우저는 내 사이트에서 api.sume.com으로 직접 보내는 호출을 차단하며, API 키는 프론트엔드 코드에 절대 넣으면 안 됩니다. 서버에서 Sume를 호출해 프록시하세요.
Sume MCP 서버 OAuth 플로: 디스커버리·동의·PKCE·스코프
Sume 호스팅 MCP 서버는 자체 OAuth를 운영합니다. 401이 디스커버리 메타데이터를 가리키고, 사용자가 mcp.sume.com에서 동의하면 PKCE S256으로 한 시간짜리 토큰을 받습니다.
Sume MCP insufficient_scope·누락 도구·타임아웃 해결
Sume MCP의 insufficient_scope 오류는 OAuth 세션에 mcp:write가 없다는 뜻입니다. mcp_health부터 호출한 뒤 스코프, 누락된 도구, 타임아웃을 해결하세요.
Sume 에이전트 실행 오류: action_run_in_progress 등
스케줄 실행이 이미 진행 중인데 reject를 보내면 409 action_run_in_progress, ID가 내 Agent Completion 실행이 아니면 404 agent_run_not_found입니다.
CI와 헤드리스 서버에서 Sume CLI 실행하기
CI에서는 버전을 고정한 릴리스 바이너리, 시크릿 저장소의 SUME_API_KEY, 격리된 SUME_CONFIG_DIR, doctor 사전 점검, --json 출력으로 Sume CLI를 실행하세요.
Sume CLI 명령어 레퍼런스: 계정, Job, 에셋, skills
Sume CLI에는 생성 외에도 로그인과 계정, health·doctor 점검, 스키마 탐색, Job, 에셋, 배치 헬퍼, skills, 별칭 명령어가 있습니다.
Sume CLI가 안 될 때: 로그인·API 베이스·Job·미디어 해결법
Sume CLI가 안 될 때는 읽기 전용 점검 네 가지를 먼저 실행한 뒤, 키 누락, 잘못된 API 베이스, 끝나지 않은 Job, 거부된 미디어 URL 중 해당하는 원인을 고치세요.
영상 생성 모델 목록 API: GET /v1/videos/models
GET /v1/videos/models는 Sume의 모든 영상 모델을 해상도, 화면 비율, 길이, 프레임·레퍼런스 유형, 오디오 여부, 가격 SKU와 함께 보여 줍니다.
영상 생성 Job 상태 API 폴링하기: Sume의 /v1/jobs
terminal이 true일 때까지 GET /v1/jobs/{id}/status를 next_poll_after_seconds 간격으로 폴링하고, result_ready가 true면 /result를 읽으세요.
영상 생성 API 동기 vs 비동기: Sume의 네 가지 제출 모드
Sume의 제출 모드는 async, sync, subscribe, webhook입니다. sync와 subscribe는 최대 30초만 기다리므로, 영상은 async로 제출해 폴링하거나 웹훅을 받으세요.
Sume TypeScript SDK 빠른 시작: 설치·클라이언트·오류·재시도
@sume-com/sdk를 설치하고 createSumeClient로 클라이언트 하나를 만든 뒤, throw 대신 오류를 반환하는 타입 지정 오퍼레이션을 호출하세요. 재시도는 기본으로 들어 있습니다.
AI 영상 생성 Job은 왜 실패했나요? Job 오류 읽는 법
실패한 Sume Job에는 category, stage, retryable, public_reason, next_action이 담긴 공개 오류가 있습니다. 읽는 곳과 필드별로 할 일을 설명합니다.
TypeScript SDK에서 Sume Job·실행이 끝날 때까지 기다리기
waitForJob, waitForRun, subscribeFormatRun은 Sume Job이나 실행이 끝날 때까지 폴링합니다. 기본 타임아웃, throw하는 오류, 재시도를 정리했습니다.
Job 목록 API: 상태별 영상 Job 필터링과 잃어버린 ID 복구
GET /v1/jobs는 워크스페이스 Job을 최신순으로 페이지당 100개까지, status·type·run_id로 걸러 나열합니다. starting_after로 넘기고 idempotency_key로 매칭하세요.
Sume API 카탈로그: 사용 가능한 모델·엔드포인트·가격 조회
GET /v1/catalog는 Sume API 기능을 모델 ID, 호출 URL, 가용성, 런타임 준비 상태, 가격과 함께 나열합니다. API 키가 필요 없습니다.
Sume API OpenAPI 스펙: 다운로드·탐색·클라이언트 생성
api.sume.com/reference/json에서 Sume API의 라이브 OpenAPI 스펙을 내려받고, Swagger UI에서 살펴보고, TypeScript 외의 언어용 클라이언트를 생성하세요.
Sume 생성 Job과 Format·Action·Agent 실행의 차이
Sume Job은 /v1/jobs에서 추적하는 생성 요청 하나이고, 실행은 Format, 스케줄, Agent Completion이 시작한 에이전트 턴 하나입니다. ID, 웹훅, 대기 방법이 다릅니다.
Sume 웹훅이 도착하지 않나요? 전달·서명 디버깅 방법
Sume 웹훅이 도착하지 않으면 Job이나 실행의 webhook_delivery를 읽고, 테스트 전송으로 엔드포인트를 확인한 뒤, 실제 이벤트를 다시 보내세요.
AI 영상 생성은 얼마나 걸리나요? Sume Job, 실행, 한도
Sume 문서 기준 영상 Job 하나는 30초에서 몇 분, 롱폼 Format 실행은 15~30분이 걸립니다. 실행 단계와 멈춤 신호, 한도를 정리했습니다.
AI 영상 생성 API 진행 상황 업데이트: 푸시 스트림 없이
Sume에는 SSE나 WebSocket 진행 상황 스트림이 없습니다. Job 이벤트나 Format 실행의 phase 타임라인을 폴링하고, 아바타 장면 스틸을 보여 주되 ETA는 약속하지 마세요.
Sume API로 AI 영상 생성 Job이나 실행을 취소하는 방법
Sume 생성 Job은 생성이 시작되기 전에만 취소되고, Format·Action·Agent 실행 취소는 멱등입니다. 경로, 응답, 과금, 웹훅을 정리했습니다.
영상 생성 API 타임아웃: Sume 대기 상한, SDK 기본값, 만료
Sume의 sync 제출은 최대 30초, SDK 대기는 기본 10–20분을 기다리지만, 클라이언트 타임아웃은 Job을 절대 취소하지 않습니다. 모든 한도와 직접 정할 마감 시간을 정리했습니다.
영상 생성 API 400 오류: 지원되지 않는 파라미터와 해결법
POST /v1/videos 400 원인과 해결: invalid_request, unsupported_parameter(size·seed·provider.options), unsupported_capability.
Sume request_id·job_id·run_id: 저장하고 문의할 ID
Job이나 실행 ID를 저장하고, 웹훅은 job_id나 실행 봉투의 request_id로 중복을 제거하고, Sume 지원팀에는 req_ 요청 ID를 Job이나 실행 ID와 함께 알려 주세요.
Sume API 빠른 시작: 다섯 단계로 첫 영상 생성 호출하기
Sume API 키를 만들고, sume/auto로 POST /v1/videos 요청을 한 번 보낸 뒤, Job을 폴링하고 영상을 내려받으세요. 짧은 다섯 단계와 그다음 갈 곳을 정리했습니다.
Sume 개발자 대시보드: API 키·사용량·Job·결제·플레이그라운드
Sume 개발자 대시보드를 페이지별로 소개합니다. API 키 생성, Billing & subscription에서 크레딧 구매, Jobs·Usage 확인, 플레이그라운드에서 Avatar 시험을 다룹니다.
AI 영상 API 멱등성 키: 이중 과금 없이 재시도하기
멱등성 키를 쓰면 재시도한 생성 요청이 두 번째 유료 작업 대신 원래 실행이나 Job을 돌려줍니다. Sume의 Idempotency-Key가 API별로 어떻게 동작하는지 설명합니다.
무인 AI 에이전트 지출 상한: Sume가 실행별 지출을 제한하는 법
무인 에이전트에는 지출을 승인할 사람이 없어 Sume는 실행마다 생성 비용에 상한을 둡니다. Agent Completions에서는 필수이고, Format 실행은 최대 $500입니다.