Celon

API Reference

API 레퍼런스

게이트웨이가 실제로 제공하는 엔드포인트 전체입니다. Base URL은 로컬 기준 http://localhost:8787이며, 인증은 Authorization: Bearer <key> 또는 x-api-key 헤더를 사용합니다. admin 엔드포인트는 CELON_MASTER_KEY로만 접근할 수 있습니다.

오류 형식

모든 오류는 OpenAI 호환 envelope로 반환됩니다. 스트리밍 도중 업스트림 오류가 발생하면 같은 형태의 error 객체가 SSE 데이터로 전송됩니다.

error.json
{
  "error": {
    "message": "Monthly budget exceeded",
    "type": "insufficient_quota",
    "code": "budget_exceeded"
  }
}
상태code의미
400—본문이 JSON이 아니거나 필수 필드 누락
401invalid_api_key키 누락·무효·비활성화
402budget_exceeded월 예산 초과 (reject 정책)
403master_key_requiredadmin 엔드포인트를 일반 키로 호출
404model_not_found카탈로그에 없는 모델 id
502upstream_unavailablefallback 체인의 모든 후보 실패

POST /v1/chat/completions

OpenAI 호환 채팅 완성. 아래 표에 없는 OpenAI 파라미터도 검증 없이 어댑터로 그대로 통과됩니다.

필드타입설명
modelstring · 필수celon/auto · celon/fusion · 카탈로그 id(vendor/model)
messagesMessage[] · 필수OpenAI chat 포맷. text·image_url 콘텐츠 파트 지원
temperaturenumber업스트림에 그대로 전달. ≤ 0.3이어야 캐시 대상 (캐싱 참조)
top_p · stop · presence_penalty · frequency_penalty · seed · userpassthrough업스트림에 그대로 전달
max_tokens / max_completion_tokensnumber출력 토큰 상한
streambooleanSSE 스트리밍 (아래 형식 참조)
tools · tool_choiceobjectfunction calling — 사용 시 캐시 제외, 분류기에 구조화 출력 신호
response_formattext | json_object | json_schema구조화 출력 — 분류기 점수에 반영
celonobject라우팅/캐시 옵션 — dial, anchor, session_id, context_compression, tier, no_cache, no_pii_mask, fallbacks (스마트 라우팅 참조)
terminal
curl http://localhost:8787/v1/chat/completions \
  -H "Authorization: Bearer sk-celon-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "celon/auto",
    "messages": [{ "role": "user", "content": "안녕!" }],
    "temperature": 0.2,
    "stream": false
  }'

응답에는 celon 메타 필드와 x-celon-* 헤더(x-celon-model · x-celon-tier · x-celon-cache · x-celon-dial · x-celon-sticky · x-celon-guardrail-findings 등)가 붙습니다 — 전체 헤더 표와 필드 정의는 응답 메타데이터를 참조하세요.

SSE 스트리밍 형식

stream: true이면 text/event-stream으로 OpenAI 호환 청크가 전송됩니다. 마지막 데이터 청크는 choices가 빈 배열이고 usage와 celon 메타를 담으며, 그 뒤 data: [DONE]으로 종료됩니다.

event-stream
data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1750000000,"model":"meta-llama/llama-4-maverick","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1750000000,"model":"meta-llama/llama-4-maverick","choices":[{"index":0,"delta":{"content":"안녕하세요"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1750000000,"model":"meta-llama/llama-4-maverick","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1750000000,"model":"meta-llama/llama-4-maverick","choices":[],"usage":{"prompt_tokens":21,"completion_tokens":96,"total_tokens":117},"celon":{"model":"meta-llama/llama-4-maverick","provider":"deepinfra","tier":2,"classifier_score":0.41,"cache_hit":null,"cost_usd":0.000122,"saved_usd":0.003886,"latency_ms":842,"pii_masked":0,"attempts":[],"dial":"balanced","sticky":false,"guardrails":{"mode":"mask","findings":0,"blocked":false}}}

data: [DONE]

POST /v1/embeddings

OpenAI 호환 임베딩. model은 생략 시 openai/text-embedding-3-small이며, 카탈로그 id와 raw OpenAI 이름(text-embedding-3-large) 둘 다 받습니다. input은 string 또는 string[]입니다. 응답의 celon 필드에는 provider · cache_hit · cost_usd · latency_ms가 담깁니다.

terminal
curl http://localhost:8787/v1/embeddings \
  -H "Authorization: Bearer sk-celon-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/text-embedding-3-small",
    "input": ["첫 번째 문장", "두 번째 문장"]
  }'

GET /v1/models

가상 모델(celon/auto, celon/fusion)과 전체 카탈로그를 반환합니다. 항목마다 celon 메타로 티어, $/1M 가격, 컨텍스트 윈도, modality, 그리고 현재 서빙 가능 여부(available — 해당 프로바이더 키가 설정됐는지)를 알려줍니다.

terminal
curl http://localhost:8787/v1/models \
  -H "Authorization: Bearer sk-celon-…"
response.json (일부)
{
  "object": "list",
  "data": [
    { "id": "celon/auto",   "object": "model", "owned_by": "celon",
      "celon": { "tier": null, "pricing": null, "modality": "text", "available": true } },
    { "id": "celon/fusion", "object": "model", "owned_by": "celon",
      "celon": { "tier": 0, "pricing": null, "modality": "text", "available": true } },
    { "id": "anthropic/claude-fable-5", "object": "model", "owned_by": "anthropic",
      "celon": { "tier": 1, "pricing": { "inputPerM": 10, "outputPerM": 50 },
                 "context_window": 500000, "modality": "text", "available": true } }
  ]
}

Admin API

POST /admin/orgs

조직을 생성합니다. zdr(본문 미저장 정책), monthlyBudgetUsd(하드 캡, null=무제한)를 설정합니다.

terminal
curl -X POST http://localhost:8787/admin/orgs \
  -H "Authorization: Bearer $CELON_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "acme", "zdr": true, "monthlyBudgetUsd": 5000 }'

POST /admin/keys

가상 키(sk-celon- + 48 hex)를 발급합니다. 예산(monthlyBudgetUsd, overBudgetBehavior), PII 마스킹, ZDR, 라우팅 정책(routing — dial 기본 인텐트 다이얼과 anchorModel 앵커 상한), 가드레일 정책(guardrails — mode block | mask | shadow, 탐지기별 detectors, 출력 검사 streamOutput), BYOK 업스트림 키(byokKeys)를 키 단위로 설정합니다. 요청 본문의 celon.dial·celon.anchor는 키 정책보다 우선합니다.

terminal
curl -X POST http://localhost:8787/admin/keys \
  -H "Authorization: Bearer $CELON_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "org_abc123",
    "name": "prod-backend",
    "monthlyBudgetUsd": 1000,
    "overBudgetBehavior": "downgrade",
    "piiMasking": true,
    "zdr": true,
    "routing": {
      "dial": "strict-quality",
      "anchorModel": "anthropic/claude-fable-5"
    },
    "guardrails": {
      "mode": "mask",
      "detectors": { "pii": true, "secrets": true, "injection": true, "presidio": false },
      "streamOutput": true
    },
    "byokKeys": {}
  }'
# 응답의 평문 키(sk-celon-…)는 이 응답에서만 확인 가능

GET /admin/audit

가드레일 판정의 불변(append-only) 감사 로그를 최신순 으로 반환합니다 — 모드, 카테고리별 탐지 건수, 차단 여부만 담기고 프롬프트·응답 본문은 없습니다 (ZDR). 쿼리 파라미터: orgId(조직 필터), limit(기본 100). 정책과 모드 설명은 거버넌스 — Audit Trail을 참조하세요.

terminal
curl "http://localhost:8787/admin/audit?orgId=org_abc123&limit=50" \
  -H "Authorization: Bearer $CELON_MASTER_KEY"
response.json
{
  "items": [
    {
      "ts": 1750000000000,
      "orgId": "org_abc123",
      "keyId": "key_7f3d",
      "requestId": "chatcmpl-abc",
      "mode": "mask",
      "findings": 2,
      "byCategory": { "PHONE": 1, "SECRET": 1 },
      "blocked": false
    }
  ]
}

GET /admin/usage/summary

조직 단위 사용량 요약 — 요청 수, 총비용, 총절감액, 캐시 hit율, 티어별 · 모델별 집계를 반환합니다.

terminal
curl "http://localhost:8787/admin/usage/summary?orgId=org_abc123" \
  -H "Authorization: Bearer $CELON_MASTER_KEY"
response.json
{
  "requests": 1284,
  "totalCostUsd": 12.4,
  "totalSavedUsd": 63.1,
  "cacheHitRate": 0.23,
  "byTier": { "1": 96, "2": 512, "3": 676 },
  "byModel": {
    "google/gemini-3-flash": { "requests": 512, "costUsd": 4.2 }
  }
}

GET /healthz

라이브니스 체크. 배포 환경의 health probe에 사용합니다.

terminal
curl http://localhost:8787/healthz
# → { "status": "ok" }

GET /metrics

프로세스 내 메트릭 스냅샷(JSON) — 총 요청 수, 분당 요청 수, 엔드포인트 · 티어별 카운트, 캐시 hit율, 지연 p50/p95 (최근 1,000개 샘플 기준).

terminal
curl http://localhost:8787/metrics
response.json
{
  "uptimeSeconds": 3600,
  "requests": { "total": 1284, "ok": 1279, "error": 5, "perMinute": 21 },
  "byEndpoint": { "chat": 1201, "embeddings": 83 },
  "byTier": { "1": 96, "2": 512, "3": 676 },
  "cache": { "exactHits": 214, "semanticHits": 81, "hitRate": 0.23 },
  "latencyMs": { "p50": 640, "p95": 2210, "avg": 812, "samples": 1000 }
}