API 및 MCP 문서

무료 API는 브라우저 도구와 별개의 클라우드 기능입니다. Google로 로그인하고 Google이 확인한 @gmail.com 계정으로 Turnstile을 통과하면, 카드 없이 UTC 기준 매월 500 credits를 받을 수 있습니다. 단, 월 $20 무료 연산 예산의 적용을 받습니다.

활성화한 뒤 계정 설정 페이지에서 API 키를 만드세요. 같은 계정의 모든 키는 동일한 credit 풀, 속도 제한, 미완료 작업 한도를 공유합니다. 무료 연산 예산이 소진되면 새 무료 작업은 표시된 초기화 시간까지 일시 중지되며, 유료 Developer 작업과 브라우저 로컬 압축은 별도로 계속됩니다.

GIF 파일과 JSON이 담긴 options 필드를 포함한 multipart 요청을 보내세요. 목표 용량 모드는 targetBytes에 10진수 바이트 값을 사용합니다. mode 또는 targetBytes를 별도의 폼 필드로 보내지 마세요.

모든 생성 요청에는 계정 범위의 Idempotency-Key가 필요합니다. 같은 키에 같은 파일과 옵션을 사용하면 크레딧을 다시 예약하지 않고 원래 작업을 반환합니다.

생성 응답에는 최상위 id가 포함됩니다. JOB_ID로 저장하고 상태 URL에 사용하세요. job 속성 안에 들어 있지 않습니다. 생성 응답만으로는 다운로드 링크가 제공되지 않습니다. 이미 완료된 작업이 멱등 재전송으로 반환되더라도 상태 엔드포인트를 조회하세요. 예시의 YOUR_JOB_ID를 해당 id로 바꾸고, succeeded 응답의 result.downloadUrl을 DOWNLOAD_URL에 복사한 뒤 다운로드 명령을 실행합니다.

상태가 queued 또는 processing이면 result는 null입니다. succeeded 상태가 되면 result.downloadUrl과 result.expiresInSeconds를 읽습니다. failed 또는 canceled이면 다운로드를 다시 시도하지 말고 error.code와 error.message를 확인하세요.

몇 초마다 조회하되 계정 읽기 제한을 지키세요. 파일에 아직 접근할 수 있는 동안 새 상태 조회로 만료된 다운로드 링크를 갱신할 수 있습니다. 링크는 최대 15분 동안 유효하며 파일 접근 24시간 제한을 넘지 않습니다. 상태 조회, 다운로드, 정확히 같은 멱등 재전송은 크레딧을 사용하지 않습니다.

JSON 생성 요청에서는 sourceUrl과 options를 사용합니다. 서버는 HTTPS URL만 가져오고, 각 리디렉션을 검증하며, 사설 네트워크를 차단하고, 업로드와 동일한 파일 크기 제한을 적용합니다.

웹사이트가 브라우저 CORS를 차단하면 로컬 URL 가져오기가 실패할 수 있습니다. REST URL 가져오기는 여전히 클라우드 작업이며 API 키, 크레딧, 요청 한도, 보관 규칙을 사용합니다.

GET /api/v1/usage는 { usage }를 반환합니다. usage 객체에는 활성 풀, limit, used, reserved, remaining, resetAt, windowStart, windowEnd가 포함됩니다. 생성 요청은 무료 10 rpm, Developer 60 rpm으로 제한되며, 상태 또는 사용량 조회는 계정당 120 rpm까지 가능합니다.

무료 API 기간은 UTC 달력 기준 매월 초기화됩니다. Developer 기간은 연간 구독을 포함해 구독 기준일에 맞춰 매월 초기화됩니다. 크레딧은 이월되지 않습니다. 무료 계정은 미완료 작업 2개, Developer 계정은 20개까지 허용되며, 무료 대기열에는 100개 작업을 담을 수 있습니다. 무료 작업이 10분 넘게 기다리면 종료되고 예약이 해제됩니다.

MCP 엔드포인트는 /api/mcp의 Streamable HTTP입니다. compress_gif, get_compression, get_usage를 제공하고 REST와 동일한 API 키를 사용합니다.

MCP에는 원격 HTTPS GIF URL을 전달할 수 있습니다. 로컬 파일은 REST로 업로드하세요. 서버 로컬 경로나 대용량 Base64 페이로드를 MCP 도구에 전달하지 마세요.

compress_gif에는 sourceUrl, 선택적 options 객체, 필수 idempotencyKey를 전달합니다. 그런 다음 반환된 id를 get_compression에 전달하세요. 어댑터는 REST 응답을 structuredContent.data로 감쌉니다. 도구 전송이 성공했다는 뜻이 압축 작업 완료를 의미하지는 않습니다. 잔액 확인은 빈 객체로 get_usage를 호출하세요.

5MB 이하 입력은 quality 또는 size 모드에서 1 credit, target 모드에서 2 credits가 듭니다. 5MB 초과 20MB 이하 입력은 2 credits, target 모드에서는 4 credits가 듭니다. 각 처리 시도에는 60초 예산과 최대 8개의 인코딩 후보 제한이 있습니다.

검증 실패, 시스템 실패, 시간 초과에는 사용자 크레딧이 차감되지 않습니다. 유효한 결과가 나왔지만 요청한 목표 용량을 충족하지 못한 경우에는 연산이 완료되었으므로 공개된 견적이 차감됩니다. 작업에는 targetMet: false가 표시됩니다.

작업의 credits 및 cost.credits 필드는 견적 비용을 보여줄 뿐, 차감 완료의 증거가 아닙니다. 크레딧은 작업 접수 시 예약되고, 성공 시 확정되며, 실패 시 해제됩니다. 현재 used, reserved, remaining 잔액은 /api/v1/usage에서 확인하세요.

일반적인 오류 코드에는 API_KEY_REQUIRED, API_KEY_INVALID, INSUFFICIENT_CREDITS, FREE_API_NOT_ACTIVE, IDEMPOTENCY_CONFLICT, INPUT_TOO_LARGE, INVALID_GIF, RATE_LIMITED, TOO_MANY_OUTSTANDING_TASKS, FREE_COMPUTE_BUDGET_EXHAUSTED가 포함됩니다.

401은 API 키가 없거나 유효하지 않음을 의미합니다. 402는 사용자 크레딧이 소진된 경우에만 사용됩니다. 403은 무료 API가 활성화되지 않았음을, 409는 멱등성 충돌을, 413은 클라우드 입력 크기 한도 초과를, 422는 유효하지 않은 GIF 데이터 또는 옵션을 의미합니다. 429는 생성·읽기 요청 한도 또는 미완료 작업 수 제한에 도달했음을 나타냅니다. 503은 일시적인 대기열 압박 또는 FREE_COMPUTE_BUDGET_EXHAUSTED를 의미합니다. Retry-After가 있으면 따르세요.

로컬 브라우저 압축과 클라우드 API 작업은 데이터 흐름이 다릅니다. GIF를 기기에 남겨야 한다면 브라우저 도구를 사용하고, 원격 워크플로에서 처리해야 한다면 REST 또는 MCP를 사용하세요.

브라우저 도구는 GIF를 업로드하지 않습니다. URL로 가져오면 이미지가 있는 사이트에 직접 연결합니다. API와 MCP 요청은 파일을 업로드하거나 서비스가 공개 HTTPS URL에서 가져오도록 요청합니다. Cloudflare가 애플리케이션, 데이터베이스, 파일 저장소를 호스팅합니다. API 입력·출력 파일은 24시간 후 접근이 만료되며 다운로드 링크는 최대 15분간 유효합니다. 백그라운드 정리가 만료 파일을 제거하므로 실제 삭제는 더 늦을 수 있습니다. 안정성과 이용 현황을 측정하기 위해 압축 성공 또는 실패, 입력·출력 크기, 목표 상태, 다운로드 같은 기술 이벤트를 Cloudflare 서비스 로그에 기록합니다. 이러한 이벤트에는 파일 이름, 원본 URL, 파일 내용이 포함되지 않습니다. Cloudflare도 서비스 제공과 보호를 위해 요청 데이터를 처리합니다. 제품 이벤트 로그는 최대 7일간 보관합니다.

생성, 상태, 사용량 요청에는 Authorization: Bearer YOUR_API_KEY를 보내세요. API는 x-api-key 헤더도 받습니다. 계정 로그인 쿠키는 API 키를 대체하지 않습니다. 한 계정에 속한 모든 키는 이용량과 제한을 공유합니다.

키는 서버 측 환경 변수나 AI 클라이언트의 보호된 설정에 보관하세요. 공개 웹페이지, 저장소, 이미지 URL에 넣지 마세요. 키가 노출되면 API 키 설정에서 폐기하고 새 키를 만드세요. 무료 브라우저 도구에는 API 키가 필요 없습니다.

mode는 quality, size, target을 받으며 기본값은 quality입니다. target은 10진수 바이트로 측정한 양의 정수 targetBytes가 필요합니다. 100KB는 100000, 1MB는 1000000입니다. multipart 업로드에서는 이 필드를 JSON으로 인코딩한 options 필드 안에 넣으세요.

선택적 colors는 auto, 64, 128, 256을 받습니다. lossyLevel은 0부터 200까지의 정수입니다. width는 1부터 4096까지의 정수이며 크기 조절을 요청합니다. 원래 크기를 유지하려면 생략하세요. 프레임 삭제나 형식 변환 옵션은 지원하지 않습니다.

한 요청은 하나의 GIF를 처리합니다. Free API 입력은 5MB, Developer 입력은 20MB로 제한됩니다. 또한 양쪽 모두 각 변이 최대 4096픽셀, 최대 1,000프레임, width × height × frame count가 최대 50,000,000이어야 합니다. 짧지만 매우 큰 애니메이션은 바이트 크기 제한보다 먼저 이러한 안전 제한에 걸릴 수 있습니다.

새 파일과 옵션 요청마다 새 Idempotency-Key를 선택하고, 불확실한 네트워크 응답 뒤 다시 시도할 때는 그 키를 유지하세요. 키는 1~128자의 출력 가능한 공백 없는 ASCII 문자입니다. 동일한 재전송은 기존 작업을 반환합니다. 같은 키에서 입력 또는 옵션을 바꾸면 409 IDEMPOTENCY_CONFLICT가 반환됩니다.

429 또는 일시적인 503 응답에서는 Retry-After가 있으면 따르고 대기 시간을 늘리세요. 402 크레딧 부족은 이용량 초기화나 플랜 변경이 필요하며, 요청을 반복해도 해결되지 않습니다. 503 FREE_COMPUTE_BUDGET_EXHAUSTED는 표시된 초기화 시점까지 새 무료 작업을 중지하지만, 유료 작업과 로컬 브라우저 도구는 별개로 유지됩니다.

실패한 작업은 그 키를 다시 보내도 같은 실패한 작업으로 남습니다. 먼저 원인을 확인한 뒤 의도적으로 새 시도를 할 때 새 키를 사용하세요. 모든 시간 초과마다 새 키를 만들지 마세요. 첫 번째 요청이 이미 접수되었을 수 있습니다.