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

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

EndpointМодальностьСтандартный вводСтандартный вывод
POST /ai/chat/completionsЧат (текст, потоковая передача)OpenAI-совместимый messages[]OpenAI-совместимый choices[] или SSE поток
POST /ai/responsesResponses APIOpenAI 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 провайдераПрямой ответ провайдера
GET /ai/modelsКаталог—{ models: [{ id, modality, pricing, ... }] }
GET /ai/models — источник истины для того, какие id моделей работают на каких endpoints. Прочитайте его в первую очередь, если разрабатываете против API.

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

Каждый платный вызов проходит пять фаз. Вы не видите большинство из них — они отслеживаются на сервере, чтобы мы могли возвращать средства за неудачные вызовы и сообщать точное использование.
ФазаЧто произошло
openМы создали событие биллинга, привязанное к вашему запросу, но еще не вызвали провайдера.
recordedПровайдер ответил. У нас есть id логирования от Cloudflare AI Gateway. Стоимость еще не известна.
pricedCloudflare сообщил финальную стоимость. Мы применили наценку и записали списание кредитов. Финальное.
failedВызов провайдера не удался или мы не смогли получить стоимость после 20 повторов. Клиент не заряжается. Финальное.
syncedСобытие с ценой доставлено в нашу систему учета.
Каждый успешный ответ включает x-kazzle-ai-billing-event-id: airesp_... — сохраните его, если хотите позже сопоставить запрос с экспортом использования.

​
Биллинг и наценка

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

​
Ошибки

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

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

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 Reference — полные схемы запросов/ответов для каждого endpoint
  • API keys — создание и использование ключей kzl_
  • Billing — кредиты, планы и наценка, которую мы применяем