브라우저에서 Sume API 호출 시 CORS 오류: 해결 방법

CORS 오류가 나는 이유는 내 도메인의 웹 페이지가 api.sume.com을 직접 호출할 수 없기 때문입니다. Sume API는 현재 Sume 자체 웹 오리진에만 CORS 헤더를 보내므로 브라우저가 호출을 차단합니다. 해결책은 Sume 문서가 어차피 요구하는 방식입니다. API 키는 서버에 두고, 브라우저가 백엔드나 서버리스 함수를 호출하게 하고, 그 코드가 Sume를 호출하게 하세요.

아래 CORS 동작은 API 서버 코드에서 읽은 것으로, 현재 동작을 설명합니다. 키 관련 규칙은 2026-09-27에 확인한 Sume 인증 페이지에서 가져왔습니다. 키, 스코프, 호스트가 동작하는 방식은 Sume API 키 동작 방식에서 다룹니다.

브라우저는 왜 Sume API 호출을 차단하나요?

CORS는 브라우저의 규칙입니다. 페이지는 다른 오리진의 응답을, 그 서버의 Access-Control-Allow-Origin 헤더가 페이지의 오리진을 허용할 때만 읽을 수 있습니다. Sume 호출에는 Authorization이나 x-api-key 헤더가 실리므로, 브라우저는 먼저 OPTIONS 프리플라이트 요청을 보내고 프리플라이트가 허용할 때만 실제 요청을 보냅니다.

현재 코드에서 Sume API는 요청마다 Origin 헤더를 Sume 자체 웹 오리진의 허용 목록과 대조합니다. 그 밖의 오리진에는 CORS 헤더를 붙이지 않으므로 프리플라이트 요청이 실패하고, 내 코드는 상태 코드도 본문도 전혀 받지 못합니다. CORS는 브라우저가 강제하고 서버는 강제하지 않으므로, 같은 요청을 백엔드에서 보내면 통과합니다.

Sume API는 어디에서 호출할 수 있나요?

키를 비밀로 지킬 수 있는 곳이라면 어디서든 호출할 수 있습니다. CORS보다 먼저 문서의 안전 규칙이 이를 정합니다.

서버 쪽 프록시로 어떻게 해결하나요?

문서에 이 패턴이 나와 있습니다. 브라우저와 모바일 클라이언트는 백엔드를 호출하고, 백엔드가 서버 쪽 환경 변수에서 Sume 키를 가져와 붙입니다. 아래 라우트 핸들러는 요청을 아바타 생성으로 전달합니다.

export async function POST(request: Request) {
  const body = await request.json();

  const response = await fetch("https://api.sume.com/v1/avatar-1.0/generate", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SUME_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify(body),
  });

  return new Response(await response.text(), {
    status: response.status,
    headers: { "Content-Type": "application/json" },
  });
}

프록시는 요청을 전달하기 전에 무엇을 확인해야 하나요?

어떤 요청이든 전달하는 프록시는 누구나 내 키로 비용을 쓸 수 있게 만듭니다. 프록시를 자체 API처럼 다루세요.

• Sume로 요청을 전달하기 전에 사용자 입력을 검증하고 자체 인가를 적용하세요.
• 키 헤더는 정확히 하나만 보내세요. 이미 x-api-key를 보내는 클라이언트 위에 Authorization을 덧붙이는 게이트웨이는 401 unauthorized를 받습니다.
• 요청 본문에 workspace_id, owner_user_id, user_id를 넣지 마세요. Sume는 이 값들을 키에서 알아냅니다.
• 이제 모든 방문자가 키의 분당 요청 예산(읽기 예산과 쓰기 예산은 별도)을 함께 쓰므로, ratelimit-remaining과 retry-after 헤더를 보고 요청 속도를 조절하세요.
• 영상이 렌더링되는 동안 브라우저 요청을 열어 두지 마세요. 서버리스 타임아웃과 AI 영상에서 설명하듯 비동기로 제출한 뒤 폴링하거나 웹훅을 받으세요.
• 브라우저 번들, 로그, 채팅 기록 등으로 키가 노출되면 대시보드에서 교체하세요.

대신 브라우저에서 TypeScript SDK를 쓸 수 있나요?

쓸 수 없습니다. @sume-com/sdk 클라이언트는 API 키로 만들기 때문에 클라이언트 코드가 아니라 백엔드 라우트에 두어야 합니다. 문서에 나온 런타임은 Node 18+, Bun, Deno, Cloudflare Workers입니다. 백엔드 흐름 전체는 제품에 AI 영상 생성 임베드하기에서 보여 줍니다.