Dify에서 BeatAPI 사용하기

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

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

사전 준비

Dify 워크스페이스 — 클라우드 서비스 또는 자체 호스팅 배포.
BeatAPI API 키 — 대시보드 → API Keys에서 만드세요.

1단계: 모델 설정 열기

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

2단계: BeatAPI 추가

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

방법 A: OpenAI 제공자 재사용

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

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

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

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

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

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

필드	값
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 페이지에, 요금은 가격 페이지에 있습니다.

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

4단계: 빌드하고 게시

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

설정해 두면 좋은 파라미터

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

자주 묻는 질문

Dify가 연결되지 않음

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

실행할 때만 모델이 실패함

Dify 목록에서는 켜져 있지만 계정에서 제공하지 않는 모델입니다. 가격 페이지와 ID를 비교하세요.

402 insufficient_credits

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

429 rate_limit_exceeded

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

비용 관리

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

지원

대시보드에서 지원 티켓을 열고 실패한 응답의 request_id를 함께 보내 주세요.