INTEGRITY Dokumentace

← Cloudflare AI Gateway / ai-gateway / usage

REST API

REST API vám umožňuje volat libovolný model, ať už hostovaný na Cloudflare, nebo u poskytovatele třetí strany, jako je OpenAI, Anthropic nebo Google, prostřednictvím stejného Cloudflare API, přičemž se automaticky uplatní všechny funkce AI Gateway (protokolování, cachování, omezování počtu požadavků a další).

Nejsou potřeba žádná SDK poskytovatelů ani API klíče. Ověřování a fakturace probíhají prostřednictvím vašeho účtu Cloudflare. Modely třetích stran jsou fakturovány prostřednictvím Unified Billing. Modely Workers AI mohou využívat předplacené kredity AI Gateway nebo fakturace Workers AI.

Endpointy

K dispozici jsou čtyři koncové body, každý vhodný pro jiný případ užití:

Endpoint Formát Případ použití Modely od třetích stran Modely Workers AI (@cf/)
POST /ai/run Obálka s model, input Všechny modely a modality (LLM, obraz, TTS, ASR) ✅ Ano ✅ Ano
POST /ai/v1/chat/completions OpenAI chat completions LLM kompatibilní s OpenAI SDK ✅ Ano ✅ Ano
POST /ai/v1/responses OpenAI Responses API Agentní workflow kompatibilní s OpenAI SDK ✅ Ano ✅ Závisí na modelu
POST /ai/v1/messages Anthropic Messages API LLM kompatibilní s Anthropic SDK ✅ Ano ❌ Ne

Ověřování

Ověřte se pomocí Token Cloudflare API která má Účet > Workers AI > Čtení oprávnění. Předejte je v Authorization hlavička.

Všechny /accounts/{account_id}/ai/* koncové body vyžadují oprávnění Workers AI. Platí to jak pro modely třetích stran, tak pro Workers AI (@cf/) modely. Token, který obsahuje pouze AI Gateway oprávnění vrací 401 s chybovým kódem 10000.

AI Gateway oprávnění platí pro /accounts/{account_id}/ai-gateway/* koncové body, které slouží ke správě konfigurace brány, protokolů a tras.

Pojmenování modelů

Modely od třetích stran používají author/model formát:

Modely Workers AI používají @cf/author/model formát (například @cf/moonshotai/kimi-k2.6). Požadavky Workers AI také vyžadují cf-aig-gateway-id hlavičku, viz Zavolejte model Workers AI s podrobnostmi.

Prohlédněte si dostupné modely v katalog modelů.

/ai/run : univerzální koncový bod

Přijímá libovolný model s jeho vlastním schématem. Parametry specifické pro daný model se uvádí uvnitř input.

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "openai/gpt-4.1",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "What is Cloudflare?"
        }
      ],
      "max_tokens": 512
    }
  }'

Zavolejte model Workers AI

Chcete-li zavolat model Workers AI, použijte @cf/ prefix v názvu modelu a zahrnout cf-aig-gateway-id hlavičku k určení brány, přes kterou se má požadavek směrovat.

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "cf-aig-gateway-id: default" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "@cf/moonshotai/kimi-k2.6",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "What is Cloudflare?"
        }
      ]
    }
  }'

Stávající koncový bod Workers AI s ID modelu v cestě URL nadále funguje také:

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run/@cf/moonshotai/kimi-k2.6" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "cf-aig-gateway-id: default" \
  --header "Content-Type: application/json" \
  --data '{
    "messages": [
      {
        "role": "user",
        "content": "What is Cloudflare?"
      }
    ]
  }'

Chcete-li použít předplacené kredity AI Gateway pro Workers AI, použijte výše uvedený koncový bod model-in-path a u gateway nastavte Nastavení fakturace Workers AI na Jednotné účtování, a jeho ID uveďte v cf-aig-gateway-id hlavička. Požadavky na frontier modely účtované z předplacených kreditů získávají vyšší limity počtu požadavků.

Požadavky na pozadí a webhooky

Standardně /ai/run požadavky jsou synchronní: připojení zůstává otevřené, dokud model nedokončí zpracování a výsledek se nevrátí v odpovědi. U dlouho běžících modelů, jako je generování obrázků, videa nebo zvuku, nebo pokud nechcete držet připojení otevřené, spusťte požadavek na pozadí a nechte AI Gateway po dokončení upozornit webhook.

Nastavte background na true a uveďte webhookUrl. Obě jsou pole options objekt v /ai/run tělo, spolu s model a input.

webhookUrl lze uvést pouze v případě, že background je true. Uvedení webhookUrl bez background: true vrací 400 chyba.

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "google/nano-banana",
    "input": {
      "prompt": "A cozy coffee shop interior with warm lighting, plants hanging from the ceiling, and a cat sleeping on a velvet armchair by the window",
      "aspect_ratio": "16:9"
    },
    "options": {
      "background": true,
      "webhookUrl": "https://example.com/my-webhook"
    }
  }'

Požadavek na pozadí vrátí odpověď okamžitě, zatímco model běží. Výsledek je po dokončení běhu doručen na váš webhook.

Payload webhooku

Po dokončení běhu odešle AI Gateway jediný POST požadavek na vaši webhookUrl s výsledkem běhu:

{
	"id": "<run-id>",
	"state": "<run-state>",
	"result": {},
	"error": null,
	"provider": "google",
	"model": "google/nano-banana",
	"usage": {}
}

Doručení webhooku probíhá na bázi best-effort a v případě selhání se neopakuje. Cílová adresa musí být HTTPS URL, která se nepřekládá na adresu privátní sítě.

Formát webhooku

Použijte volitelný webhookFormat v options objekt pro řízení podoby těla webhooku. Výchozí hodnota je raw. webhookFormat lze uvést pouze v případě, že webhookUrl je přítomná. V opačném případě požadavek vrátí 400 chyba.

Formát Popis
raw Odesílá payload v nezměněné podobě (výchozí).
chat Obalí payload do { "text": "<prettified JSON>" }, odpovídající tělu příchozího webhooku přijímanému službami Google Chat a Slack.

/ai/v1/chat/completions : Kompatibilní s OpenAI

Používá standardní formát OpenAI chat completions. Tento model pole používá stejný author/model pojmenování. Tento endpoint je kompatibilní s OpenAI SDK a dalšími klienty kompatibilními s OpenAI.

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "openai/gpt-4.1",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "What is Cloudflare?"
      }
    ],
    "max_tokens": 512,
    "temperature": 0.7,
    "stream": true
  }'

OpenAI SDK

Nasměrujte OpenAI SDK baseURL na Cloudflare API:

import OpenAI from "openai";

const openai = new OpenAI({
	apiKey: CLOUDFLARE_API_TOKEN,
	baseURL: `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/ai/v1`,
});

const response = await openai.chat.completions.create({
	model: "openai/gpt-4.1",
	messages: [{ role: "user", content: "What is Cloudflare?" }],
});

/ai/v1/responses : OpenAI Responses API

Používá formát OpenAI Responses API pro agentické workflow. Kompatibilní s OpenAI SDK.

import OpenAI from "openai";

const openai = new OpenAI({
	apiKey: CLOUDFLARE_API_TOKEN,
	baseURL: `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/ai/v1`,
});

const response = await openai.responses.create({
	model: "openai/gpt-4.1",
	input: "What is Cloudflare?",
});

/ai/v1/messages : Kompatibilní s Anthropic

Používá formát Anthropic Messages API. Kompatibilní s Anthropic SDK.

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/messages" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "anthropic/claude-sonnet-4-5",
    "max_tokens": 512,
    "messages": [
      {
        "role": "user",
        "content": "What is Cloudflare?"
      }
    ]
  }'

Nasměrujte Anthropic SDK baseURL na Cloudflare API:

import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic({
	apiKey: CLOUDFLARE_API_TOKEN,
	baseURL: `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/ai/v1`,
});

const message = await anthropic.messages.create({
	model: "anthropic/claude-sonnet-4-5",
	max_tokens: 512,
	messages: [{ role: "user", content: "What is Cloudflare?" }],
});

Někteří poskytovatelé zpřístupňují nativní nástroje (včetně webového vyhledávání na straně serveru) prostřednictvím těchto koncových bodů. Podrobnosti najdete v Web Search pro podporované modely jednotlivých poskytovatelů a tvar požadavku, který každý z nich používá. Projděte si katalog modelů pro kanonická ID modelů.

Zadat gateway

Požadavky na modely třetích stran ve výchozím nastavení směřují přes výchozí AI Gateway vašeho účtu. Chcete-li použít konkrétní gateway, uveďte cf-aig-gateway-id hlavička. Požadavky Workers AI tuto hlavičku vyžadují vždy.

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "cf-aig-gateway-id: default" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "anthropic/claude-sonnet-4",
    "messages": [
      {
        "role": "user",
        "content": "Hello"
      }
    ]
  }'

V OpenAI SDK nastavte hlavičku pomocí defaultHeaders:

const openai = new OpenAI({
	apiKey: CLOUDFLARE_API_TOKEN,
	baseURL: `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/ai/v1`,
	defaultHeaders: {
		"cf-aig-gateway-id": "default",
	},
});

Na požadavek se vztahují všechny funkce AI Gateway nakonfigurované na dané bráně: ukládání do mezipaměti, omezování rychlosti, guardrails a protokolování.

Konfigurace na požadavek

Použijte cf-aig-* hlavičky pro řízení chování AI Gateway u jednotlivých požadavků:

Hlavička Typ Popis
cf-aig-skip-cache boolean Přeskočte mezipaměť pro tento požadavek.
cf-aig-cache-ttl number TTL mezipaměti v sekundách.
cf-aig-cache-key string Vlastní klíč mezipaměti.
cf-aig-collect-log boolean Zapněte nebo vypněte protokolování pro tento požadavek.
cf-aig-request-timeout number Časový limit požadavku v milisekundách.
cf-aig-max-attempts number Počet pokusů o opakování (max. 5).
cf-aig-retry-delay number Prodleva mezi opakováními v milisekundách (max. 5000).
cf-aig-backoff string Metoda backoffu: constant, linear, nebo exponential.
cf-aig-metadata Řetězec JSON Vlastní metadata k připojení k záznamu protokolu.

Podrobnosti o těchto možnostech najdete v Zpracování požadavků a Ukládání do mezipaměti.