↓ Skip to main content
HJP’s Evening Stroll
HJP’s Evening Stroll
  1. Posts/

Build a Free AI Gateway on Cloudflare Workers AI

·574 words·2 mins· loading · loading · ·
Cloudflare Workers AI Serverless Tutorial AI Tools
HJP
Author
HJP
Always learning, always growing.
Table of Contents

This is a summary of a longer Chinese tutorial on building a free AI gateway on Cloudflare Workers AI. It shares only the method — no deployed endpoints or credentials.

What it is
#

Cloudflare Workers AI hosts its own open-source model catalog, and every account gets 10,000 free neurons per day (shared across all models, reset at 00:00 UTC; on the Free plan you simply get errors past the limit — no charges). This gateway wraps that free quota into an OpenAI-compatible API so any OpenAI client (Cherry Studio, Chatbox, OpenWebUI) can use it.

What the gateway does
#

  1. Auth — clients send a custom ACCESS_KEY; the gateway validates it before forwarding to Workers AI. No real credentials ever leave your Cloudflare account.
  2. Daily quotas via KV — a global daily request cap (default 1000) plus a per-IP cap (default 200), keyed by UTC date; excess requests get HTTP 429. This stops the free quota from being drained.
  3. OpenAI compatibility — POST /v1/chat/completions (non-streaming + SSE streaming) and GET /v1/models.

Architecture
#

Client (any OpenAI-compatible app)
   │  Authorization: Bearer <ACCESS_KEY>
   ▼
Cloudflare Worker (free-ai-gateway)
   ├─ auth → KV quota check → model mapping → env.AI.run()
   ├─ KV (QUOTA_KV): quota:day:{date} / quota:ip:{date}:{ip} / quota:model:{date}:{m}
   └─ Workers AI binding: env.AI
        ▼
Workers AI (10,000 free neurons/day)

Since the gateway itself runs on Cloudflare, calling Workers AI through the env.AI binding adds no extra network cost — only neurons count against the free quota.

Deploy (outline)
#

  1. npm i -D wrangler; npx wrangler login.
  2. npx wrangler kv namespace create QUOTA_KV, put the id in wrangler.toml.
  3. npx wrangler secret put ACCESS_KEY (your client-facing key).
  4. Write wrangler.toml: custom-domain route, [[kv_namespaces]] binding, [ai] binding = "AI", and [vars] for DEFAULT_MODEL / DAILY_LIMIT / IP_DAILY_LIMIT.
  5. npx wrangler deploy; verify with GET /v1/models, a 401 without the key, a real POST /v1/chat/completions, and GET /stats.

The complete secret-free src/index.js and full wrangler.toml are in the Chinese version.

Models
#

Friendly names map to Workers AI ids: llama-3.3-70b (default), llama-3.1-8b, qwen-30b, qwen-coder-32b, glm-4.7-flash, mistral-small, and llama-vision — a multimodal model that accepts OpenAI-style image_url inputs (data URL or http URL), so clients like Cherry Studio can send images directly. Raw @cf/... ids also work, but note: not every catalog model runs on the Free plan — frontier models like kimi-k2.6 and deepseek-v4-flash return error 5035 (Workers Paid required).

Client setup
#

  • Base URL: https://<your-gateway-host>/v1
  • API Key: your ACCESS_KEY (the random string from step 3)
  • Model: any friendly name above, e.g. llama-3.3-70b

Gotchas
#

  • wrangler 4.x uses kv namespace create (space, not colon).
  • KV get’s cacheTtl minimum is 30 seconds — 0 is rejected (400).
  • Workers AI streaming is SSE (data: {...}\n\n events). Llama chunks look like {"response":"text"}, while GLM streams OpenAI-style {"choices":[{"delta":{...}}]} — the gateway’s extractContent() handles both.
  • GLM’s non-streaming out.response is a full nested OpenAI JSON string; parse it instead of returning it as raw text.
  • After deploy, old and new versions coexist for 1–2 minutes (progressive rollout) — retry if you hit an old version right after deploying.

When to pick this vs the OpenRouter gateway
#

This gateway is ideal for light tasks (translation, copywriting, summarization, casual chat) at zero cost. The OpenRouter gateway bills by usage but unlocks the full model catalog, including closed-source models — better for complex reasoning and coding.

Full Chinese version: 自建免费 AI 网关：把 Cloudflare Workers AI 白嫖成 OpenAI 接口

Related