> 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.

# Dify에서 BeatAPI 사용하기

> Dify에 BeatAPI를 모델 제공자로 설정하고 앱, 에이전트, 워크플로 전반에서 사용합니다.

# Dify에서 BeatAPI 사용하기

Dify는 채팅 앱, 에이전트, 워크플로를 만드는 LLMOps 플랫폼입니다. BeatAPI를 모델 제공자로 한 번 추가하면 워크스페이스의 모든 앱에서 선택할 수 있습니다.

아래의 모델 제공자 설정은 [Dify Marketplace의 BeatAPI 도구 플러그인](https://marketplace.dify.ai/plugin/erickkkyt/beatapi)과 별개입니다. 현재 Marketplace에는 뮤직비디오 도구 두 개가 포함된 v0.1.0가 올라 있습니다. 기능이 확장된 v0.2.1 플러그인은 [Marketplace 심사를 위해 제출](https://github.com/langgenius/dify-plugins/pull/3164)되었습니다. 제출했다고 해서 Marketplace가 업그레이드되었거나 모든 새 도구가 Dify 워크스페이스에서 실행 검증을 마쳤다는 뜻은 아닙니다.

## 사전 준비

1. **Dify 워크스페이스** — 클라우드 서비스 또는 자체 호스팅 배포.
2. **BeatAPI API 키** — [대시보드 → API Keys](https://beatapi.io/dashboard/apikeys)에서 만드세요.

## 1단계: 모델 설정 열기

오른쪽 위의 아바타를 클릭하고 **Settings**를 선택한 다음 왼쪽 메뉴에서 **Model Provider**를 선택하세요.

## 2단계: BeatAPI 추가

두 방법의 결과는 같습니다. 첫 번째가 더 빠르고, 두 번째는 BeatAPI를 다른 제공자와 분리해 둡니다.

### 방법 A: OpenAI 제공자 재사용

1. **OpenAI** 제공자를 찾아 **Configure**를 클릭하세요.
2. 다음을 입력하세요.

| 필드           | 값                           |
| ------------ | --------------------------- |
| API Key      | BeatAPI API 키               |
| API Base URL | `https://api.beatapi.io/v1` |

3. 저장한 다음 모델 목록에서 사용할 모델을 켜세요.

> **Note**
>
> Dify의 OpenAI 모델 목록은 Dify 자체 목록이며 엔드포인트에서 읽어 오지 않습니다. BeatAPI가 제공하지 않는 모델을 켜면 그 모델로 만든 앱을 실행할 때 `not_found`가 발생합니다. 아래 표나 [가격 페이지](https://beatapi.io/pricing)에 있는 ID만 켜세요.

### 방법 B: 사용자 지정 모델 제공자 추가

1. **Custom Model**까지 스크롤하고 **+ Add Model**을 클릭하세요.
2. 다음을 입력하세요.

| 필드                  | 값                               |
| ------------------- | ------------------------------- |
| Model Name          | `BeatAPI` 또는 원하는 이름             |
| Model Type          | `LLM`                           |
| API Key             | BeatAPI API 키                   |
| API endpoint URL    | `https://api.beatapi.io/v1`     |
| Endpoint model name | 정확한 모델 ID(예: `claude-sonnet-5`) |

사용할 모델마다 반복하세요. 입력할 것은 많지만 목록에 실제로 동작하는 모델만 남습니다.

## 3단계: 모델

| 모델 ID                       | 컨텍스트 | 추천 용도                                  |
| --------------------------- | ---- | -------------------------------------- |
| `claude-fable-5-1`          | 김    | 까다로운 앱을 위한 최신 세대                       |
| `claude-sonnet-5`           | 김    | 품질과 비용의 균형                             |
| `claude-haiku-4-5-20251001` | 김    | 분류, 라우팅 등 저렴한 단계                       |
| `gpt-6-astra`               | 김    | 최신 OpenAI 세대. 입력 토큰이 272K를 넘으면 요금이 높아짐 |
| `gemini-3.7-flash`          | 김    | 빠르고 저렴함                                |
| `deepseek-v4-pro-0813`      | 김    | 저렴한 요금의 강력한 추론                         |
| `minimax-m3`                | 매우 김 | 일반적인 컨텍스트 상한을 넘는 문서                    |

자세한 내용은 [텍스트 API](/text-api) 페이지에, 요금은 [가격 페이지](https://beatapi.io/pricing)에 있습니다.

> **Note**
>
> 일부 모델은 부하나 컨텍스트 길이에 따라 요금이 바뀝니다. DeepSeek HC(고캐시) 모델 두 개는 평일 베이징 시간 09:00–12:00, 14:00–18:00에 요금이 두 배가 되고(일반 유료 DeepSeek 모델은 시간과 관계없이 요금이 같음), Hunyuan `hy3`는 자체 일일 피크 시간대가 있으며, GPT-6 Astra와 GPT-5.6 계열은 입력 토큰 272K 초과 시, Grok은 200K 초과 시 상위 요금이 적용됩니다. 예약 실행되는 Dify 워크플로는 아무도 모르는 사이에 피크 시간대에만 실행될 수 있습니다. [가격 페이지](https://beatapi.io/pricing)의 각주를 참고하세요.

## 4단계: 빌드하고 게시

1. Chatbot, Text Generator, Agent 또는 Workflow 앱을 만드세요.
2. **Model Settings**에서 BeatAPI 모델을 선택하세요.
3. 시스템 프롬프트를 작성하세요. 사용자 입력은 `{{variable}}`, 지식 베이스 내용은 `{{context}}`를 사용합니다.
4. 미리보기 패널에서 테스트한 다음 API, 임베드 또는 공유 링크로 **Publish**하세요.

### 설정해 두면 좋은 파라미터

| 파라미터        | 이펙트       | 권장값                  |
| ----------- | --------- | -------------------- |
| Temperature | 출력의 무작위성  | `0.7` 창의적, `0.3` 정확함 |
| Max Tokens  | 출력 길이 상한  | 2000–4000            |
| Top P       | 누클리어스 샘플링 | `0.9`                |

## 자주 묻는 질문

### Dify가 연결되지 않음

1. Base URL은 `/v1`을 포함한 `https://api.beatapi.io/v1`여야 하며, 끝에 슬래시를 붙이지 않습니다.
2. [대시보드 → API Keys](https://beatapi.io/dashboard/apikeys)에서 키가 활성 상태인지 확인하세요.
3. 자체 호스팅 배포: 브라우저뿐 아니라 Dify **서버**가 `api.beatapi.io`에 접근할 수 있는지 확인하세요.

### 실행할 때만 모델이 실패함

Dify 목록에서는 켜져 있지만 계정에서 제공하지 않는 모델입니다. [가격 페이지](https://beatapi.io/pricing)와 ID를 비교하세요.

### 402 insufficient_credits

잔액 부족: 잔액이 0이거나 요청 가격보다 적습니다. 대시보드에서 충전하세요. 잔액이 비어 있는 동안 게시된 앱은 사용자에게 실패하므로 알림을 설정해 두는 것이 좋습니다.

### 429 rate_limit_exceeded

키의 요청 속도 한도를 넘었습니다. 대개 워크플로가 요청을 병렬로 퍼뜨린 경우입니다. 워크플로의 동시성을 줄이거나 한도를 높이세요. 분당 한도는 누적 충전액에 따라 올라가며 대시보드에 표시됩니다.

### 비용 관리

* 앱마다 BeatAPI 키를 따로 두면 [`GET /v1/usage`](/quick-guide)의 `by_api_key`로 앱별 비용을 구분할 수 있습니다.
* 분류, 라우팅, 추출 같은 저렴한 단계는 저렴한 모델에 맡기고, 강력한 모델은 최종 답변에만 쓰세요.
* 모든 노드에 Max Tokens 상한을 두세요. 워크플로 노드는 넉넉한 기본값을 물려받습니다.

## 지원

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