Chrome Prompt API란 무엇인가? API 개발자를 위한 브라우저 AI

Chrome은 브라우저 내부에 AI 모델을 직접 탑재했습니다. Prompt API는 이 모델을 사용하기 위해 호출하는 JavaScript 인터페이스입니다. API 키도, 네트워크 왕복도, 토큰당 요금도 없습니다. 이 모델은 Gemini Nano이며, 사용자의 기기에서 실행됩니다. Chrome 138부터는 확장 프로그램에서 일반적으로 사용할 수 있으며 웹 페이지에서는 플래그 뒤에 숨겨져 있습니다. API 개발자에게 있어 이는 클라이언트에서 수행할 수 있는 작업의 범위가 변화함을 의미합니다.

이 가이드에서는 Chrome Prompt API가 무엇인지, 클라우드 Gemini API와 어떻게 다른지, API 워크플로우에 언제 적합한지, 확장 프로그램과 웹 페이지 모두를 위한 실습 코드, 그리고 문서에서 인정하는 것보다 더 빨리 직면하게 될 한계점에 대해 다룹니다. 모델을 사용할 수 없을 때 동일한 작업에 대한 폴백 경로를 가질 수 있도록 마지막에 Apidog와 함께 사용법을 설명합니다.

버튼

핵심 요약

Chrome Prompt API는 웹 페이지의 `window.LanguageModel`과 확장 프로그램의 `chrome.languageModel`을 통해 Gemini Nano를 `LanguageModel`로 노출합니다.
모델은 전적으로 기기 내에서 실행됩니다. 네트워크 호출, 키, 토큰 비용이 없습니다.
Chrome 138+ 버전의 Chrome 확장 프로그램에서 안정적으로 사용할 수 있습니다. 웹 페이지의 경우, `chrome://flags/#prompt-api-for-gemini-nano` 플래그 및 등록된 Origin Trial 뒤에서 제공됩니다.
API 개발자를 위한 최적의 사용 사례: 클라이언트 측 입력 구문 분석, JSON 형식 수정, UI용 API 응답 요약, 개발 중 스텁 생성.
항상 클라우드 폴백을 연결하세요. 기기 내 모델은 개방형으로 실패하므로, 여러분의 코드는 그렇게 해서는 안 됩니다.

Prompt API가 실제로 노출하는 것

Prompt API는 Chrome이 작년부터 제공하기 시작한 소규모 "내장형 AI" API 그룹 중 하나입니다. 다른 API들은 더 좁은 범위(요약, 작성, 재작성, 번역, 언어 감지)를 가집니다. Prompt API는 범용적인 인터페이스이며, 다른 API들은 작업별 기본값으로 이를 감싸고 있습니다.

세 가지 기본 요소가 중요합니다:

`LanguageModel.availability()`. `available`, `downloadable`, `downloading`, 또는 `unavailable`을 반환합니다. 모델은 약 2GB 크기이며, 사이트에서 처음 요청할 때 백그라운드에서 다운로드됩니다.
`LanguageModel.create(options)`. 세션을 시작합니다. 세션은 턴 상태, 시스템 프롬프트, 몇 가지 샘플링 조절 기능을 유지합니다.
`session.prompt(text)` 및 `session.promptStreaming(text)`. 모델을 실제로 호출하는 두 가지 방법입니다.

형태는 의도적으로 Gemini 클라우드 SDK와 유사하지만 간소화되었습니다. 아직 도구 호출은 없으며, 안정화 채널에서는 이미지 입력이 지원되지 않고(Origin Trial에서 제공), 컨텍스트 창이 작습니다(입력 4K 토큰, 출력 1K 토큰, 총 8K 토큰까지 소프트 확장 가능).

웹 페이지에서의 첫 번째 호출은 다음과 같습니다:

if (!('LanguageModel' in window)) {
  console.warn('Prompt API not available. Falling back to cloud.');
} else {
  const status = await LanguageModel.availability();
  if (status === 'unavailable') {
    console.warn('Device does not support Gemini Nano.');
  } else {
    if (status !== 'available') {
      // 백그라운드 다운로드를 시작합니다. UI를 표시합니다.
      await LanguageModel.create({ monitor(m) {
        m.addEventListener('downloadprogress', e => {
          console.log(`downloaded ${(e.loaded * 100).toFixed(0)}%`);
        });
      }});
    }
    const session = await LanguageModel.create({
      systemPrompt: '세 가지 간결한 글머리 기호로 답변하십시오. JSON만 가능합니다.',
    });
    const reply = await session.prompt(
      '다음 변경 로그를 세 가지 글머리 기호로 요약하십시오.\n\n' + changelog
    );
    console.log(reply);
  }
}

이 스니펫에는 기능 감지, 가용성 확인, 선택적 다운로드, 세션 생성, 시스템 프롬프트, 프롬프트 호출 등 모든 중요한 부분이 표시되어 있습니다.

클라우드 Gemini API와의 차이점

동일한 계열이지만 배포 방식이 다릅니다. 이러한 차이점은 무엇을 구축할 수 있고 없는지를 결정합니다.

속성	Chrome Prompt API	Gemini API (클라우드)
모델	Gemini Nano (기기 내)	`gemini-3-flash`, `gemini-3-flash-preview`, `gemini-3-pro`
호출당 비용	없음	토큰당 과금
지연 시간	일반적으로 첫 토큰 50~300ms	첫 토큰 200~800ms
네트워크	모델 다운로드 후 필요 없음	모든 호출에 필요
개인 정보 보호	입력이 기기를 떠나지 않음	Google 서버로 전송됨
컨텍스트 창	입력 4K / 출력 1K (총 8K)	최대 1M 토큰
도구 호출	없음 (예정)	있음
멀티모달	Origin Trial에서 이미지 입력	있음
JSON 모드	시스템 프롬프트를 통한 최선의 노력	스키마를 통한 일급 지원
가용성	Chrome 전용, 지원 가능한 하드웨어 전용	네트워크가 있는 모든 클라이언트

기기 내 모델은 `gemini-3-flash`보다 대략 두 자릿수 정도 작습니다. 정규식이나 수동으로 조정한 프롬프트 분류기를 사용했을 짧은 작업에 사용하십시오. 클라우드 Gemini의 대체품으로 사용하지 마십시오.

API 개발자 워크플로우에 실제로 적합한 곳

네 가지 사용 사례는 통합 비용을 상쇄합니다. 이 외의 경우에는 클라우드 API가 여전히 올바른 선택입니다.

클라이언트 측에서 사용자 입력 구문 분석 및 재구성.자유 형식 쿼리를 API의 구조화된 필터로 변환합니다. 사용자가 “지난주 100달러 초과 Stripe 요금”이라고 입력하면, Prompt API는 검색 엔드포인트를 호출하기 전에 이를 `{ "amount_gt": 100, "since": "2026-04-22", "provider": "stripe" }`로 변환합니다. 왕복 시간을 절약하고 사용자 개인 정보를 보호합니다.
UI를 위한 API 응답 요약.자신의 API를 호출하여 40개의 레코드를 가져오고, 카드에 표시할 한 줄 요약이 필요할 때 사용합니다. 레코드를 클라우드 모델로 보내면 지연 시간과 비용이 추가됩니다. Prompt API는 로컬에서 실행되며 200ms 미만으로 결과를 반환합니다.
JSON 형식 수정.LLM 응답은 자주 잘못된 형식으로 도착하는 경우가 많습니다. Gemini Nano를 통해 한 번의 수정 패스를 실행합니다: “여기에 잘못된 JSON이 있습니다. 동일한 필드로 유효한 JSON만 반환하십시오.” 저렴하고 빠르며 비용이 들지 않습니다.
개발 중 로컬 스텁(Stub) 생성.새로운 엔드포인트를 연결하고 백엔드가 절반만 구축되었을 때, 그 자리에서 그럴듯한 응답 본문을 생성합니다. 형식은 프로덕션에 맞지 않을 수 있지만, 프런트엔드 작업을 막히지 않게 합니다. Apidog의 모의 서버와 결합하여 중요한 엔드포인트는 저장된 예제에서 가져오고 탐색적인 엔드포인트는 Prompt API에서 가져오는 하이브리드 설정을 구축할 수 있습니다.

확장 프로그램에 통합하기

확장 프로그램은 Chrome 138부터 안정화 채널에서 Prompt API를 사용할 수 있습니다. 권한을 선언하고 `chrome.languageModel`을 호출합니다.

manifest.json:

{
  "manifest_version": 3,
  "name": "Endpoint Summarizer",
  "version": "1.0.0",
  "permissions": ["languageModel"],
  "action": { "default_popup": "popup.html" }
}

popup.js:

const status = await chrome.languageModel.availability();
if (status === 'unavailable') {
  document.getElementById('out').textContent =
    'Device does not support on-device AI.';
  return;
}

const session = await chrome.languageModel.create({
  systemPrompt: [
    'HTTP 응답을 세 개의 짧은 글머리 기호로 요약하십시오.',
    '상태, 가장 많이 변경된 필드, 그리고 오류 키를 언급하십시오.',
  ].join(' '),
  temperature: 0.3,
  topK: 3,
});

document.getElementById('go').addEventListener('click', async () => {
  const tab = await chrome.tabs.query({ active: true, currentWindow: true });
  const [{ result }] = await chrome.scripting.executeScript({
    target: { tabId: tab[0].id },
    func: () => document.body.innerText.slice(0, 4000),
  });
  const stream = session.promptStreaming(result);
  const out = document.getElementById('out');
  out.textContent = '';
  for await (const chunk of stream) {
    out.textContent += chunk;
  }
});

두 가지 주목할 점이 있습니다. `temperature`와 `topK`는 API가 노출하는 유일한 샘플링 조절 기능입니다. `topP`는 안정화 채널에서 지원되지 않습니다. 스트리밍은 비동기 이터레이터이며, 서버 전송 이벤트가 아니므로, 소비 패턴은 클라우드 Gemini용으로 작성할 SSE 리더 대신 `for await`입니다.

웹 페이지에 통합하기

웹 페이지는 사용자가 플래그를 켜거나 여러분의 Origin이 Origin Trial에 등록되어야 합니다. 트라이얼 토큰은 메타 태그에 들어갑니다.

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="origin-trial" content="YOUR_TRIAL_TOKEN_HERE" />
</head>
<body>
  <textarea id="in" placeholder="Paste an API response..."></textarea>
  <button id="go">요약</button>
  <pre id="out"></pre>
  <script type="module">
    if (!('LanguageModel' in window)) {
      document.getElementById('out').textContent =
        'Prompt API not available in this browser.';
    } else {
      const session = await LanguageModel.create({
        systemPrompt: 'JSON으로 응답하십시오: { "summary": "...", "tags": [...] }',
        temperature: 0.2,
      });
      document.getElementById('go').onclick = async () => {
        const text = document.getElementById('in').value;
        const reply = await session.prompt(text);
        try {
          document.getElementById('out').textContent =
            JSON.stringify(JSON.parse(reply), null, 2);
        } catch {
          document.getElementById('out').textContent = reply;
        }
      };
    }
  </script>
</body>
</html>

Origin Trial 토큰 없이 페이지를 테스트하려면 `chrome://flags/#prompt-api-for-gemini-nano`를 열고 "Enabled"로 설정한 다음 Chrome을 다시 시작하십시오. 이 플래그는 지난 6개 버전에서 안정적이었지만 영구적으로 유지될 것이라고 약속된 것은 아닙니다. 예측 가능한 동작을 원한다면 Origin Trial 경로를 사용하십시오.

문서에서 충분히 강조하지 않는 한계 및 주의사항

여러분을 방해할 수 있는 여섯 가지 사항.

컨텍스트가 작습니다. 4K 입력, 1K 출력입니다. 공격적으로 잘라내세요. 50K 토큰 JSON 문서를 붙여넣고 유용한 답변을 기대하지 마십시오.
하드웨어 지원이 균일하지 않습니다. 모델은 약 4GB의 VRAM 또는 통합 메모리가 필요하며, Chrome 138+가 설치된 Windows, macOS, Linux, 최신 ChromeOS에서만 실행됩니다. 이 글을 쓰는 시점에는 모바일 Chrome이 지원되지 않습니다.
첫 로드가 느립니다. 2GB 다운로드는 백그라운드에서 발생하지만 첫 세션을 차단합니다. 항상 다운로드 진행 UI를 표시하십시오.
도구 호출이 없습니다. 작업에서 모델이 API를 호출해야 하는 경우, 클라이언트에서 직접 수행하십시오. 모델은 무엇을 호출할지만 결정합니다.
시스템 프롬프트 드리프트. 기기 내 모델은 클라우드 변형보다 시스템 프롬프트를 덜 엄격하게 따릅니다. 시스템 프롬프트에서 원샷 예제로 형식을 고정하십시오.
권한이 중요합니다. 확장 프로그램은 `permissions`에 `\"languageModel\"`이 필요합니다. 이를 잊으면 API는 조용히 `unavailable`을 반환합니다.

배포 전에 클라우드 폴백(Fallback)을 연결하세요

여러분의 앱은 모델이 없는 사용자에게도 배포됩니다. 항상 폴백을 연결하십시오. 패턴은 간단합니다:

async function summarize(text) {
  if ('LanguageModel' in window) {
    const status = await LanguageModel.availability();
    if (status === 'available') {
      const session = await LanguageModel.create({
        systemPrompt: '12단어 이내의 글머리 기호 요약으로 응답하십시오.',
      });
      return session.prompt(text);
    }
  }
  // 폴백: 서버를 호출하여 클라우드 Gemini 또는 사용자 고유의 모델을 호출합니다.
  const r = await fetch('/api/summarize', {
    method: 'POST', body: JSON.stringify({ text }),
  });
  return (await r.json()).summary;
}

개인 정보 보호 및 사용자에게 알려야 할 사항

Prompt API의 강점은 입력이 기기를 떠나지 않는다는 것입니다. 이는 현재 사실이며, 내장형 AI 이니셔티브의 명시적인 설계 의도입니다. 알아야 할 두 가지 자격 요건은 다음과 같습니다:

모델 자체는 Google이 Google의 데이터로 훈련했습니다. 이를 로컬에서 실행한다고 해서 이 사실이 바뀌지는 않습니다. Chrome은 브라우저 업데이트와 함께 가중치를 제공합니다.
사용에 대한 원격 측정은 사용자의 일반적인 Chrome 원격 측정 설정에 따라 Chrome에서 여전히 보고될 수 있습니다. 프롬프트 내용은 해당 원격 측정의 일부가 아닙니다.

대부분의 소비자 앱에서 이는 법적 검토 없이 UI에 넣을 수 있는 강력한 개인 정보 보호 이야기입니다. 규제 대상 워크로드(HIPAA, PCI)의 경우, 의존하기 전에 변호사와 확인하십시오.

Prompt API를 건너뛰어야 할 때

다음과 같은 경우 클라우드 Gemini API를 대신 선택하십시오:

작업에 4K 토큰 이상의 입력이 필요할 때.
도구 호출, 스키마 강제가 적용된 구조화된 출력, 또는 Origin Trial을 넘어선 멀티모달 입력이 필요할 때.
Safari, Firefox 또는 모바일 Chrome 사용자를 대상으로 서비스를 제공할 때. 현재 브라우저 지원은 Chrome 전용이며 Apple은 출시일을 알리지 않았습니다.
출력 품질이 지연 시간보다 중요할 때. Nano는 작지만 Pro는 그렇지 않습니다.

오픈 가중치 관점에서, 로컬에서 DeepSeek V4 실행 방법 게시물은 로컬 네트워크를 벗어나지 않고 개발자 머신에서 훨씬 더 큰 모델을 실행하는 방법을 다룹니다.

자주 묻는 질문

Prompt API는 공식 웹 표준 프로세스에 있습니까?W3C WebML 커뮤니티 그룹에서 제안으로 논의 중입니다. 다른 엔진이 출시될 때까지는 Chrome 전용으로 간주하십시오.
서비스 워커에서 사용할 수 있습니까?Chrome 138+에서는 확장 프로그램의 경우 가능합니다. 웹 페이지는 현재 문서 컨텍스트로 제한됩니다. 서비스 워커에 배포하기 전에 문서를 확인하십시오.
실제로 어떤 모델 크기를 얻는 것입니까?Gemini Nano는 2-4B 매개변수 범위에 있으며, 맞춰서 양자화되었습니다. Google은 특정 크기를 약속하지 않았으며, 커질 것으로 예상됩니다.
함수 호출을 지원합니까?안정화 채널에서는 지원하지 않습니다. Origin Trial 브랜치에는 실험적인 도구 지원이 있습니다. 프로덕션용으로는 의존하지 마십시오.
자동화된 CI에서 어떻게 테스트합니까?아직 헤드리스 Chromium에서 기기 내 모델을 실행할 수 없습니다. 테스트에서 `LanguageModel` 전역을 모의(mock)하고 CI에서 클라우드 폴백 경로를 실행하십시오.
상업적 사용에도 무료입니까?예. 호출당 요금은 없습니다. 사용자 기기의 저장 비용(약 2GB)은 사용자가 부담하며, Chrome이 업데이트를 처리합니다.

이미 클라우드 측 LLM 워크플로우를 함께 실행하는 팀의 경우, GPT-5.5란 무엇인가 게시물에서 클라우드 측의 장단점을 더 자세히 다루고, Apidog는 별도의 테스트 도구 없이 모의 및 폴백 연결을 처리합니다.

버튼