> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# Immersive Translate에서 BeatAPI 사용하기

> Immersive Translate 브라우저 확장 프로그램에 BeatAPI를 사용자 지정 번역 서비스로 추가해 웹 페이지, PDF, 자막을 이중 언어로 봅니다.

# Immersive Translate에서 BeatAPI 사용하기

Immersive Translate는 웹 페이지, PDF, 동영상 자막을 이중 언어로 보여 줍니다. OpenAI 호환 엔드포인트라면 무엇이든 사용자 지정 번역 서비스로 받으므로 BeatAPI를 바로 연결할 수 있습니다.

## 사전 준비

1. **확장 프로그램 설치** — Chrome 웹 스토어, Edge 부가 기능, Firefox 부가 기능 또는 공식 사이트에서 받으세요.
2. **BeatAPI API 키** — [대시보드 → API Keys](https://beatapi.io/dashboard/apikeys)에서 만드세요.

## 1단계: 설정 열기

브라우저 툴바의 Immersive Translate 아이콘을 클릭한 다음 팝업 왼쪽 아래의 **Settings**를 클릭하세요. 왼쪽 메뉴에서 **Translation Services**를 선택합니다.

## 2단계: BeatAPI를 사용자 지정 서비스로 추가

목록 위쪽의 **+ Add Custom Translation Service**를 클릭하고 다음을 입력하세요.

| 필드               | 값                                            |
| ---------------- | -------------------------------------------- |
| 서비스 이름           | `BeatAPI`                                    |
| APIKEY           | BeatAPI API 키                                |
| 모델               | 모델 ID(예: `glm-5.3-flash`)                    |
| 사용자 지정 API 엔드포인트 | `https://api.beatapi.io/v1/chat/completions` |
| 초당 최대 요청 수       | `3`–`5`                                      |

> **Note**
>
> 이 필드에는 기본 URL이 아니라 경로까지 포함한 **전체 엔드포인트**(`https://api.beatapi.io/v1/chat/completions`)를 입력해야 합니다. 이 사이트의 연동 가이드 중 `https://api.beatapi.io/v1`만 입력하면 안 되는 유일한 경우입니다.

저장한 다음 확장 프로그램 팝업으로 돌아가 Translation Service 드롭다운에서 **BeatAPI**를 선택하세요.

## 3단계: 번역하기

* **웹 페이지** — 확장 프로그램 아이콘을 클릭하고 번역을 선택하거나 `Alt+A`를 누르세요.
* **PDF** — 브라우저에서 온라인 PDF를 열고 `Alt+A`를 누르세요. 로컬 파일은 먼저 웹 뷰어에서 열어야 합니다.
* **자막** — 지원되는 플랫폼에서 동영상을 재생하면 이중 언어 자막이 자동으로 표시됩니다.
* **선택한 텍스트** — 텍스트를 선택하고 단어 번역 패널(기본 `Alt+W`)을 사용하세요.

## 모델 선택

번역은 대부분의 사람에게 가장 양이 많고 반복적인 작업입니다. 페이지 하나가 작은 요청 여러 개로 나뉘므로, 다른 어떤 용도보다 모델 선택이 비용을 크게 좌우합니다.

| 모델 ID                    | 추천 용도                           |
| ------------------------ | ------------------------------- |
| `glm-5.3-flash`          | 일상적인 웹 탐색 — 번역 품질이 좋은 가장 저렴한 등급 |
| `gemini-3.7-flash`       | 빠르고 여러 언어에 강함                   |
| `qwen3.8-flash`          | 중국어 페이지                         |
| `deepseek-v4-flash-0731` | 대량 작업에 저렴하고 유능함                 |
| `claude-sonnet-5`        | 어조가 중요한 문학·창작 텍스트               |
| `gpt-5.6-terra`          | 기술·학술 문서                        |

전체 목록은 [텍스트 API](/text-api) 페이지와 [가격 페이지](https://beatapi.io/pricing)에 있습니다.

> **Note**
>
> `deepseek-v4-flash-0731`을 포함한 일반 유료 DeepSeek 모델은 시간과 관계없이 요금이 같습니다. DeepSeek HC(고캐시) 모델 두 개만 평일 베이징 시간 09:00–12:00, 14:00–18:00에 요금이 두 배가 되므로, 예약 작업이나 평일 낮 시간의 대량 탐색에 쓰기 전에 요금을 확인하세요. 정확한 시간은 [가격 페이지](https://beatapi.io/pricing) 각주에 있습니다.

## 자주 묻는 질문

### 설정 후에도 번역되지 않음

1. 설정에 저장만 한 것이 아니라 Translation Service 드롭다운에서 **BeatAPI**가 선택되어 있는지 확인하세요.
2. 엔드포인트는 전체 경로 `https://api.beatapi.io/v1/chat/completions`여야 합니다.
3. [대시보드 → API Keys](https://beatapi.io/dashboard/apikeys)에서 키가 활성 상태인지 확인하세요.
4. 모델 ID는 대소문자를 구분합니다.

### 번역이 느리거나 시간 초과됨

**Max requests per second**를 `3`으로 낮추세요. 페이지 하나가 동시 호출 여러 개로 나뉘며, 보통 모델이 아니라 요청 속도에서 막힙니다. 그런 다음 `glm-5.3-flash`나 `gemini-3.7-flash` 같은 더 빠른 등급으로 바꾸세요.

### 429 rate_limit_exceeded

위와 원인이 같고 한 단계 더 나아간 경우입니다. 먼저 초당 요청 설정을 낮추세요. 계정의 분당 한도는 누적 충전액에 따라 올라가며 대시보드에 표시됩니다.

### 번역 품질이 낮음

한 등급 올리세요(산문은 `claude-sonnet-5`, 기술 문서는 `gpt-5.6-terra`). AI Expert 스타일도 자료에 맞게 설정하세요. 반복되는 용어는 확장 프로그램의 용어 목록에 등록하세요. 더 큰 모델로도 해결되지 않는 일관성 문제를 바로잡을 수 있습니다.

### 402 insufficient_credits

잔액 부족: 잔액이 0이거나 요청 가격보다 적습니다. 대시보드에서 충전하세요.

### 비용 확인

확장 프로그램 전용 BeatAPI 키를 따로 만드세요. 웹 탐색은 작은 호출을 끊임없이 만들어 내므로, 키를 분리하면 [`GET /v1/usage`](/quick-guide)의 `by_api_key`와 대시보드에서 애플리케이션 트래픽과 구분할 수 있습니다.

## 지원

[대시보드](https://beatapi.io/dashboard)에서 지원 티켓을 열고 실패한 응답의 `request_id`를 함께 보내 주세요.