메인 콘텐츠로 건너뛰기
Kazzle AI API는 지원하는 모든 모델을 호출할 수 있는 하나의 인증된 엔드포인트를 제공합니다. OpenAI, Anthropic, Cloudflare Workers AI 또는 다른 제공자별 계정 없이 스페이스 크레딧으로 한 번에 결제합니다. 모든 엔드포인트는 https://api.kazzle.app의 /ai/* 아래에 있으며 Authorization 헤더에서 kzl_ API 키를 받습니다. 생성 방법은 API 키를 참조하세요. 생성된 Kazzle 앱도 이 API를 사용해야 합니다. 앱용 Kazzle API 키를 만들고 Vault에 저장한 후 프로세스 컴포넌트에서 KAZZLE_API_KEY로 연결하고 서버 측 코드에서 https://api.kazzle.app/ai/*를 호출하세요. 사용자가 자신의 제공자 계정을 명시적으로 사용하려는 경우가 아니면 제공자 키를 요청하지 마세요.

​
기능

엔드포인트모달리티표준 입력표준 출력
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 with file + model{ text }
POST /ai/video/generations비디오 (비동기){ model, prompt, ... }{ id, status, pollUrl }
GET /ai/responses/{id}비동기 폴링response id제공자 형식 결과
POST /ai/gateway원본 통과모든 Workers AI / 제공자 네이티브 페이로드원본 업스트림 응답
GET /ai/models카탈로그—{ models: [{ id, modality, pricing, ... }] }
GET /ai/models는 어떤 모델 ID가 어떤 엔드포인트에서 작동하는지에 대한 신뢰할 수 있는 출처입니다. API에 대해 구축하는 경우 먼저 읽으세요.

​
호출 작동 방식

모든 청구 가능한 호출은 5단계를 거칩니다. 대부분은 보이지 않습니다 — 실패한 호출을 환불하고 정확한 사용량을 보고하기 위해 서버 측에서 추적됩니다.
단계발생한 일
open요청에 연결된 청구 이벤트를 생성했지만 아직 업스트림을 호출하지 않았습니다.
recorded업스트림 제공자가 반환했습니다. Cloudflare AI Gateway에서 로그 ID를 받았습니다. 비용은 아직 알려지지 않았습니다.
pricedCloudflare가 최종 비용을 보고했습니다. 마크업을 적용하고 크레딧 청구를 기록했습니다. 최종.
failed업스트림 호출이 실패했거나 20회 재시도 후 비용을 얻을 수 없습니다. 고객은 청구되지 않습니다. 최종.
synced가격 책정된 이벤트가 미터링 시스템에 전달되었습니다.
모든 성공한 응답에는 x-kazzle-ai-billing-event-id: airesp_...가 포함됩니다 — 나중에 요청을 사용량 내보내기와 연관시키려면 유지하세요.

​
청구 및 마크업

cloudflare_cost_usd × (1 + markup)을 청구합니다. 마크업은 설정 → 청구 → 요금에 게시됩니다. Cloudflare가 $0으로 가격을 책정한 호출(무료 Workers AI 계층, 프로모션)은 priced 단계에 도달하며 비용이 0이고 청구되지 않습니다. 예약: 호출을 하려면 최소 $0.50 상당의 크레딧이 필요합니다. 호출이 완료될 때까지 잔액에 대해 보유한 후 실제 비용을 정산합니다.

​
오류

상태의미
401누락되었거나 유효하지 않은 kzl_ API 키입니다.
402예약을 위한 크레딧이 부족합니다. 설정 → 청구에서 충전하세요.
4xx from upstream그대로 전달됩니다. 본문에는 제공자의 오류가 포함됩니다. 고객은 청구되지 않습니다.
5xx from 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 참조 — 모든 엔드포인트의 전체 요청/응답 스키마
  • API 키 — kzl_ 키 생성 및 사용
  • 청구 — 크레딧, 플랜 및 적용되는 마크업