INTEGRITY Документация

← Cloudflare AI Gateway / ai-gateway / usage

REST API

REST API позволяет вызывать любую модель (размещённую в Cloudflare или у стороннего провайдера, такого как OpenAI, Anthropic или Google) через единый API Cloudflare, при этом все функции AI Gateway (логирование, кэширование, ограничение скорости запросов и другие) применяются автоматически.

Не нужны SDK провайдеров или API-ключи. Аутентификация и оплата обрабатываются через ваш аккаунт Cloudflare. Сторонние модели оплачиваются через Unified Billing. Модели Workers AI могут использовать предоплаченные кредиты AI Gateway или биллинг Workers AI.

Конечные точки

Доступны четыре эндпойнта, каждый из которых подходит для разных сценариев использования:

Конечная точка Формат Сценарий использования Сторонние модели Модели Workers AI (@cf/)
POST /ai/run Конверт с model, input Все модели и модальности (LLM, изображения, TTS, ASR) ✅ Да ✅ Да
POST /ai/v1/chat/completions OpenAI chat completions LLM, совместимые с OpenAI SDK ✅ Да ✅ Да
POST /ai/v1/responses OpenAI Responses API Агентные рабочие процессы: совместимость с OpenAI SDK ✅ Да ✅ Зависит от модели
POST /ai/v1/messages Anthropic Messages API LLM, совместимые с Anthropic SDK ✅ Да ❌ Нет

Аутентификация

Аутентифицируйтесь с помощью API-токен Cloudflare у которого есть Аккаунт > Workers AI > Чтение разрешение. Передайте его в Authorization заголовок.

Все /accounts/{account_id}/ai/* конечные точки требуют разрешения Workers AI. Это касается как сторонних моделей, так и Workers AI (@cf/) моделей. Токен, содержащий только AI Gateway разрешение возвращает 401 с кодом ошибки 10000.

AI Gateway разрешения применяются к /accounts/{account_id}/ai-gateway/* конечные точки, которые управляют настройкой шлюза, логами и маршрутами.

Именование моделей

Сторонние модели используют author/model формат:

Модели Workers AI используют @cf/author/model в формате (например, @cf/moonshotai/kimi-k2.6). Запросы Workers AI также требуют cf-aig-gateway-id заголовок. Подробнее см. в Вызов модели Workers AI для получения подробностей.

Просмотрите доступные модели в каталог моделей.

/ai/run, универсальная конечная точка

Принимает любую модель с соответствующей ей схемой. Параметры, специфичные для конкретной модели, указываются внутри 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
    }
  }'

Вызов модели Workers AI

Чтобы вызвать модель Workers AI, используйте @cf/ префикс в имени модели и включите cf-aig-gateway-id заголовок, чтобы указать, через какой шлюз направлять запрос.

# 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?"
        }
      ]
    }
  }'

Существующий эндпойнт Workers AI с ID модели в пути URL продолжает работать:

# 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?"
      }
    ]
  }'

Чтобы использовать предоплаченные кредиты AI Gateway для Workers AI, используйте эндпойнт model-in-path, показанный выше, и задайте в настройках шлюза настройка биллинга Workers AI к Единый биллинг, и указать его ID в cf-aig-gateway-id заголовок. Запросы к передовым моделям, оплачиваемые предоплаченными кредитами, получают более высокие лимиты количества запросов.

Фоновые запросы и вебхуки

По умолчанию /ai/run запросы синхронные: соединение остаётся открытым, пока модель не завершит работу и результат не вернётся в ответе. Для долго выполняющихся моделей, таких как генерация изображений, видео или аудио, или если вы не хотите держать соединение открытым, выполняйте запрос в фоновом режиме и настройте уведомление вебхука через AI Gateway по завершении.

Задайте background к true и укажите webhookUrl. Оба являются полями options объект в /ai/run тело, наряду с model и input.

webhookUrl можно указать только если background это true. Указание webhookUrl без background: true возвращает 400 ошибка.

# 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"
    }
  }'

Фоновый запрос возвращается немедленно, пока модель выполняется. Результат доставляется на ваш вебхук после завершения выполнения.

Payload вебхука

Когда запуск завершается, AI Gateway отправляет один POST запрос к вашему webhookUrl с результатом выполнения:

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

Доставка вебхуков выполняется по принципу best-effort и не повторяется. Адресом назначения должен быть HTTPS URL, который не преобразуется в адрес частной сети.

Формат вебхука

Используйте необязательный webhookFormat поле в options объект, чтобы задать структуру тела вебхука. По умолчанию используется raw. webhookFormat можно указать только если webhookUrl присутствует. В противном случае запрос вернёт 400 ошибка.

Формат Описание
raw Отправляет payload без изменений (по умолчанию).
chat Оборачивает payload в { "text": "<prettified JSON>" }, соответствующее телу входящего вебхука, которое принимают Google Chat и Slack.

/ai/v1/chat/completions, совместимо с OpenAI

Использует стандартный формат OpenAI chat completions. model поле использует тот же author/model именования. Эта конечная точка совместима с OpenAI SDK и другими клиентами, совместимыми с 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

Направьте OpenAI SDK baseURL в 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

Использует формат OpenAI Responses API для агентных рабочих процессов. Совместим с 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, совместимо с Anthropic

Использует формат Anthropic Messages API. Совместим с 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?"
      }
    ]
  }'

Направьте Anthropic SDK baseURL в 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?" }],
});

Некоторые провайдеры предоставляют через эти эндпойнты встроенные инструменты, включая веб-поиск на стороне сервера. См. Web Search для поддерживаемых моделей по каждому провайдеру и формата запроса, который использует каждая из них. См. каталог моделей для канонических идентификаторов моделей.

Укажите шлюз

По умолчанию запросы к моделям сторонних провайдеров направляются через шлюз AI Gateway вашей учетной записи, используемый по умолчанию. Чтобы использовать конкретный шлюз, укажите cf-aig-gateway-id заголовок. Для запросов Workers AI этот заголовок обязателен всегда.

# 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"
      }
    ]
  }'

В OpenAI SDK задайте заголовок через 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",
	},
});

Все функции AI Gateway, настроенные для этого шлюза (кеширование, ограничение частоты запросов, guardrails и логирование), применяются к запросу.

Настройка для каждого запроса

Используйте cf-aig-* заголовков для управления поведением AI Gateway в рамках отдельного запроса:

Header Тип Описание
cf-aig-skip-cache boolean Пропустить кеш для этого запроса.
cf-aig-cache-ttl число Cache TTL в секундах.
cf-aig-cache-key string Пользовательский ключ кэша.
cf-aig-collect-log boolean Включите или отключите логирование для этого запроса.
cf-aig-request-timeout число Тайм-аут запроса в миллисекундах.
cf-aig-max-attempts число Попытки повтора (максимум 5).
cf-aig-retry-delay число Задержка перед повторной попыткой в миллисекундах (максимум 5000).
cf-aig-backoff string Метод задержки: constant, linear, или exponential.
cf-aig-metadata Строка JSON Пользовательские метаданные для добавления к записи лога.

Подробнее об этих параметрах см. в Обработка запросов и Кеширование.