AI API

Kazzle AI API предоставляет один аутентифицированный endpoint для вызова любой поддерживаемой модели. Вы платите один раз кредитами из своего пространства — без отдельных аккаунтов OpenAI, Anthropic, Cloudflare Workers AI или других провайдеров, к которым мы маршрутизируем запросы. Все endpoints находятся под /ai/* на https://api.kazzle.app и принимают API-ключ kzl_ в заголовке Authorization. Инструкции по созданию ключа см. в разделе API-ключи. Созданные приложения Kazzle должны использовать этот API — см. AI в приложениях для подключения ключа к компоненту. Не просите пользователей предоставлять ключи провайдеров, если они явно не хотят использовать свой аккаунт провайдера.

Возможности

Endpoint	Модальность	Стандартизированный ввод	Стандартизированный вывод
`POST /ai/chat/completions`	Чат (текст, потоковая передача)	Совместимый с OpenAI `messages[]`	Совместимый с OpenAI `choices[]` или SSE-поток
`POST /ai/responses`	Responses API	Совместимый с OpenAI Responses	Совместимый с OpenAI Responses
`POST /ai/images/generations`	Изображение	`{ model, prompt, size?, output_format? }`	`{ images: [{ url? \| b64?, mimeType }] }`
`POST /ai/audio/speech`	Синтез речи	`{ model, text, voice?, format? }`	`audio/*` поток байтов
`POST /ai/audio/transcriptions`	Распознавание речи	`multipart/form-data` с `file` + `model`	`{ text }`
`POST /ai/video/generations`	Видео (асинхронно)	`{ model, prompt, ... }`	`{ id, status, pollUrl }`
`GET /ai/responses/{id}`	Асинхронный опрос	id ответа	результат в формате провайдера
`POST /ai/gateway`	Прямой проход	Любой Workers AI / нативный payload провайдера	Прямой ответ от upstream
`GET /ai/models`	Каталог	—	`{ models: [{ id, modality, pricing, ... }] }`

GET /ai/models — источник истины для определения, какие id моделей работают на каком endpoint. Прочитайте его в первую очередь, если разрабатываете против API.

Как работает вызов

Каждый оплачиваемый вызов проходит пять фаз. Вы не видите большинство из них — они отслеживаются на сервере, чтобы мы могли возвращать средства за неудачные вызовы и сообщать точное использование.

Фаза	Что произошло
`open`	Мы создали событие биллинга, привязанное к вашему запросу, но еще не вызвали upstream.
`recorded`	Upstream-провайдер ответил. У нас есть id логирования от Cloudflare AI Gateway. Стоимость еще не известна.
`priced`	Cloudflare сообщил финальную стоимость. Мы применили наш коэффициент и записали списание кредитов. Финальное состояние.
`failed`	Upstream-вызов не удался, или мы не смогли получить стоимость после 20 повторных попыток. Клиент не оплачивается. Финальное состояние.
`synced`	Событие с установленной ценой доставлено в нашу систему учета.

Каждый успешный ответ включает x-kazzle-ai-billing-event-id: airesp_... — сохраните его, если хотите позже сопоставить запрос с экспортом использования.

Биллинг и коэффициент

Мы взимаем cloudflare_cost_usd × (1 + markup). Коэффициент опубликован в Параметры → Биллинг → Тарифы. Вызовы, оцененные Cloudflare в $0 (бесплатный уровень Workers AI, промо), достигают фазы priced с нулевой стоимостью и никогда не оплачиваются. Резерв: вам нужно иметь как минимум $0.50 эквивалента в кредитах для выполнения вызова. Мы удерживаем это против вашего баланса до завершения вызова, затем рассчитываем фактическую стоимость.

Ошибки

Статус	Значение
`401`	Отсутствует или неверный API-ключ `kzl_`.
`402`	Недостаточно кредитов для резерва. Пополните в Параметры → Биллинг.
`4xx` от upstream	Перенаправлено как есть. Тело содержит ошибку провайдера. Клиент не оплачивается.
`5xx` от upstream	Перенаправлено как есть. Клиент не оплачивается.

Пример — генерация изображения

curl https://api.kazzle.app/ai/images/generations \
  -H "Authorization: Bearer kzl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-1",
    "prompt": "a single red dot on white",
    "size": "1024x1024"
  }'

{
  "images": [
    { "url": "https://...", "mimeType": "image/png" }
  ]
}

Пример — синтез речи

curl https://api.kazzle.app/ai/audio/speech \
  -H "Authorization: Bearer kzl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/tts-1","text":"hello world","voice":"alloy","format":"mp3"}' \
  --output speech.mp3

См. также

Справочник API — полные схемы запросов/ответов для каждого endpoint
API-ключи — создание и использование ключей kzl_
Биллинг — кредиты, планы и коэффициент, который мы применяем

О Kazzle

Работа

Браузер

Код

Приложения

Безопасность

Платформа

Возможности

Как работает вызов

Биллинг и коэффициент

Ошибки

Пример — генерация изображения

Пример — синтез речи

См. также

​Возможности

​Как работает вызов

​Биллинг и коэффициент

​Ошибки

​Пример — генерация изображения

​Пример — синтез речи

​См. также

Возможности

Как работает вызов

Биллинг и коэффициент

Ошибки

Пример — генерация изображения

Пример — синтез речи

См. также