AI 게이트웨이 (chat 및 generate)

AI 게이트웨이

AI 게이트웨이를 사용하면 배포된 FloopFloop 프로젝트가 타사 자격 증명 없이 관리형 LLM 엔드포인트를 호출할 수 있습니다. FloopFloop가 적절한 제공업체로 요청을 라우팅하고, 재시도 및 서킷 브레이킹을 처리하며, 프로젝트 소유자의 크레딧에서 차감하고, 대시보드를 위한 사용량을 기록합니다.

이것은 FloopFloop에서 빌드한 프로젝트 내의 AI 기능을 구동하는 것입니다. 프로젝트의 서버 측 코드에서 직접 호출할 수 있습니다.

대부분의 프로젝트는 이 원시 HTTP API를 사용할 필요가 없습니다.생성된 모든 프로젝트에는 아래에 문서화된 모든 내용을 래핑하는@floopfloop/ai SDK가 사전 설치되어 있습니다:

import { FloopAI } from "@floopfloop/ai";

const ai = new FloopAI({ apiKey: process.env.FLOOPFLOOP_AI_KEY! });

const reply = await ai.chat({ messages, model: "smart" });

FloopFloop 프로젝트 외부(커스텀 백엔드, 디버깅 스크립트, 또는 비 Node 런타임)에서 게이트웨이를 호출해야 하거나, 커스텀 클라이언트의 정확한 와이어 형식이 필요한 경우에 이 참조 문서를 활용하십시오.

인증: 프로젝트 AI 키

게이트웨이는 접두사 flp_sk_를 가진 프로젝트 범위키를 사용하며, 나머지 API에서 사용하는 사용자 수준 flp_ 키와는 별개입니다. 프로젝트당 하나의 활성 키가 존재하며, 프로젝트 생성 시 자동으로 프로비저닝됩니다.

• 대시보드의 Project settings → AI에서 키를 찾거나 교체하십시오. 교체 시 새 flp_sk_ 값이 생성되고, 이전 값이 취소되며, 실행 중인 프로젝트가 이를 적용하도록 재배포가 트리거됩니다.
• FloopFloop는 활성 키를 환경 변수 FLOOPFLOOP_AI_KEY로서 프로젝트의 빌드 번들에 포함시키므로, 서버 측 코드가 시크릿 왕복 없이process.env.FLOOPFLOOP_AI_KEY를 통해 읽을 수 있습니다.
• 모든 요청은 표준 Bearer 방식을 사용합니다:

  Authorization: Bearer flp_sk_…

• 서버 측 전용.키를 클라이언트 측 코드에 포함시키지 마십시오 — 페이지 소스에 접근할 수 있는 모든 사람이 프로젝트의 크레딧을 소진할 수 있습니다.

채팅 완성

POST /api/v1/ai/chat

구조화된 메시지 목록을 사용한 OpenAI/Anthropic 스타일 채팅입니다.

요청 본문:

{
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user",   "content": "Summarise this in one sentence: ..." }
  ],
  "model":       "auto",   // optional alias; default "auto" picks the best fit
  "system":      "...",    // optional, alternative to a system role message
  "temperature": 0.7,      // optional, 0-2
  "max_tokens":  1024,     // optional, clamped to plan limit
  "stream":      false     // optional, default false (see streaming below)
}

응답 (200, 비스트리밍):

{
  "content": "...",
  "model":   "auto",
  "usage": {
    "input_tokens":      123,
    "output_tokens":     45,
    "total_tokens":      168,
    "credits_used":      0.21,
    "credits_remaining": 4837.79
  },
  "finishReason": "end_turn"
}

model이 "auto"인 경우, 게이트웨이가 요청 복잡성을 분류하고 적절한 크기의 모델을 선택합니다. 다른 지원 별칭은:

하드코딩된 공급업체 모델 id보다 별칭을 사용하는 것이 권장됩니다 — 플랫폼은 공급업체가 변경될 때 별칭을 통해 재라우팅하지만, 하드코딩된 id는 해당 모델이 업스트림에서 종료되는 날부터 실패하기 시작합니다.

단일 프롬프트 생성

POST /api/v1/ai/generate

/chat와 동일한 모델 라우팅이지만, 메시지 배열 대신 단일 일반 텍스트 prompt를 사용합니다. 완성 스타일 사용 사례에 편리합니다.

{
  "prompt":      "Write a haiku about the moon",   // required, ≤ 500_000 chars
  "system":      "...",                            // optional
  "model":       "auto",                           // optional
  "temperature": 0.7,                              // optional
  "max_tokens":  1024,                             // optional
  "stream":      false                             // optional
}

응답 형식은 /chat과 동일합니다.

스트리밍 (SSE)

두 엔드포인트 중 하나에 "stream": true를 전달하여text/event-stream 응답을 수신합니다. 각 프레임은data: 줄의 JSON입니다:

data: {"text": "Once "}

data: {"text": "upon "}

data: {"text": "a time"}

data: {"usage": { "input_tokens": 14, "output_tokens": 47, "total_tokens": 61, "credits_used": 0.07, "credits_remaining": 4837.93 }, "finishReason": "end_turn"}

data: [DONE]

최종 usage 프레임은 [DONE] 전에 전송되므로 호출자는 별도의 요청 없이 비용을 기록할 수 있습니다. 스트리밍 중간에 업스트림 오류가 발생하면 스트림은 data: {"error": "..."}를 내보낸 후 [DONE]을 내보냅니다 — 이미 생성된 토큰은 여전히 청구됩니다.

임베딩 (아직 미제공)

POST /api/v1/ai/embed

현재 501 NOT_IMPLEMENTED를 반환합니다. 엔드포인트는 게이트웨이가 출시되기 전에 SDK가 메서드를 스텁할 수 있도록 예약되어 있습니다; 아직 의존하지 마십시오.

한도 및 예산

각 프로젝트 AI 키는 크레딧 잔액 외에 두 가지 스로틀링 레이어를 가집니다:

• 분당 요청 수 — Project settings → AI에서 설정 가능하며, 기본값은 10 RPM입니다. 초과 시 Retry-After헤더와 함께 429 RATE_LIMITED를 반환합니다.
• 일일 토큰 예산— UTC 자정에 초기화되며, 기본값은 하루 10,000 토큰입니다. 초과 시 429 BUDGET_EXCEEDED를 반환합니다.
• 요청당 입력 크기는 플랜의 컨텍스트 한도로 제한됩니다. 초과 입력은 메시지에 한도가 포함된 400 INPUT_TOO_LARGE를 반환합니다.

이 외에도 모든 호출은 모델의 설정된 비율로 (입력 + 출력) 토큰당 가격이 책정된 크레딧을 차감합니다. 프로젝트 소유자의 크레딧 잔액이 0에 도달하면 요청은 402 INSUFFICIENT_CREDITS를 반환합니다.

게이트웨이 전용 오류 코드

모든 게이트웨이 응답 — 성공 또는 실패 — 에는X-Request-Id 헤더가 포함됩니다. 지원팀이 프로젝트별 AI 사용량 로그에서 추적을 찾을 수 있도록 문제 보고 시 이를 인용하십시오.