개발자
Sume API로 개발할 때 필요한 글입니다. API 키와 호스트, 작업과 실행, 폴링, 웹훅, 멱등성, 오류와 요청 한도, SDK, CLI, MCP 인증을 다룹니다.
fal.ai와 Replicate 대안: AI 영상 생성 API 비교
AI 영상 생성에서 fal.ai와 Replicate의 대안인 Kling·Runway API, Higgsfield, Sume를 가격 단위, 모델, API 형태, 한도로 비교합니다.
로컬 vs 원격 MCP 서버 차이: stdio와 Streamable HTTP
로컬 MCP 서버는 여러분의 컴퓨터에서 실행되어 stdio로 통신하고, 원격 MCP 서버는 다른 곳에서 실행되며 Streamable HTTP로 URL에 접속합니다. 고르는 방법을 정리합니다.
MCP SSE vs Streamable HTTP 차이: 무엇을 써야 하나요?
SSE는 지원 중단된 MCP의 이전 HTTP 트랜스포트이고, Streamable HTTP는 모든 메시지를 POST로 받는 단일 엔드포인트로 이를 대체했습니다. 무엇을 고를지 정리합니다.
MCP 도구 vs 리소스 vs 프롬프트: 각각 누가 제어하나요?
MCP 도구는 모델이 호출하고, 리소스는 앱이 첨부하며, 프롬프트는 사용자가 고릅니다. 각각의 용도와 고르는 방법을 정리합니다.
MCP 서버 테스트 방법: Inspector, Postman, curl
MCP 서버는 MCP Inspector로 테스트합니다. 연결하고, 로그인하거나 인증 헤더를 넣고, 도구 목록을 본 뒤 읽기 전용 도구를 호출하세요. Postman과 curl로도 됩니다.
MCP 오류 코드: -32601, -32602, -32001의 의미
MCP 오류 코드는 JSON-RPC 코드입니다. -32700부터 -32603까지의 의미, -32001이 클라이언트 쪽 타임아웃인 이유, 실패한 도구 호출과의 차이를 정리합니다.
Stateless MCP 서버: 세션·Mcp-Session-Id·핸들
Stateless MCP 서버는 요청 사이에 세션을 유지하지 않습니다. Mcp-Session-Id의 역할, 2026-07-28 개정판이 없앤 것, 상태를 대신 어디에 두는지 정리합니다.
MCP JSON 설정 파일: mcp.json 구조와 클라이언트별 차이
MCP JSON 설정은 서버를 이름별로 나열합니다. 로컬 서버에는 명령어를, 원격 서버에는 URL과 헤더를 적습니다. 클라이언트마다 키 이름이 다른 이유도 정리합니다.
MCP 도구 호출 결과 구조: content와 structuredContent
MCP 도구 호출 결과에는 content 배열, 선택 필드 structuredContent, isError가 있습니다. 각 필드의 내용과 이미지 전달 방식, 오류의 모습을 정리합니다.
MCP 도구 설명(description): 쓸 내용과 길이 제한
MCP 도구 설명은 모델이 도구를 고르고 호출할 때 읽는 텍스트입니다. 명세의 규정, Claude Code가 설명을 자르는 지점, 무엇을 써야 하는지 정리합니다.
텍스트로 SRT 자막 파일 만드는 방법: TTS로 타이밍 잡기
SRT 파일에는 줄마다 시작 시각과 끝 시각이 필요합니다. 텍스트를 TTS로 읽히면서 단어별 타이밍을 받고, 타이밍이 붙은 문장마다 번호 블록으로 쓰세요.
Java 음성 인식 API: HttpClient로 오디오를 텍스트로
JDK HttpClient와 Jackson으로 Java에서 음성 인식 API를 호출하세요. 오디오 URL을 POST하고 Job을 폴링한 뒤, 전사문과 단어별 시간을 읽습니다.
curl Bearer 토큰: Authorization 헤더 보내는 법
curl에서 bearer 토큰은 $TOKEN이 확장되도록 큰따옴표로 감싼 Authorization: Bearer 헤더나 --oauth2-bearer로 보내세요. 401별 해결법도 담았습니다.
Retry-After 헤더: 429·503 후 얼마나 기다려야 하나요?
Retry-After는 재시도 전에 얼마나 기다릴지 클라이언트에 알려 주는 헤더로, 초 단위 숫자나 HTTP 날짜이며 429나 503과 함께 옵니다. 읽는 법과 대응 방법을 정리했습니다.
API가 404 Not Found를 반환하는 이유와 해결법
API는 경로나 메서드에 맞는 라우트가 없을 때, 또는 보낸 자격 증명으로는 그 ID가 없을 때 404를 반환합니다. 둘을 구별하고 각각 고치는 법을 알아보세요.
재시도 가능한 HTTP 상태 코드: 어떤 오류를 재시도해야 하나요?
네트워크 오류, 408, 429, 5xx는 백오프하며 재시도하고, 그 밖의 4xx는 대부분 재시도하지 마세요. POST는 멱등성 키가 있을 때만 재시도하고, API의 재시도 플래그를 읽으세요.
POST는 멱등한가요? 아니요, PUT과 DELETE는 멱등합니다
아니요, HTTP는 GET, HEAD, OPTIONS, TRACE, PUT, DELETE를 멱등하다고 정의하지만 POST와 PATCH는 아닙니다. 멱등성 키가 있으면 POST 재시도가 안전합니다.
웹훅과 API의 차이는 무엇인가요?
API 호출은 코드가 서버에 무언가를 요청하는 것이고, 웹훅은 어떤 일이 일어났을 때 서버가 내 URL을 호출하는 것입니다. 둘은 함께 동작합니다.
롱 폴링과 숏 폴링의 차이는 무엇인가요?
숏 폴링은 타이머에 맞춰 요청하고 즉시 답을 받습니다. 롱 폴링은 새 소식이 생기거나 타임아웃이 될 때까지 요청을 열어 두었다가 응답을 받으면 다시 요청합니다.
Bearer 토큰과 API 키의 차이는 무엇인가요?
API 키는 자격 증명의 한 종류이고, Bearer는 Authorization 헤더에 자격 증명을 담아 보내는 방식입니다. OAuth 토큰처럼 API 키도 bearer 토큰으로 보낼 수 있습니다.
API 키는 어디에 저장해야 하나요? 서버·CI·로컬 개발
API 키는 서버 쪽에만 두세요. 프로덕션은 시크릿 매니저로 채우는 환경 변수, 파이프라인은 CI의 시크릿 저장소, 노트북은 git이 무시하는 파일에 둡니다.
웹훅 보안 모범 사례: 수신기 체크리스트
HTTPS로만 받고, 원본 본문의 HMAC을 상수 시간으로 검증하고, 오래된 타임스탬프는 거부하고, 이벤트 ID로 중복을 제거하고, 2xx로 빠르게 응답하세요.
HMAC과 디지털 서명의 차이: 웹훅에서 각각 무엇을 증명하나요?
HMAC은 송신자가 공유 시크릿을 가졌음을 증명합니다. 디지털 서명은 개인 키로 만들고 공개 키로 확인하며, 부인 방지까지 더합니다.
cron 표현식 6자리: 맨 앞이 초인가요, 맨 끝이 연도인가요?
표준 cron은 필드가 5개입니다. 6자리 cron 표현식은 맨 앞에 초를 더하거나(Spring, Quartz, Azure Functions) 맨 끝에 연도를 더합니다(AWS).
FFmpeg 영상 자르기: 시간 지정과 재인코딩 여부
FFmpeg에서 영상을 자르려면 -i 앞의 -ss로 탐색하고 -t로 길이를 정하세요. -c copy를 쓰면 재인코딩을 건너뛰지만, 컷이 시작 지점 앞의 키프레임에서 시작합니다.
FFmpeg height not divisible by 2 오류 원인과 해결
yuv420p 인코딩에 홀수 높이(또는 너비)가 들어갔다는 오류입니다. -2로 스케일하거나 trunc(ih/2)*2로 내림해 두 변을 짝수로 만드세요. Sume가 크기를 맞추는 방식도 다룹니다.
yuv420p10le vs yuv420p 차이: 8비트와 10비트 픽셀 포맷
yuv420p와 yuv420p10le는 둘 다 planar YUV 4:2:0입니다. yuv420p는 샘플당 8비트를, yuv420p10le는 10비트를 16비트 워드에 리틀 엔디언으로 저장합니다.
Faststart MP4: moov atom을 파일 앞으로 옮기는 방법
faststart MP4는 인덱스인 moov atom이 파일 앞부분에 있는 MP4입니다. FFmpeg는 -movflags +faststart를 주면 두 번째 패스에서 인덱스를 앞으로 옮깁니다.
FFmpeg로 영상에서 오디오 추출하기: 복사, MP3, WAV
FFmpeg로 영상에서 오디오를 추출하려면 -vn으로 화면을 빼고, -c:a copy로 오디오를 그대로 두거나 인코더로 WAV나 MP3를 쓰세요.
FFmpeg로 영상에서 프레임 추출하기: 한 장, 매초, 전체
FFmpeg로 프레임을 추출할 때 -frames:v 1은 이미지 한 장을, -r 1은 초당 한 장을 저장하고, 번호를 붙인 파일 패턴은 모든 프레임을 씁니다.
FFmpeg로 영상 합치기: concat 디먹서 vs concat 필터
FFmpeg로 영상을 이어 붙일 때 설정이 같은 파일은 concat 디먹서와 -c copy로 재인코딩 없이 잇고, 서로 다른 클립은 concat 필터로 재인코딩해 잇습니다.
FFmpeg로 오디오와 영상 합치기: -map, copy, -shortest
FFmpeg로 오디오와 영상을 합치려면 한 파일에서는 영상을, 다른 파일에서는 오디오를 매핑하고, 영상은 복사하고, -shortest로 길이를 맞추세요.
Text to Image API: 프롬프트 보내고 이미지 URL 받기
Text-to-image API는 HTTPS로 보낸 프롬프트를 생성된 이미지로 바꿉니다. 요청과 응답, 오래 걸리는 Job, 비용까지 호출 방법을 정리했습니다.
AI 이미지 생성은 얼마나 걸리나요?
Sume에서는 대부분의 AI 이미지가 API가 요청을 열어 두는 30초 안에 완성됩니다. 무엇이 시간을 늘리는지, 느린 이미지와 멈춘 이미지를 어떻게 구분하는지 알아보세요.
MCP 도구 어노테이션: readOnlyHint와 클라이언트 활용법
MCP 도구 어노테이션은 readOnlyHint 같은 선택적 힌트입니다. 각 힌트의 의미와 기본값, 그리고 ChatGPT·VS Code·Copilot이 이를 쓰는 방식을 정리합니다.
Claude Code에서 MCP 서버 인증이 필요할 때 해결법
Claude Code는 해결하지 못한 401이나 403을 받은 MCP 서버를 인증 필요로 표시합니다. 다시 로그인하는 방법과 API 키가 더 알맞은 경우를 정리했습니다.
단어 하이라이트 TTS: 단어별 타이밍을 재생에 동기화하기
TTS 재생에 맞춰 단어를 강조하세요. 오디오와 함께 단어별 타임스탬프를 받고, 플레이어의 현재 시간이 시간 범위 안에 드는 단어를 표시합니다.
Python TTS API: 요청, 폴링, MP3 저장하기
Python에서 Requests로 텍스트 음성 변환 API를 호출하세요. 텍스트와 음성을 POST하고 Job을 폴링한 뒤 MP3를 저장하는 Sume TTS 1.0 전체 스크립트입니다.
JavaScript TTS API: Node.js에서 MP3로 저장하기
서버의 JavaScript 코드에서 텍스트 음성 변환(TTS) API를 호출하세요. Node.js에서 Sume SDK로 텍스트를 제출하고, Job을 기다린 뒤 MP3를 저장합니다.
일괄 전사 API: 여러 오디오 파일을 텍스트로 변환하기
API 일괄 전사는 파일마다 음성 인식 Job을 하나씩 보내는 루프입니다. 키는 파일 ID로 만들고, 결과는 웹훅이나 폴링으로 모읍니다. Sume에서 동작하는 방식을 설명합니다.
Python 음성 인식(STT): 오디오를 타임스탬프와 함께 텍스트로
Python에서 Requests로 음성을 텍스트로 변환하세요. 오디오 URL을 보내고 Job을 폴링한 뒤 전사문과 단어별 타임스탬프를 읽는 Sume STT 1.0 스크립트입니다.
JavaScript 음성 인식 API: Node.js에서 오디오를 텍스트로
서버의 JavaScript 코드에서 음성 인식 API를 호출하세요. Node.js에서 Sume SDK로 오디오 파일 URL을 보내고, Job을 기다린 뒤 텍스트를 읽습니다.
AI 영상 생성을 코드로 자동화하는 방법
AI 영상 생성을 자동화하려면 잘 나오는 브리프를 레시피로 저장하고, 이벤트·목록·스케줄에 맞춰 코드에서 시작한 뒤, 완성된 영상은 웹훅으로 받으세요.
API 키가 노출됐다면? 먼저 폐기하고 사용 내역 확인하기
노출된 API 키는 폐기하기 전까지 누구나 쓸 수 있습니다. 새 키로 교체하고 이전 키를 폐기한 뒤, 그 키의 최근 사용과 지출, 여러분의 Job을 확인하세요.
여러 사람이 같은 API 키를 써도 되나요?
쓸 수는 있지만, 그러면 키의 요청 한도와 사용 기록, 폐기까지 함께 나누게 됩니다. 사람이나 서비스마다 키를 따로 주고, 그래도 공유되는 것이 무엇인지 알아 두세요.
무료 웹훅 테스터: 코딩 전에 웹훅이 보내는 내용 보기
무료 웹훅 테스터는 공개 HTTPS URL을 주고, 들어온 요청마다 헤더와 본문을 보여 줍니다. Sume의 테스트 보내기(Send test)를 그 URL로 보내면 서명된 페이로드를 볼 수 있습니다.
Python으로 말하는 아바타 만들기: Sume API 활용
Python Requests로 말하는 아바타를 만드세요. 아바타를 생성하고 Job을 폴링한 뒤, 말할 스크립트를 보내고 완성된 영상의 URL을 읽습니다.
AI 이미지 대량 생성 API: 스크립트로 수백 장 만들기
행마다 이미지 요청을 하나씩 보내되, 요청마다 고유한 Idempotency-Key와 async 모드를 쓰고 호출당 최대 네 장을 요청하세요. 속도는 요금제의 동시성이 정합니다.