Cloudflare AI Gateway REST API 공개: OpenAI Responses·Anthropic Messages 한 엔드포인트 호출법

 

Cloudflare AI Gateway REST API 공개: OpenAI·Anthropic 모델을 한 엔드포인트로 호출하기

api.cloudflare.com 기반 새 AI REST API가 OpenAI, Anthropic, Google, Workers AI 호출 방식을 어떻게 묶는지 정리합니다.

 

Cloudflare AI Gateway REST API 공개: 무엇이 바뀌었나

 

Cloudflare는 2026년 5월 21일 AI Gateway의 새 REST API를 공개했다. OpenAI Responses, OpenAI Chat Completions, Anthropic Messages, Workers AI 호출을 api.cloudflare.com 기반의 공통 인증과 라우팅으로 묶는 내용이다.

AI 모델을 앱에 붙여 쓰면 처음에는 모델 품질만 보입니다. 그런데 실제로 조금만 굴려 보면 API 키가 어디에 있는지, 비용이 어느 기능에서 튀는지, 실패한 요청을 어디서 볼지 같은 운영 문제가 더 빨리 다가옵니다. OpenAI는 OpenAI대로, Anthropic은 Anthropic대로, Workers AI는 또 다른 방식으로 붙이면 작은 프로젝트도 호출 경로가 쉽게 흩어집니다.

2026년 5월 21일 Cloudflare 공식 changelog에 올라온 AI Gateway REST API는 이 흩어진 호출 경로를 `api.cloudflare.com` 기반으로 묶는 업데이트입니다. 2026년 5월 23일 작성 기준, 문서는 OpenAI, Anthropic, Google, Workers AI 모델을 Cloudflare API token과 계정 단위 경로에서 호출하는 방식을 설명합니다.

Cloudflare AI Gateway REST API OpenAI Responses Anthropic Messages를 찾는 독자라면 궁금한 지점은 대체로 세 가지입니다. 기존 경로가 사라지는지, OpenAI Responses와 Anthropic Messages 중 어떤 endpoint를 써야 하는지, 그리고 비용과 로그가 어디에 남는지입니다. 제가 보기에는 이번 업데이트의 포인트가 새 모델 추가보다 AI 호출을 운영 가능한 계층으로 모으는 선택지에 더 가깝습니다.

 

 

AI Gateway 업데이트 타임라인

 

2026년 5월 21일 공개된 REST API는 OpenAI-compatible endpoint, default gateway 자동 생성, payload log 제어, gateway-level retry 이후 이어진 통합 흐름에 놓여 있다.

2025년 6월 3일에는 AI Gateway에 OpenAI-compatible endpoint가 추가됐습니다. 2026년 3월 2일에는 `default` gateway ID를 쓰면 첫 요청 때 gateway가 자동 생성되는 흐름이 공지됐고, 3월 17일에는 request/response payload 저장 여부를 제어하는 로그 관련 기능이 나왔습니다.

그 뒤 2026년 4월 2일에는 upstream provider 실패에 대한 gateway-level retry가 붙었습니다. 이번 2026년 5월 21일 업데이트는 그 다음 단계입니다. `POST /ai/run`, `POST /ai/v1/chat/completions`, `POST /ai/v1/responses`, `POST /ai/v1/messages`를 `api.cloudflare.com` 쪽 REST API 표면으로 정리했습니다.

이 순서를 보면 Cloudflare가 단순히 provider API를 감싸는 데서 멈추려는 흐름은 아닙니다. 모델 호출을 한곳으로 모으고, 그 위에 logging, caching, rate limiting, guardrails, retry 같은 운영 장치를 얹는 구조입니다. 한국 사용자 입장에서는 “어떤 모델이 제일 좋은가”보다 “우리 앱의 AI 호출을 어디에서 추적하고 제어할 것인가”라는 질문에 더 가깝습니다.

 

기존 gateway.ai.cloudflare.com 방식과 새 REST API 차이

 

새 방식은 provider별 gateway URL을 바꾸는 접근에서 api.cloudflare.com의 AI REST API 표면으로 이동한 것이 핵심이다. 다만 기존 Workers AI REST API path는 중단된 것이 아니라 계속 동작한다고 공식 changelog가 밝힌다.

기존 방식에 익숙한 독자라면 가장 먼저 “예전 endpoint가 없어지는가”를 확인하는 편이 맞습니다. 공식 changelog는 기존 Workers AI REST API path인 `/ai/run/@cf/{model}`이 계속 동작한다고 밝힙니다. 그래서 이번 업데이트를 강제 마이그레이션 공지처럼 읽으면 방향이 틀어집니다.

달라진 점은 호출의 중심이 더 명확해졌다는 데 있습니다. Cloudflare AI Gateway REST API는 Cloudflare 계정의 `api.cloudflare.com/client/v4/accounts/{account_id}/ai/...` 경로를 기준으로 하고, `Authorization: Bearer ...` 형식의 Cloudflare API token을 사용합니다. third-party model은 `openai/...`, `anthropic/...`, `google/...` 같은 provider/model 이름을 쓰고, Workers AI 모델은 `@cf/...` 형식입니다.

구분	기존에 신경 쓰던 것	새 REST API에서 확인할 것
호출 경로	provider별 gateway 또는 Workers AI 경로	account-scoped `api.cloudflare.com` AI 경로
인증	provider key 또는 Cloudflare 설정 조합	AI Gateway 권한이 있는 Cloudflare API token
모델명	provider별 관습	`openai/...`, `anthropic/...`, `@cf/...`처럼 문서화된 naming
운영 제어	앱 코드와 provider 콘솔에 분산	gateway 단위 logging, caching, rate limiting, guardrails

실제로 확인할 부분은 `cf-aig-gateway-id`입니다. REST API 문서는 third-party model 요청이 기본적으로 계정의 default AI Gateway로 라우팅될 수 있고, 특정 gateway를 지정하려면 이 헤더를 쓴다고 설명합니다. Workers AI 요청에는 gateway 지정 헤더가 필요하다고 문서화돼 있으니, 기존 Workers AI 사용자는 이 차이를 먼저 봐야 합니다.

 

 

네 가지 엔드포인트: /ai/run, chat completions, responses, messages

 

OpenAI SDK 앱은 /ai/v1/chat/completions 또는 /ai/v1/responses를, Anthropic SDK 앱은 /ai/v1/messages를 우선 검토하면 된다. /ai/run은 model과 input을 감싸는 universal endpoint로 여러 modality 실험에 적합하다.

실무에서는 endpoint 이름보다 “내 코드가 이미 어떤 API 표면을 기대하는가”가 먼저입니다. 이름만 보면 비슷하지만 Cloudflare AI Gateway REST API OpenAI Responses Anthropic Messages 조합에서 선택 기준은 꽤 다릅니다.

`/ai/v1/chat/completions`는 기존 OpenAI Chat Completions 형식에 맞춘 앱에서 먼저 볼 만합니다. OpenAI SDK를 쓰는 코드라면 `baseURL`을 Cloudflare의 account-scoped `/ai/v1` 경로로 바꾸는 접근이 문서에 나옵니다. 기존 챗봇이나 간단한 질의응답 앱은 이 경로가 비교적 마찰이 작습니다.

`/ai/v1/responses`는 OpenAI Responses API 형식에 맞춘 endpoint입니다. 에이전트형 작업, input 중심 호출, Responses API 기반 구조를 이미 쓰고 있거나 새로 검토하는 팀이라면 이쪽을 봐야 합니다. 반대로 Anthropic SDK와 Messages API 형태를 유지하고 싶다면 `/ai/v1/messages`가 더 자연스럽습니다. Anthropic SDK도 `baseURL`을 Cloudflare 경로로 바꾸는 방식이 공식 문서에 제시돼 있습니다.

`/ai/run`은 조금 다르게 봐야 합니다. 문서상 `model`과 `input`을 담는 envelope 형식이고, LLM뿐 아니라 이미지, TTS, ASR 등 여러 modality 실험에 쓰는 universal endpoint로 설명됩니다. 개인 프로젝트에서 Cloudflare 경유 호출 자체를 넓게 확인할 때는 괜찮지만, 기존 OpenAI 또는 Anthropic SDK 앱을 최소 수정으로 옮기는 목적이라면 SDK-compatible endpoint부터 보는 편이 낫습니다.

> 제 기준에서는 모든 endpoint를 한 번에 도입하려는 계획보다, 현재 앱이 기대하는 API 표면은 유지하고 gateway 계층만 Cloudflare로 옮기는 테스트가 더 현실적입니다.

 

설치와 첫 테스트: API token, account ID, baseURL

 

첫 테스트는 Cloudflare API token에 AI Gateway 권한을 부여하고, account ID와 baseURL을 Cloudflare API 경로로 바꾼 뒤 작은 요청으로 로그와 비용 반영을 확인하는 순서가 안전하다.

이 업데이트는 설치형 오픈소스가 아니라 관리형 API 업데이트입니다. 그래서 여기서 말하는 “설치”는 패키지 설치보다 Cloudflare 계정, 권한, 과금, gateway routing을 맞추는 작업에 가깝습니다.

작게 검증할 때는 아래 순서가 편합니다.

1. Cloudflare Account ID를 확인합니다.
2. `AI Gateway` permission이 있는 Cloudflare API token을 준비합니다.
3. third-party model을 쓸 경우 Unified Billing credit과 spend limit 상태를 확인합니다.
4. OpenAI SDK 앱이면 `baseURL`을 Cloudflare account-scoped `/ai/v1` 경로로 바꿔 `chat.completions` 또는 `responses`를 호출합니다.
5. Anthropic SDK 앱이면 같은 `/ai/v1` 경로를 `baseURL`로 지정하고 `messages.create` 계열의 작은 요청부터 보냅니다.
6. 특정 gateway로 묶어야 하면 `cf-aig-gateway-id` 헤더를 넣고, 로그가 의도한 gateway에 쌓이는지 확인합니다.

첫 요청은 긴 프롬프트보다 한 문장 응답 같은 저위험 요청이 낫습니다. OpenAI Chat Completions 형식에서는 `model`을 `openai/...` 형식으로 지정하고, Anthropic Messages 형식에서는 `anthropic/...` 모델명을 사용합니다. Workers AI 모델을 테스트한다면 `@cf/...` 형식과 gateway 지정 헤더를 함께 확인해야 합니다.

응답이 왔다는 사실만으로는 부족합니다. dashboard log에 provider, model, status, token usage, cost, duration 같은 운영 정보가 원하는 수준으로 남는지 봐야 Cloudflare AI Gateway REST API를 도입할 이유가 생깁니다.

 

 

 

실무 도입 모델: 사내 AI API proxy와 모델 교체 실험

 

이 업데이트의 실무 가치는 provider별 API key와 호출 경로를 앱마다 흩어두지 않고 Cloudflare AI Gateway를 관측/제어 지점으로 쓰는 데 있다. 비용 추적, rate limiting, caching, guardrails가 필요한 팀일수록 먼저 테스트할 이유가 크다.

작은 서비스라도 AI 기능이 늘어나면 나중에 이런 질문이 생깁니다. 어떤 요청이 어떤 모델로 갔는지, 비용이 얼마였는지, 실패했을 때 재시도했는지, 같은 사용자 요청이 여러 provider로 흩어졌는지입니다. Cloudflare AI Gateway REST API는 이 문제를 Cloudflare 계정의 gateway 계층에서 다뤄 보자는 제안에 가깝습니다.

도입 모델은 세 가지 정도로 나뉩니다.

• 개인 개발자/사이드 프로젝트: OpenAI SDK 코드의 `baseURL`만 바꿔 작은 기능부터 Cloudflare 경유로 테스트합니다. 목적은 로그와 비용이 눈에 보이는지 확인하는 데 있습니다.
• 팀 내부 AI 도구: gateway를 앱 또는 환경별로 나누고, rate limiting과 guardrails를 붙여 사내 테스트 트래픽을 관리합니다.
• 멀티 모델 실험: OpenAI Responses, Anthropic Messages, Google 모델, Workers AI를 한 운영 계층에서 비교하되, provider별 세부 기능 차이는 별도로 검증합니다.

Request handling 문서를 보면 timeout과 retry를 `cf-aig-request-timeout`, `cf-aig-max-attempts`, `cf-aig-retry-delay`, `cf-aig-backoff` 같은 헤더로 요청 단위에서 제어하는 흐름도 정리돼 있습니다. 장애 대응 관점에서는 꽤 실용적인 부분입니다. 다만 앱 레벨의 trace ID, 사용자 세션, 비즈니스 지표까지 자동으로 해결되지는 않습니다. AI Gateway 로그는 출발점이고, 제품 운영 로그와 연결하는 설계는 여전히 팀 몫입니다.

 

비용과 로그 리스크: Unified Billing은 무료가 아니다

 

Cloudflare API token만으로 provider API key 없이 third-party model을 호출할 수 있는 흐름이 생겼지만 무료 호출을 뜻하지는 않는다. third-party model은 Unified Billing, Workers AI는 Workers AI pricing을 따르므로 credit, fee, spend limit을 확인해야 한다.

다만 여기서 조심할 점은 비용입니다. Unified Billing 문서는 Cloudflare-managed third-party provider 호출에서 provider API key 없이 Cloudflare 계정 크레딧으로 차감되는 흐름을 설명합니다. 편해졌다는 뜻이지 무료라는 뜻은 아닙니다. Pricing 문서 기준으로는 Unified Billing credit 구매에 fee가 붙고, provider inference price는 pass-through로 설명됩니다. 가격과 한도는 바뀔 수 있으므로 2026년 5월 23일 작성 기준으로 읽어야 합니다.

로그도 같은 방식으로 봐야 합니다. AI Gateway logging은 운영 가시성을 높이지만 prompt와 response가 저장될 수 있는 환경에서는 민감정보 관리 문제가 생깁니다. 문서에는 `cf-aig-collect-log-payload: false`로 payload 저장을 끄고 metadata-only 로그만 남기는 운용이 가능하다고 설명돼 있습니다.

실무에서는 아래 항목을 먼저 정해야 합니다.

• third-party model에 쓸 Unified Billing credit과 spend limit
• Workers AI 모델과 third-party model의 과금 분리
• prompt/response payload 저장 여부
• `cf-aig-collect-log-payload` 적용 기준
• 캐시 가능한 프롬프트와 캐시하면 안 되는 사용자별 프롬프트
• provider별 기능이 Cloudflare 경유에서 동일하게 필요한지 여부

Cloudflare AI Gateway REST API OpenAI Responses Anthropic Messages 조합은 편리합니다. 그래도 개인정보나 내부 문서가 프롬프트에 들어가는 팀이라면 “호출 성공”보다 “무엇이 저장되는가”를 먼저 보는 편이 맞습니다.

 

 

 

한국 개발자에게 중요한 이유

 

한국 독자에게 이 업데이트는 새 모델 하나가 아니라 AI 호출 인프라의 운영 방식 변화로 읽는 편이 정확하다. 여러 provider를 쓰는 개인 개발자와 팀은 인증, 비용, 로그, 장애 대응을 한 계층에서 정리할 수 있는지 검토할 수 있다.

한국 개발자 입장에서는 Cloudflare Workers, Pages, R2 같은 생태계를 이미 쓰고 있는지가 첫 번째 분기점입니다. 프론트엔드나 백엔드가 Cloudflare 쪽에 붙어 있고, AI 호출만 OpenAI와 Anthropic으로 흩어져 있다면 운영 경계가 애매해지기 쉽습니다.

이번 업데이트는 그 경계를 Cloudflare 계정 단위로 모아 보자는 선택지입니다. OpenAI Responses 기반 에이전트 기능을 실험하면서 Anthropic Messages 기반 요약 기능도 함께 운영해야 하는 팀이라면, 각 provider 콘솔만 보지 않고 gateway 로그와 비용을 같이 보는 구조가 도움이 됩니다.

물론 무조건 옮길 필요는 없습니다. provider-native 기능을 깊게 쓰는 앱, latency가 아주 민감한 워크로드, 직접 provider invoice가 필요한 조직, 민감정보 로그 정책이 아직 정리되지 않은 팀은 서두르지 않는 편이 낫습니다. 작은 staging 요청으로 응답, 비용, 로그, retry, gateway routing을 검증한 뒤 production 후보로 올리는 흐름이 맞습니다.

제가 보기에는 가장 현실적인 첫 사용처가 “모델 성능 비교”는 아닙니다. 모델을 바꾸는 일보다 호출을 추적하는 일이 더 어려워지는 시점, 그때 Cloudflare AI Gateway REST API OpenAI Responses Anthropic Messages 조합을 검토할 이유가 생깁니다.

 

자주 묻는 질문

 

Q. Cloudflare AI Gateway REST API는 기존 gateway.ai.cloudflare.com 방식과 무엇이 다른가?
A. 새 방식은 `api.cloudflare.com`의 account-scoped AI REST API 경로를 중심으로 OpenAI, Anthropic, Google, Workers AI 호출을 묶는다. 다만 공식 changelog 기준 기존 Workers AI REST API path는 계속 동작하므로 강제 폐지로 해석하면 안 된다.

Q. OpenAI Responses API를 Cloudflare AI Gateway에서 호출하려면 무엇을 바꾸면 되나?
A. OpenAI SDK 사용 시 `baseURL`을 Cloudflare 계정의 `/ai/v1` 경로로 바꾸고, API key는 AI Gateway 권한이 있는 Cloudflare API token을 사용한다. 요청은 `/ai/v1/responses` 형식에 맞춰 작은 테스트부터 검증하는 것이 좋다.

Q. Anthropic Messages API도 Cloudflare AI Gateway REST API로 호출할 수 있나?
A. 가능하다. Cloudflare REST API 문서는 `/ai/v1/messages`를 Anthropic Messages API 형식 및 Anthropic SDK 호환 endpoint로 설명하며, `baseURL`을 Cloudflare `/ai/v1` 경로로 지정하는 예시를 제공한다.

Q. Cloudflare API token만 있으면 OpenAI나 Anthropic provider API key가 항상 필요 없나?
A. Cloudflare-managed third-party model 호출은 Unified Billing을 통해 provider API key 없이 Cloudflare 계정 크레딧으로 처리되는 흐름이 문서화돼 있다. 그러나 모든 계정, 모든 모델, 모든 provider-native 기능이 동일하게 보장된다고 단정하면 안 되며 supported models와 billing 상태를 확인해야 한다.

Q. Unified Billing은 무료인가?
A. 아니다. 2026년 5월 23일 작성 기준, 문서는 third-party model 호출이 Cloudflare 크레딧에서 차감되고 Unified Billing credit 구매에는 fee가 붙는 구조를 설명한다. Workers AI 모델은 별도 Workers AI pricing을 따른다.

Q. AI Gateway의 logging, caching, rate limiting, guardrails는 새 REST API에도 적용되나?
A. Cloudflare REST API 문서는 gateway를 통해 들어온 REST API 요청에도 AI Gateway의 logging, caching, rate limiting, guardrails가 적용된다고 설명한다. 실제로는 요청이 의도한 gateway에 라우팅되는지 `cf-aig-gateway-id`와 dashboard log로 확인해야 한다.

Q. 민감한 prompt와 response를 로그에 남기지 않으려면 무엇을 확인해야 하나?
A. Logging 문서의 payload 저장 옵션과 `cf-aig-collect-log-payload: false` 헤더를 확인해야 한다. metadata-only 로그가 충분한지, 캐시를 허용할 프롬프트가 무엇인지, 내부 개인정보 처리 정책과 맞는지 먼저 정하는 편이 안전하다.

함께 읽으면 좋은 글

 

• GitHub Copilot Auto 모델 선택: VS Code에서 작업별 모델 라우팅이 시작됐다 — AI UPDATES
• Claude Code 2.1.144 업데이트: 백그라운드 세션 /resume와 모델 설정 변화 — AI UPDATES
• Cursor Composer 2.5 출시: AI 코딩 모델 성능과 가격 변화 핵심 정리 — AI UPDATES

참조 링크

 

• AI Gateway Changelog: Call any AI model through AI Gateway's new REST API — 2026년 5월 21일 공식 업데이트 원문이며 공개 날짜, 엔드포인트, 기존 Workers AI path 유지 여부를 확인하는 1차 출처
• REST API - Cloudflare AI Gateway docs — 실제 호출 URL, 인증 방식, model naming, SDK baseURL, cf-aig-gateway-id 확인용 구현 문서
• Unified Billing - Cloudflare AI Gateway docs — third-party model billing, provider API key 없는 호출 흐름, Workers AI 과금 구분 확인
• Pricing - Cloudflare AI Gateway docs — Unified Billing credit fee, pricing, log limit 등 비용 관련 기준 확인
• Logging - Cloudflare AI Gateway docs — AI Gateway dashboard log 항목과 payload 저장 제어 확인
• Request handling - Cloudflare AI Gateway docs — timeout, retry, backoff 등 per-request 운영 헤더 확인
• Supported models - Cloudflare AI Gateway docs — 지원 모델과 provider별 제한을 최신 상태로 확인하기 위한 보조 문서
• Responses - OpenAI API Reference — OpenAI Responses API 원 API 개념 확인용 보조 출처
• Messages - Anthropic API — Anthropic Messages API 원 API 개념 확인용 보조 출처