freebuff2cloudflare-api

freebuff 무료 모델을 OpenAI 호환 API로 쓸 수 있게 해주는 Cloudflare Worker입니다. 파일 하나, 의존성 없이 동작하며 Cloudflare 콘솔에 붙여넣거나 wrangler CLI로 바로 배포할 수 있습니다.

주요 기능

계정·모델별 한도 관측 — 인증된 GET /v1/accounts?refresh=1으로 Worker egress 기준 계정 tier와 DeepSeek Flash·Muse Spark의 upstream 한도 스냅샷을 확인합니다.
나머지 모델도 정상 호출 — meta/muse-spark-1.2-contributor는 minimal ~ xhigh까지 공식 reasoning_effort를 지원합니다. 현재 배포 환경(미국 리전 고정)에서는 high, xhigh 등으로 실제 호출이 성공했습니다.
미국 리전 고정 배포 — wrangler.toml의 [placement] region = "aws:us-west-1"로 Worker 실행 위치를 미국 서부 근처로 고정했습니다. freebuff 무료 모델이 미국 출구 IP를 요구하기 때문입니다.
여러 계정 자동 전환 — FREEBUFF_TOKEN에 토큰을 쉼표로 이어 붙이면, 한도가 걸리거나 세션이 실패했을 때 자동으로 다음 계정으로 넘어갑니다.
한도 계정 회피 — upstream의 모델 한도 엔트리가 확인된 계정·모델 조합은 45분 동안 기억합니다. 한도 엔트리가 없는 계정을 먼저 선택하고, 429 한도 초과 계정도 같은 방식으로 제외합니다.
중복 토큰 자동 정리 — 같은 토큰을 두 번 넣어도 하나의 계정으로만 처리됩니다.
살아 있는 세션 재사용 우선 — 세션은 보통 1시간 정도 유지되며 만들 때만 한도가 차감됩니다. 아직 유효한 세션이 있으면 같은 계정을 계속 쓰고, 없을 때만 다른 계정으로 옮겨 한도를 아납니다.
광고 요청 흐름 모방 — 새 세션을 만들기 전에 공식 클라이언트처럼 광고 노출 요청을 한 번 보냅니다. 실패해도 채팅에는 영향이 없습니다.
OpenAI 호환 — GET /v1/models, POST /v1/chat/completions을 스트리밍과 일반 응답 모두 지원합니다.
헬스 체크 — GET /healthz는 인증 없이 호출할 수 있습니다.
단일 파일 — 별도 설치 없이 바로 배포할 수 있습니다.
전체 한국어 — 코드 주석, CLI 출력, 텔레그램 알림까지 모두 한국어입니다.

모델과 한도

한도는 모델·계정별로 다르며, 서버가 수시로 갱신합니다. 아래는 실측 기준 rateLimitsByModel에서 확인한 값입니다.

모델	한도
`deepseek/deepseek-v4-flash`	계정별 상이. `limited` 계정에서는 실측 6회/태평양일
`mimo/mimo-v2.5`	계정별 상이. upstream `rateLimitsByModel`로 확인
`meta/muse-spark-1.2-contributor`	계정마다 다름 — 어떤 계정은 6회/일, 어떤 계정은 제한 없음
`z-ai/glm-5.2`	레퍼럴 없이는 한도 0 (세션 생성 429)

한도는 태평양 시간 기준 하루 단위이며, 한국 시간으로는 보통 오후 4시쯤 리셋됩니다. 세션을 새로 만들 때만 차감됩니다.

전체 모델 목록

API 모델 이름	세션 모델	upstream agentId
`deepseek/deepseek-v4-flash`	동일	`base2-free-deepseek-flash`
`deepseek/deepseek-v4-pro`	동일	`base2-free-deepseek`
`minimax/minimax-m3`	동일	`base2-free-minimax-m3`
`mimo/mimo-v2.5`	동일	`base2-free-mimo`
`openai/gpt-5.6-luna`	동일	`base2-free-luna`
`z-ai/glm-5.2`	동일	`base2-free-glm`
`poolside/laguna-s-2.1`	동일	`base2-free-laguna-s-2-1`
`openrouter/poolside/laguna-s-2.1`	동일	`base2-free-laguna-s-2-1-openrouter`
`inclusionai/ling-3.0-flash:free`	동일	`base2-free-ling-3-flash`
`crof/greg-2-ultra`	동일	`base2-free-greg-2-ultra`
`crof/greg-2-super`	동일	`base2-free-greg-2-super`
`anthropic/claude-fable-5`	동일	`base2-free-fable`
`meta/muse-spark-1.2-contributor`	동일	`base2-free-muse-spark`

reasoning_effort (Muse Spark)

none은 지원하지 않습니다 (400 오류)
minimal, low, medium, high, xhigh만 공식에서 지원합니다
max, extreme, ultra는 공식에 없고 무시될 수 있습니다

참고: https://dev.meta.ai/docs/reasoning

빠르게 시작하기

freebuff 토큰을 발급합니다 (아래 `FREEBUFF_TOKEN 발급` 참고)
Worker를 배포합니다 (아래 `배포` 참고. 콘솔에 붙여넣거나 wrangler로 배포)
Cloudflare 대시보드에서 변수를 설정합니다
- FREEBUFF_TOKEN (필수)
- FREEBUFF_API_KEY (선택, 비워두면 freebuff-default-key)
OpenAI 호환 클라이언트에서 아래처럼 연결합니다
- Base URL: https://<워커 주소>/v1
- API Key: FREEBUFF_API_KEY에 넣은 값

헬스 체크

curl https://<워커 주소>/healthz
# {"status":"ok","version":"1.6.0","time":"..."}

인증 없이 호출할 수 있어 모니터링용으로 쓰기 좋습니다.

계정 권한·모델 한도 조회

인증된 계정 관측 endpoint입니다. 토큰은 끝 4자리만 표시됩니다.

# 현재 Worker isolate에 캐시된 상태만 반환. upstream 호출 없음.
curl -H "Authorization: Bearer <API_KEY>" \
  https://<워커 주소>/v1/accounts

# Worker egress에서 각 계정의 upstream GET /session을 실행해 상태를 새로 조회.
curl -H "Authorization: Bearer <API_KEY>" \
  'https://<워커 주소>/v1/accounts?refresh=1'

refresh=1 응답은 계정별 다음 데이터를 포함합니다.

upstream.access_tier: upstream 계정 권한 (full, limited 등)
upstream.status: free session 상태 (none, active 등)
upstream.country_code, upstream.country_block_reason: Worker egress 기준 upstream 지역/리스크 판정
models.deepseek/deepseek-v4-flash.rateLimitsEntry, models.meta/muse-spark-1.2-contributor.rateLimitsEntry: upstream 원본 한도 데이터 (limit, recentCount, resetAt 등)

rateLimitsEntry: null은 upstream이 해당 모델 한도를 이 응답에 싣지 않았다는 뜻입니다. 무제한을 보장하는 표시는 아닙니다. refresh=1은 세션을 만들거나 모델을 호출하지 않지만, 활성 free session의 상태를 조회하므로 운영 중인 대화와 겹치지 않을 때만 실행하세요.

FREEBUFF_TOKEN 발급

freebuff_tools/extract_freebuff.py를 씁니다. 파이썬 표준 라이브러리만 있으면 됩니다.

cd freebuff_tools
python3 extract_freebuff.py login   # 인증 주소가 나오면 브라우저에서 열고 구글 로그인, 이후 자동으로 토큰 저장
python3 extract_freebuff.py show    # 저장된 토큰 확인 (마스킹되어 표시)
python3 extract_freebuff.py tgsend  # 텔레그램 연결 테스트 (선택)

토큰은 freebuff_tools/freebuff_credentials.json에 저장됩니다. 이 파일은 깃에 올리지 마세요. login은 기본적으로 이메일의 @ 앞부분을 프로필 레이블로 사용하며, session --label <레이블>, chat --label <레이블>, quota --label <레이블>로 특정 계정을 선택할 수 있습니다.

GitHub Actions로 원격 발급 (권장 — 미국 IP로 받으면 tier가 달라질 수 있음)

이 저장소에는 이미 워크플로가 포함되어 있습니다 (.github/workflows/extract-token.yml).

필요한 준비물

텔레그램에서 @BotFather에게 /newbot을 보내 봇을 만든 뒤 HTTP API 토큰을 받습니다
@freebuff_token_bot(방금 만든 봇)을 열고 /start를 보낸 뒤, 터미널에서 curl "https://api.telegram.org/bot<토큰>/getUpdates"로 chat.id를 확인합니다
저장소의 Settings → Secrets and variables → Actions에서 두 secret을 넣습니다
- TG_BOT_TOKEN: 봇 토큰
- TG_CHAT_ID: 숫자 chat id

실행

Actions → Freebuff authToken 발급 → Run workflow → Run을 누르면 GitHub의 미국 러너에서 인증 절차가 시작됩니다. 텔레그램 봇 채팅으로 인증 링크가 오면, 꼭 새 구글 계정으로 로그인하세요. 같은 구글 계정으로 다시 로그인하면 같은 토큰이 다시 발급될 수 있습니다. 인증이 끝나면 새 토큰이 텔레그램으로 옵니다.

텔레그램 봇 토큰을 채팅에 그대로 올리면 즉시 유출로 간주됩니다. 확인 뒤 @BotFather에서 /revoke로 재발급하세요.
실제 토큰을 채팅에 붙여넣지 마세요.

배포

방법 A: Cloudflare 콘솔에 붙여넣기 (권장)

https://dash.cloudflare.com 에서 Workers & Pages로 이동한 뒤 Worker를 새로 만들고 배포합니다
해당 Worker에서 Edit code를 열고 worker.js 전체를 붙여넣은 뒤 다시 배포합니다
Settings, Variables and Secrets에서 Add를 눌러 아래 값을 넣습니다
- FREEBUFF_TOKEN
- FREEBUFF_API_KEY (선택)
배포가 잘 됐는지 확인합니다

curl https://<워커 주소>/healthz
curl https://<워커 주소>/v1/models -H "Authorization: Bearer <API_KEY>"

방법 B: wrangler CLI

npm i -g wrangler
npx wrangler login
cp .env.example .dev.vars  # FREEBUFF_TOKEN 입력
npx wrangler dev           # 로컬에서 테스트
npx wrangler deploy        # 배포
npx wrangler secret put FREEBUFF_TOKEN
npx wrangler secret put FREEBUFF_API_KEY

Placement (미국 고정 — 지연 실측으로 고정)

wrangler.toml에 아래 설정이 추가되어 있습니다.

[placement]
region = "aws:us-west-1"

freebuff 무료 모델은 미국 출구 IP를 요구합니다. Cloudflare Workers는 기본적으로 미국 쪽으로 나가지만, 이 설정을 넣으면 실행 위치 자체를 미국 서부(N. California) 근처로 고정해 지연을 줄일 수 있습니다.

북미 6개 리전을 실제로 배포해가며 실측한 결과 (서울에서)

리전	median healthz
`aws:us-west-2` (Oregon)	0.308초
`aws:us-west-1` (N. California)	0.326초 — 편차 최소
`gcp:us-west1`	0.319초
`gcp:us-central1`	0.335초
`gcp:us-east4`	0.315초
`aws:us-east-1` (Virginia 동부, 이전 기본값)	0.382초

서부 리전이 동부 대비 50~75ms 빠릅니다
aws:us-west-1이 편차가 가장 작아 최종 고정했습니다
mode = "smart"는 북미가 아닌 곳으로 튈 수 있어 쓰지 않았습니다
chat 스모크(deepseek-v4-flash)는 6/6 리전 모두 성공했습니다

관련 문서: https://developers.cloudflare.com/workers/configuration/placement/

커스텀 도메인

*.workers.dev 접속이 막힌 환경이라면 Worker에 본인 도메인을 연결한 뒤 Base URL을 https://api.내도메인/v1 형태로 바꾸면 됩니다.

호출 예시

curl https://<워커 주소>/v1/chat/completions \
  -H "Authorization: Bearer <API_KEY>" -H "Content-Type: application/json" \
  -d '{"model":"deepseek/deepseek-v4-flash","messages":[{"role":"user","content":"안녕"}],"reasoning_effort":"high"}'

curl -N https://<워커 주소>/v1/chat/completions \
  -H "Authorization: Bearer <API_KEY>" -H "Content-Type: application/json" \
  -d '{"model":"meta/muse-spark-1.2-contributor","messages":[{"role":"user","content":"증명해줘"}],"reasoning_effort":"xhigh","stream":true}'

여러 계정으로 쓰기

FREEBUFF_TOKEN에 token1,token2처럼 쉼표로 구분해 넣으면 됩니다. 한도가 걸리면 해당 토큰은 잠시 쿨다운되고 다음 토큰으로 넘어가며, 아직 유효한 세션이 있으면 같은 계정을 계속 씁니다.

중복으로 넣어도 무해합니다. 같은 토큰을 두 번 넣어도 내부에서 하나의 계정으로만 처리됩니다.

무제한/한도 계정이 섞였을 때 (muse-spark)

muse-spark는 계정마다 한도가 다릅니다 — 어떤 계정은 6회/일, 어떤 계정은 한도 항목 자체가 없습니다. 현재 풀은 3계정 모두 6회로 동일하지만, 이전에는 중복 토큰으로 한 계정이 두 번 보이며 실제로는 한도만 공유되는 상태가 생겼고, 또 6회 계정이 먼저 선택되어 바로 한도에 걸리면 무제한 계정은 나중에야 선택되는 문제가 있었습니다. 지금은 같은 토큰은 Set으로 중복을 제거하고, 한 계정이 429 한도 초과로 거부되면 그 모델에 대해 소진으로 기억해 두고 다음 요청부터는 소진되지 않은 계정을 먼저 선택합니다 (45분 유지).

계정이 full/limited로 보이는 차이

처음 로컬에서 발급받은 토큰은 세션 조회에서 accessTier: limited였고, GitHub Actions 미국 러너에서 새로 발급받은 토큰은 full로 표시되었습니다. freebuff가 가입/로그인 시점의 출구 IP(리전)에 따라 등급을 매기는 것으로 보입니다. 한국 IP와 미국 IP에서 같은 절차로 받아도 tier가 달랐습니다.

추가로, 처음에는 muse-spark가 limited 계정에서 session_model_mismatch로 거부되었고, 같은 토큰을 미국 출구 Worker에 그대로 두면 정상 동작했습니다. 한국 로컬과 미국 Worker의 차이가 실제 호출에도 반영됩니다.

레퍼럴과 GLM 5.2

레퍼럴 코드 (FREEBUFF_TOKEN과 함께 오는 referral/streak 정보)는 현재 z-ai/glm-5.2의 한도를 여는 데 주로 관여합니다. 레퍼럴 없이는 limit 0으로 세션 생성 429가 납니다. muse-spark, deepseek, mimo의 한도는 레퍼럴로 크게 늘어나지 않습니다.

내부 동작

세션 생성 -> agent-runs (main + context-pruner) -> chat/completions

이 전체 과정을 Worker가 처리합니다. upstream에서 바이트 단위로 검증하는 You are Buffy, the strategic coding assistant. 접두사도 자동으로 붙입니다. /v1/models는 upstream을 조회하지 않고 목록을 그대로 돌려줍니다. 한 계정에서 동시에 세션을 하나만 쓸 수 있어, 조회가 진행 중인 대화를 방해할 수 있기 때문입니다.

끊겼을 때 재시도

중간에 끊기는 원인은 대부분 upstream codebuff.com의 free 채널 불안정(동시 1 초과 시 queued 타임아웃 — 최대 8회×1.5초 폴링, 428 waiting_room_required, 세션 만료 409 등)입니다. 이 코드는 요청 내부에서 풀의 모든 계정을 끝까지 순회하며 재시도합니다: 세션 만료 428/409는 sessCache를 비우고 강제 재생성해 1회 재시도하고, 그래도 실패하면 해당 계정을 쿨다운하고 다음 계정으로 교체합니다. 타임아웃·종료 등도 쿨다운 후 다음 계정으로 넘어갑니다. 계정별 뮤텍스와 300ms 간격으로 같은 계정의 upstream 요청을 직렬화하며, 스트리밍 응답 본문이 끝날 때까지 해당 계정 락을 유지합니다. 한도가 소진된 계정은 다음 요청부터 스킵되며, 모든 계정이 소진됐을 때만 다시 시도합니다. 한도가 동시에 임박하면 셋 다 끊길 수 있어 그때는 리셋(오후 4시)까지 기다려야 합니다.

라이선스

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
.github/workflows		.github/workflows
freebuff_tools		freebuff_tools
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
worker.js		worker.js
wrangler.toml		wrangler.toml

Navigation Menu

Repository files navigation

freebuff2cloudflare-api

주요 기능

모델과 한도

전체 모델 목록

reasoning_effort (Muse Spark)

빠르게 시작하기

헬스 체크

계정 권한·모델 한도 조회

FREEBUFF_TOKEN 발급

GitHub Actions로 원격 발급 (권장 — 미국 IP로 받으면 tier가 달라질 수 있음)

배포

방법 A: Cloudflare 콘솔에 붙여넣기 (권장)

방법 B: wrangler CLI

Placement (미국 고정 — 지연 실측으로 고정)

커스텀 도메인

호출 예시

여러 계정으로 쓰기

무제한/한도 계정이 섞였을 때 (muse-spark)

계정이 full/limited로 보이는 차이

레퍼럴과 GLM 5.2

내부 동작

끊겼을 때 재시도

라이선스

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

freebuff2cloudflare-api

주요 기능

모델과 한도

전체 모델 목록

reasoning_effort (Muse Spark)

빠르게 시작하기

헬스 체크

계정 권한·모델 한도 조회

FREEBUFF_TOKEN 발급

GitHub Actions로 원격 발급 (권장 — 미국 IP로 받으면 tier가 달라질 수 있음)

배포

방법 A: Cloudflare 콘솔에 붙여넣기 (권장)

방법 B: wrangler CLI

Placement (미국 고정 — 지연 실측으로 고정)

커스텀 도메인

호출 예시

여러 계정으로 쓰기

무제한/한도 계정이 섞였을 때 (muse-spark)

계정이 full/limited로 보이는 차이

레퍼럴과 GLM 5.2

내부 동작

끊겼을 때 재시도

라이선스

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages