API 문서

이 API 스택이 실제 서비스에서 어떻게 동작하는지 궁금하다면 — 같은 엔진으로 구동되는 AI 사주 앱 인타(INTA)에서 사주 분석·AI 대화를 직접 체험해 보세요. 인타가 이 API의 살아있는 레퍼런스입니다. 인타의 AI 음성 응답(TTS)도 같은 스택으로 구동됩니다 — 음성 API는 추후 공개 예정입니다.

Quickstart

FLOAT AI API는 기억하는 AI, 사주 분석, LLM 리셀링을 제공합니다. 다음 3단계를 따르세요:

API 키 발급 - 대시보드에서 API 키를 발급받습니다.
요청 보내기 - 아래의 예제를 따라 POST 요청을 보냅니다.
응답 처리 - JSON 응답에서 사주 정보를 추출합니다.

curl -X POST https://api.float.do/api/v1/partners/v1/manseryeok \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "year": 1990,
    "month": 1,
    "day": 15,
    "hour": 14,
    "minute": 30,
    "timezone": "Asia/Seoul",
    "gender": "male"
  }'

API Reference

FLOAT AI API는 기억하는 AI, 사주 분석, LLM 리셀링을 제공합니다.

RIDM Memory API

엔드유저별 대화 기억을 호스팅하면서 ridm/* 모델에 메모리 레이어를 추가합니다. 메모리는 ridm/* 전용이며, OpenAI/Google 모델은 리셀(원본 그대로) — 같은 모델, 다른 상품입니다. 유튜브 자막 자동 주입 기능도 지원합니다.

세션이 없습니다 — 무한 세션. 같은 user로 호출하면 대화는 끝없이 이어집니다. 매 호출마다 서버가 historyCount개의 최근 대화 턴과 recallCount개의 장기 기억(요약·프로필·기억한 사실·진행 중 고민)을 자동으로 붙여 주므로, 파트너는 새 메시지 하나만 보내면 됩니다. 얼마나 멀리까지 참조할지는 두 숫자로 조절하고, 엔드유저별 기억 총량은 memoryCap으로 제한합니다. 히스토리를 직접 관리하고 싶으면 historyCount를 생략하고 OpenAI 방식대로 messages에 이전 대화를 실어 보내면 됩니다.

긴 대화도 비용이 선형으로 늘지 않습니다. 오래된 어시스턴트 턴은 자동으로 압축됩니다 — 최신 2턴은 원문 그대로, 그 이전은 500자 → 200자로 단계적으로 줄여 입력 토큰을 아낍니다(사용자 턴은 그대로). 그리고 "저번에 ~라고 했잖아"처럼 과거 발언을 묻는 질문에는 서버가 저장된 실제 대화를 검색해 날짜·화자와 함께 인용합니다(recalledMemories에 포함) — 기록이 없으면 지어내지 않고 없다고 답합니다.

LLM API (리셀) vs RIDM Memory API — 무엇이 다른가

같은 모델, 다른 상품 — 접두사만 다르고 나머지는 동일합니다. 응답에 recalledMemories·memorySaved가 붙으면 RIDM 경로입니다.

기능	LLM API (리셀)	RIDM Memory API
모델 선택	`openai/`, `google/` 등	`ridm/*` (접두사 붙임)
응답 형식	원본 모델 응답 그대로 (OpenAI 호환)	원본 모델 + 메모리 필드
`user` 파라미터	무시됨	필수 (endUserId, 기억 유지)
대화 기억·요약·프로필 회상	✗	✓ (`recallCount`·`memoryCap`)
문서 처리	`fileIds` 명시 주입만	`fileIds` 명시 + 자동 회상
유튜브 링크 처리	`youtube:true` 지원	`youtube:true` 지원
감정 분석 (`emotion`)	무시됨 (403 아님)	✓ (요약 사이클 포함)
모더레이션	user 메시지만	system + user 메시지
`systemPrompt` 제한	표준 (8,000자 포함)	8,000자 검증 (ridm 전용)
응답 추가 필드	`costUsd` (비용)	`recalledMemories`, `memorySaved`, `filesRecalled`, `emotion`
가격	원가 × 환율 × 1.30	리셀가 × 1.30 (기억 유지·회상·감정·파일 자동회상 전부 포함, 기능별 추가 과금 없음)
예외	—	`ridm/saju-report`: 메모리 없음 → 리셀 마진만, chat 불가 (리포트 전용)

코드 예시 비교

// LLM API (리셀) — 메모리 없음
{
  "model": "openai/gpt-5.6-terra",
  "messages": [{ "role": "user", "content": "..." }]
}

// RIDM Memory API — 기억 엔진 포함
{
  "model": "ridm/gpt-5.6-terra",  // 접두사만 다름
  "user": "user_123",              // 필수 (기억 유지)
  "messages": [{ "role": "user", "content": "..." }]
}

// 응답에서 차이
// 리셀: { "id": "...", "choices": [...], "usage": {...}, "costWon": 1, "costUsd": 0.00045 }
// RIDM: { "id": "...", "choices": [...], "usage": {...}, "costWon": 2, "recalledMemories": [...], "memorySaved": true }

POST /api/v1/partners/v1/chat/completions

메모리를 지닌 대화형 LLM 호출. 같은 user/endUserId로 호출하면 과거 맥락이 유지됩니다.

요청 파라미터

파라미터	타입	필수	설명
`model`	string	O	모델명. RIDM: `ridm/gpt-5.6-terra` 등 / 리셀: `openai/gpt-5.2`, `google/gemini-3.5-flash` 등
`user`	string	O	파트너사가 발급한 엔드유저 ID (endUserId — 같은 값이면 기억 유지)
`messages`	array	O	OpenAI 형식 메시지 배열 [{ "role": "user", "content": "..." }, ...]
`systemPrompt`	string		시스템 지시문 (선택, 최대 8,000자 — ridm/* 에서 검증)
`youtube`	boolean		true이면 마지막 메시지의 유튜브 링크 자막 자동 주입
`stream`	boolean		스트리밍 응답 여부 (기본값: false)
`max_tokens`	number		최대 출력 토큰. gpt-5.1 이상·5.4·5.5·5.6 계열은 서버가 추론을 끄고(reasoning_effort none) 호출해 요청한 만큼 본문이 나옵니다. 추론을 끌 수 없는 모델(gpt-5·gpt-5-mini·gpt-5-nano·o3·o3-mini·o4-mini)은 서버가 추론 예산 1,500토큰을 더해 호출하며, 이 추론 토큰도 출력으로 과금됩니다.
`historyCount`	number		서버가 자동으로 붙여 줄 최근 대화 턴 수 (1~50). 지정하면 `messages`에는 새 메시지만 보내면 됩니다. 생략 시 서버 히스토리를 붙이지 않고 `messages`의 마지막 10개만 사용합니다.
`recallCount`	number		질문과 관련된 장기 기억(과거 요약)을 몇 개까지 회상할지 (0~20, 기본 3). 프로필·기억한 사실·진행 중 고민은 항상 포함됩니다.
`memoryCap`	number		엔드유저별 기억 컨텍스트 상한 (K 토큰, 10~1000, 기본 100). 한 번 지정하면 그 유저에게 고정됩니다.

응답 예시

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1629292800,
  "model": "ridm/gpt-5.6-terra",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "안녕하세요! 이전 대화를 기억하고 있습니다..."
      },
      "finish_reason": "stop",
      "index": 0
    }
  ],
  "usage": {
    "prompt_tokens": 1250,
    "completion_tokens": 320,
    "total_tokens": 1570
  },
  "costWon": 45,
  "recalledMemories": [...],
  "memorySaved": true,
  "youtubeUsed": ["https://youtube.com/watch?v=abc123"]
}

유튜브 자막 주입: youtube:true일 때, 마지막 메시지의 유튜브 링크에서 자막을 추출해 입력 토큰에 포함합니다. 자막을 못 얻으면 주입 없이 대화가 그대로 진행되며 응답의 youtubeUsed가 빈 배열로 옵니다 (단독 유튜브 요약 API만 400 무과금).

원본 모델 호환: model 값에 openai/* 또는 google/*를 지정하면 원본 모델이 메모리 기능 없이 그대로 호출됩니다 (원가 + 30%).

프롬프트 캐시 할인: OpenAI 계열 모델(openai/*, ridm/gpt-*)은 같은 앞부분(1,024토큰 이상)을 반복해 보내면 업스트림 캐시에 맞은 입력 토큰을 입력가의 30%로 과금합니다. 응답 usage.prompt_tokens_details.cached_tokens와 GET /usage/logs의 cachedTokens로 확인할 수 있고, 캐시 적중 여부는 업스트림 정책에 따라 호출마다 달라질 수 있습니다. Google 모델은 캐시가 없어 전체 입력가가 적용됩니다.

REPORT_ONLY_MODEL 제외: ridm/saju-report는 메모리 없는 원샷 전용이라 이 엔드포인트에서 사용 불가 (400).

LLM API (리셀)

openai/*, google/* 등 원본 LLM 모델을 리셀(메모리 없이 원본 응답 그대로). 리셀 모델 요청의 user, recallCount, memoryCap, summaryEvery, emotion은 무시되며, 응답에 메모리 필드(recalledMemories 등)가 없습니다. 가격 = 원가 × 환율 × 1.30.

POST /api/v1/partners/v1/chat/completions

요청 파라미터 (메모리 레이어 없음)

파라미터	타입	필수	설명
`model`	string	O	`ridm/gpt-5.6-terra`(기억) · 리셀은 `openai/gpt-5.2`, `google/gemini-3.5-flash` 등 — 전체 목록은 요금
`messages`	array	O	OpenAI 형식 메시지
`temperature`	number		0.0~2.0 (기본 1.0)
`emotion`	boolean		무시됨
`summaryEvery`	number		무시됨

사용 예시 (OpenAI SDK 호환)

const client = new OpenAI({
  apiKey: 'your-float-api-key',
  baseURL: 'https://api.float.do/api/v1/partners/v1',
  defaultHeaders: { 'X-Partner-Api-Key': 'your-float-api-key' }
});

const response = await client.chat.completions.create({
  model: 'openai/gpt-5.6-terra',
  messages: [{ role: 'user', content: 'Hello' }]
});
// RIDM 모델 예: model: 'ridm/gpt-5.6-terra'

응답

원본 모델의 응답을 그대로 반환합니다. OpenAI 호환 스키마.

AI 사주 리딩 API

생성형 AI가 사주를 분석해 맞춤형 운세 해석과 조언을 제공합니다. 토큰 기반 과금이며, 해석 결과만 반환합니다.

POST /api/v1/partners/v1/reading

사주를 기반으로 AI 사주 리딩을 생성합니다. 내부 프롬프트와 이론은 비공개입니다.

요청 파라미터

파라미터	타입	필수	설명
`speed`	string		`fast`(기본, 빠른 응답) \| `value`(응답 느림, 요금 20% 할인)
`year`	number	O	출생년 (예: 1990)
`month`	number	O	출생월 (1-12)
`day`	number	O	출생일 (1-31)
`hour`	number		출생시간 (0-23, 선택사항)
`minute`	number		출생분 (0-59, 선택사항)
`gender`	string	O	성별 ("male" 또는 "female")
`question`	string	O	운세 풀이에 대한 질문 (예: "내 인생 경로는?")
`tone`	string		응답 톤 ("formal", "casual", "warm", 기본값: "warm")
`maxLength`	number		최대 응답 길이 (기본값: 800, 최대: 2000)

응답 예시

{
  "success": true,
  "data": {
    "interpretation": "당신의 사주에서 보이는 특징은...",
    "usage": {
      "inputTokens": 450,
      "outputTokens": 280
    },
    "costPoints": 18
  }
}

주의사항

해석 결과만 반환됨: 응답에는 생성된 운세 해석 텍스트만 포함되며, 내부 프롬프트나 사주 이론은 노출되지 않습니다.
토큰 기반 과금: 요청과 응답의 토큰 수합에 따라 포인트가 차감됩니다. costPoints는 소비된 포인트를 나타냅니다.
타임존 고정: 시간이 제공되지 않으면 자동으로 정오(12시)로 설정됩니다.

AI 사주 리딩 · 메모리 API

엔드유저별 대화 기억을 호스팅하고, 재방문 시 과거 맥락을 이어서 풀이합니다. 개인화된 지속적 상담 경험을 제공합니다. 가격은 AI 사주 리딩의 2배 단가입니다.

POST /api/v1/partners/v1/reading/memory

엔드유저별 기억을 바탕으로 AI 사주 리딩을 생성합니다.

요청 파라미터

파라미터	타입	필수	설명
`endUserId`	string	O	파트너사가 발급한 엔드유저 ID (고유값 필수)
`speed`	string		`fast`(기본, 빠른 응답) \| `value`(응답 느림, 요금 20% 할인)
`year`	number	O	출생년 (예: 1990)
`month`	number	O	출생월 (1-12)
`day`	number	O	출생일 (1-31)
`hour`	number		출생시간 (0-23, 선택사항)
`minute`	number		출생분 (0-59, 선택사항)
`gender`	string	O	성별 ("male" 또는 "female")
`question`	string	O	운세 풀이에 대한 질문
`tone`	string		응답 톤 ("formal", "casual", "warm", 기본값: "warm")
`tagFilter`	string[]		검색할 메모리 태그 필터 (선택사항)

응답 예시

{
  "success": true,
  "data": {
    "interpretation": "당신의 사주에서 보이는 특징은...",
    "memory": {
      "summary": "과거 상담 요약",
      "messageCount": 5
    },
    "usage": {
      "inputTokens": 750,
      "outputTokens": 380
    },
    "costPoints": 36
  }
}

메모리 관리 API

엔드포인트	메서드	설명
/api/v1/partners/v1/reading/memory/{endUserId}	GET	엔드유저의 저장된 메모리 조회
/api/v1/partners/v1/reading/memory/{endUserId}/messages	GET	엔드유저의 메시지 목록 조회
/api/v1/partners/v1/reading/memory/{endUserId}/search	POST	메모리 내 특정 내용 검색 (₩100/회)
/api/v1/partners/v1/reading/memory/{endUserId}	DELETE	엔드유저의 모든 메모리 삭제

주의사항

2배 단가: 메모리 호스팅으로 인해 입력/출력 토큰 단가가 2배입니다.
endUserId 필수: 각 엔드유저는 고유한 ID를 가져야 하며, 같은 ID로 호출 시 과거 맥락이 유지됩니다.
메모리 보관: 저장된 메모리는 명시적 삭제 시까지 보관됩니다.

사주 리포트 API (990st)

990 스타일(990st) — 질문 없이 버튼 한 번으로 총평·재물·연애·대운까지 모든 사주 해석이 한 번에 나옵니다. 대화형(reading)과 별개의 단품 결제형 상품. 전용 모델 ridm/saju-report(FLOAT 자체 리포트 특화 모델 — 원샷 상품 특성상 메모리 미장착)가 기본입니다. 리딩 API의 응답 상한은 2,000자입니다 — 그 이상의 장문 해설(최대 12섹션, 약 6,000자)은 이 리포트 API를 사용하세요.

POST /api/v1/partners/v1/reading/report

생년월일(또는 사주)을 넣으면 섹션별 마크다운 사주 리포트를 반환합니다.

요청 파라미터

파라미터	타입	필수	설명
year / month / day	number	birth 또는 saju 중 하나	양력 생년월일
hour / minute	number	선택	미제공 시 정오 처리
gender	string	필수(birth 시)	male \| female
saju	object	birth 또는 saju 중 하나	4기둥 직접 입력 (reading과 동일 형식)
tone	string	선택	warm(기본) \| casual \| formal
persona	string	선택	말투·캐릭터 지시 (최대 2,000자 — 이 길이만 입력 과금)
sections	string[]	선택	섹션 제목 목록 (최대 12개). 기본: 총평·타고난 기질·재물운·연애·인연·직업·적성·올해와 내년·10년 대운 흐름·마지막 한 줄 처방

응답

{
  "success": true,
  "data": {
    "report": "## 총평\n...",        // 섹션별 마크다운 전문
    "sections": ["총평", "..."],
    "sajuSource": "computed",
    "usage": { "inputTokens": 5756, "outputTokens": 2019 },
    "costPoints": 154,
    "model": "ridm/saju-report"
  }
}

사주 주입 무료: 만세력 계산·주입과 시스템 프롬프트는 과금하지 않습니다. 입력 과금은 persona 길이만, 출력은 실사용 토큰입니다.
실측 비용: 기본 8섹션(약 3,000자) 리포트 1회 약 100P (출력 ₩45,000/1M 기준).
X-Idempotency-Key 헤더로 재시도 시 중복 과금을 방지할 수 있습니다.

유튜브 요약 API

유튜브 동영상의 자막을 추출하여 요약 및 Q&A 분석을 제공합니다. 자막이 없는 경우 400 에러(무과금).

POST /api/v1/partners/v1/youtube/summary

요청 파라미터

파라미터	타입	필수	설명
`url`	string	O	유튜브 URL (예: https://www.youtube.com/watch?v=dQw4w9WgXcQ)
`question`	string		특정 질문 (선택사항 — 있으면 Q&A 모드)
`maxLength`	number		최대 요약 길이 (기본: 1,000, 최대: 4,000)
`tone`	string		톤 선택: warm \| casual \| formal (기본: warm)
`lang`	string		언어 (기본: ko, en, ja, zh 등)

응답 예시

{
  "success": true,
  "data": {
    "summary": "## 0:00~1:30 오프닝\n영상 제목 설명...\n\n## 1:30~5:00 본론\n...",
    "video": {
      "videoId": "dQw4w9WgXcQ",
      "title": "Video Title",
      "channel": "Channel Name",
      "duration": 420
    },
    "transcriptSource": "supadata",
    "usage": {
      "promptTokens": 7059,
      "completionTokens": 1384
    },
    "costPoints": 78,
    "model": "ridm/gpt-5.6-terra"
  }
}

주의사항

자막 필수: 자막이 없으면 TRANSCRIPT_UNAVAILABLE 400 (무과금).
실측 비용: 20~30분 영상 1회 약 80P (토큰 포함).
리딩 연동: AI 사주 리딩 메모리 API에서 youtube:true 옵션으로도 동일 기능 사용 가능.

기능 켜고 끄기

유튜브 요약 API는 파트너 계정 및 요청 단위로 옵트인할 수 있습니다. 콘솔의 "기능 설정"에서 전역 활성화 상태를 관리하며, chat/reading 요청 시 youtube:true를 명시해 요청별로 활성화합니다.

전역 비활성: 403 { code: 'FEATURE_DISABLED', feature: 'youtube' } 응답
요청 단위: youtube:true 미지정 또는 false = 유튜브 주입 안 함

문서 처리 API

PDF, Word, Excel, CSV, 텍스트, Markdown, HWP 등 다양한 형식의 문서를 업로드하고, AI로 분석하여 맥락 기반 지식베이스에 적재할 수 있습니다. 문서는 자동 추출되며, "AI 분석" 옵션을 활성화하면 문서를 맥락 단위로 분할하고 각 구간의 요약과 검색 태그를 생성하여 저장합니다.

지원 형식 및 제한

항목	사양
지원 형식	.pdf, .docx, .xlsx, .csv, .txt, .md, .hwpx
최대 파일 크기	10 MB
최대 추출 텍스트	200,000자 (초과 시 `charsCapped: true` 표시)
요청당 최대 파일	5개 (`fileIds`)
chat 주입 크기	파일당 최대 40,000자 / 전체 80,000자
분석 청크 범위	3~8구간 (장문서 40,000자 이상 시 2회 패스)
태그 범위	구간당 최대 10개 태그, 전체 합산 최대 10개

엔드포인트

메서드	경로	설명
POST	`/api/v1/partners/v1/files`	파일 업로드 (multipart)
GET	`/api/v1/partners/v1/files`	파일 목록 조회 (파트너 스코프)
GET	`/api/v1/partners/v1/files/:id`	파일 상세 조회 (추출 텍스트 포함)
DELETE	`/api/v1/partners/v1/files/:id`	파일 삭제

파일 업로드

POST /api/v1/partners/v1/files

Multipart form 형식으로 파일을 업로드합니다.

요청 필드

필드	타입	필수	설명
`file`	binary	O	업로드 파일
`endUserId`	string		엔드유저 ID (분석할 때 필수)
`analyze`	'true'\|'false'		AI 분석 활성화 (기본: 'false')

cURL 예시

curl -X POST https://api.float.do/api/v1/partners/v1/files \
  -H "X-Partner-Api-Key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "endUserId=user_123" \
  -F "analyze=true"

응답 예시

{
  "success": true,
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "originalName": "sample.pdf",
    "mime": "application/pdf",
    "size": 125000,
    "textLength": 8942,
    "charsCapped": false,
    "context": null,
    "analysisStatus": "ready",
    "totalChunks": null,
    "chunks": [],
    "endUserId": "user_123",
    "usage": null,
    "createdAt": "2026-08-26T12:34:56Z"
  }
}

Chat 및 리딩 연동

명시적 첨부: Chat completions 또는 AI 리딩 요청 시 fileIds 파라미터로 최대 5개의 문서를 주입할 수 있습니다. 분석된 파일(analysisStatus: 'analyzed')은 자식 청크(최대 12개)를 주입하고, 미분석 파일은 원문 텍스트를 주입합니다(파일당 40,000자 / 전체 80,000자 제한). 주입된 문서는 "[파일 참조 결과] 파일명 (청크 1/3) 요약..." 형식으로 마지막 사용자 메시지에 추가되어 입력 토큰에 포함됩니다. 리셀 모델은 fileIds 명시 주입만 지원합니다.

자동 회상 (ridm/* 전용): ridm/* chat 및 reading-memory 모델에서는 사용자 질문의 태그와 겹치는 분석된 파일을 자동으로 검색해 주입합니다(명시적 fileIds 미지정 시에만). 응답에 filesRecalled 배열로 회상된 파일 ID를 표시합니다.

Chat 요청 예시

{
  "model": "ridm/gpt-5.6-terra",
  "messages": [
    { "role": "user", "content": "이 문서에서 주요 내용을 요약해줄 수 있나요?" }
  ],
  "fileIds": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"],
  "user": "user_123"
}

응답 예시

{
  "id": "chatcmpl-abc123",
  "choices": [{
    "message": { "content": "문서의 주요 내용은..." },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 2500, "completion_tokens": 150 },
  "filesUsed": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"],
  "filesRecalled": []
}

요금 및 과금

업로드 및 추출: 무료 (텍스트 추출 토큰 미과금)
AI 분석 (analyze=true): 경계 탐지 + 구간별 요약 + 전체 요약의 실제 토큰 사용량에 대해 RIDM 단가로 과금. 동기 ≤30,000자, 비동기 >30,000자 (status: processing)
Chat 주입: 문서 텍스트가 입력 토큰으로 계산되어 일반 chat 요청과 동일하게 과금
로그: 콘솔의 사용 로그에서 file_upload (무료), file_analyze (유료, 실사용 토큰) 분류로 확인 가능

기능 켜고 끄기

문서 처리 기능은 파트너 계정 수준에서 활성화/비활성화할 수 있습니다. 콘솔의 "기능 설정"에서 관리하며, 비활성 시 모든 파일 요청에 대해 403 응답이 반환됩니다.

전역 비활성: 403 { code: 'FEATURE_DISABLED', feature: 'files' } 응답
요청 단위: fileIds 미지정 = 문서 주입 없음 (정상 처리)

분석 상태 및 청크

GET /api/v1/partners/v1/files/:id 응답에는 analysisStatus 및 chunks 배열이 포함됩니다. 분석 완료 시 각 청크는 chunkIndex, context(요약), tags(최대 10개)를 포함합니다.

상태	설명
`ready`	추출 완료·분석 없음 (analyze=false 또는 미지정 — analyzeRequested=false)
`analyzing`	분석 진행 중 (30,000자 초과 시 비동기)
`analyzed`	분석 완료 (context·tags·chunks[] 포함)
`analyze_failed`	분석 실패 (errorMessage 포함)

주의사항

형식 검증: 지원하지 않는 형식은 400 { code: 'INVALID_FILE_TYPE' } 반환
분석 필수: analyze=true일 때 endUserId가 없으면 400 { code: 'END_USER_REQUIRED' } 반환
추출 실패: 문서 추출 중 오류 시 422 { code: 'EXTRACTION_FAILED' } 반환
잔액 확인: 분석 요청 전 파트너 크레딧 충분성 검사. 부족하면 402 반환
지식베이스 자동 적재: analyze=true인 경우, 각 구간의 요약과 태그가 지식베이스에 자동 저장되어 이후 auto-recall 대상이 됩니다. endUserId 지정 시 해당 유저의 기억 계층에도 추가됩니다.
캐싱: 같은 파일 재분석 시 이전 결과를 재사용할 수 있으므로, 동일 파일은 한 번만 업로드해 비용을 절감하세요.

감정 상태 분석 (Emotion)

Chat API에서 요약 사이클에 편승하여 사용자와 AI의 감정 상태를 분석합니다. 별도의 LLM 호출이 없으며, 요약 프롬프트에만 감정 분석 블록을 추가하므로 추가 과금이 없습니다. ridm/* 모델에서만 지원됩니다.

개요

활성화 조건:

Global: partner_emotion_enabled ✓
Partner: 콘솔 기능 설정에서 "감정 상태 분석" 활성화
Request: emotion: true 명시
Model: ridm/* 계열만 지원

요약 주기 (summaryEvery)

감정 분석은 요약 사이클마다 자동으로 실행됩니다. summaryEvery 파라미터로 사이클 주기를 조절할 수 있습니다 (기본값: 5, 범위: 1–20).

summaryEvery=1: 거의 매 턴마다 감정 업데이트 (응답 지연 거의 없음, 비용 약 ₩0.5/턴)
summaryEvery=5: 5턴 주기 (권장, 비용 약 ₩0.1/턴)
summaryEvery=20: 20턴 주기 (비용 최소)

요청 파라미터

파라미터	타입	필수	설명
`emotion`	boolean		감정 상태 분석 활성화 (ridm/* 모델에서만, 기본값: false)
`summaryEvery`	number		정수 1–20 (기본 5). 요약·감정 갱신 주기 (턴 단위)

요청 예시

{
  "model": "ridm/gpt-5.6-terra",
  "user": "user_123",
  "messages": [
    { "role": "user", "content": "오늘 하루가 힘들어..." }
  ],
  "emotion": true,
  "summaryEvery": 3
}

응답 필드

필드 경로	타입	설명
`emotion`	object\|null	감정 상태 (첫 사이클 전 또는 emotion=false 시 null/생략)
`emotion.user`	object	사용자 감정
`emotion.user.type10`	string\|null	10-class 감정 판정 (joyful\|calm\|curious\|concerned\|excited\|thoughtful\|neutral\|sad\|angry\|surprised\|null)
`emotion.user.tone`	string\|null	톤 (따뜻함\|직설\|장난\|신중함\|null)
`emotion.user.distribution6`	object	6-class 분포 {joy, sadness, anger, fear, disgust, surprise}, 합 = 1000 또는 0
`emotion.assistant`	object	AI 감정
`emotion.assistant.distribution6`	object	AI의 6-class 분포
`emotion.trend`	string\|null	감정 추세 (improving\|stable\|declining\|null)
`emotion.updatedAt`	ISO 8601	마지막 감정 업데이트 시각
`emotion.turnsSinceUpdate`	number	마지막 업데이트 이후 경과 턴 수

응답 예시

{
  "id": "chatcmpl-xyz",
  "choices": [{
    "message": { "content": "오늘 하루가 힘들었군요..." },
    "finish_reason": "stop"
  }],
  "emotion": {
    "user": {
      "type10": "sad",
      "tone": "warm",
      "distribution6": {"joy": 100, "sadness": 600, "anger": 50, "fear": 100, "disgust": 50, "surprise": 0}
    },
    "assistant": {
      "distribution6": {"joy": 200, "sadness": 100, "anger": 0, "fear": 0, "disgust": 0, "surprise": 0}
    },
    "trend": "stable",
    "updatedAt": "2026-08-26T12:34:56Z",
    "turnsSinceUpdate": 0
  },
  "usage": {...}
}

분포 필드 설명 (distribution6)

감정	값	설명
`joy`	0–1000	기쁨 강도
`sadness`	0–1000	슬픔 강도
`anger`	0–1000	분노 강도
`fear`	0–1000	두려움 강도
`disgust`	0–1000	혐오 강도
`surprise`	0–1000	놀람 강도

추세 판정 (trend)

improving: 비긍정 감정(sadness+anger+fear+disgust)이 50 이상 감소
stable: 변화 50 미만
declining: 비긍정 감정이 50 이상 증가
null: 이전 사이클 데이터 부재

스트리밍 응답 예시 (SSE)

스트리밍 모드(stream: true)에서는 감정 상태가 event: message_done SSE 이벤트의 데이터에 포함됩니다.

event: message_done
data: {"id":"chatcmpl-xyz","choices":[{"message":{"role":"assistant","content":"..."},"finish_reason":"stop"}],"usage":{...},"emotion":{"user":{"type10":"concerned","distribution6":{...}},"assistant":{...},"trend":"stable","updatedAt":"2026-08-26T12:34:56Z"}}

data: [DONE]

비용 안내

별도 과금 없음: 감정 분석은 요약 사이클 프롬프트에 포함되어 진행되므로, 요약 토큰 비용만 증가합니다 (약 150 입력 + 120 출력).
예상 비용: summaryEvery=5 기준 약 ₩0.1/턴, summaryEvery=1 기준 약 ₩0.5/턴

주의사항

첫 사이클 전: 첫 요약 사이클이 실행되기 전에는 emotion 필드가 없습니다 (정상 동작).
기능 OFF: emotion: true 요청인데 전역 또는 파트너 기능 설정이 비활성이면 403 { code: 'FEATURE_DISABLED', feature: 'emotion' } 응답 (YouTube·문서 처리와 동일). emotion을 보내지 않거나 false면 필드만 생략됩니다.
ridm/* 모델에서만 지원됩니다. openai/*·google/* 요청의 emotion 필드는 무시됩니다(403 아님).
스트리밍: 스트리밍 응답에서는 message_done SSE 이벤트에 emotion이 포함됩니다.

이미지 생성 API

사주의 오행과 에너지를 표현하는 AI 아트를 생성합니다. PNG 포맷으로 base64 인코딩되어 반환되며, 고정 ₩200 과금이 적용됩니다.

POST /api/v1/partners/v1/image

생년월일을 기반으로 사주 오행 이미지를 생성합니다.

요청 파라미터

파라미터	타입	필수	설명
`year`	number	O	출생년 (예: 1990)
`month`	number	O	출생월 (1-12)
`day`	number	O	출생일 (1-31)
`hour`	number		출생시간 (0-23, 선택사항)
`minute`	number		출생분 (0-59, 선택사항)
`gender`	string	O	성별 ("male" 또는 "female")
`style`	string		스타일 ("background", "icon", "portrait", 기본값: "background")

응답 예시

{
  "success": true,
  "data": {
    "imageDataUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
    "costPoints": 200
  }
}

주의사항

고정 가격: 모든 이미지 생성은 ₩200이 과금됩니다.
생성 시간: 이미지 생성에는 20~30초 소요됩니다. 타임아웃을 충분히 설정해주세요.
Base64 인코딩: 반환된 imageDataUri는 base64로 인코딩된 PNG 이미지이며, HTML <img src="{imageDataUri}"> 태그에 직접 사용할 수 있습니다.
스타일: background는 16:9 가로 배경, icon은 정사각형 아이콘, portrait는 인물 위주의 초상화입니다.
타임존 고정: 시간이 제공되지 않으면 자동으로 정오(12시)로 설정됩니다.

만세력 API

POST /api/v1/partners/v1/manseryeok

사주 4주 천간지지와 오행을 계산합니다. 절기 기반 정확한 계산으로 대운·세운·격국·신살 등 상세한 사주 정보를 제공합니다.

요청 파라미터

파라미터	타입	필수	설명
`year`	number	O	출생년 (예: 1990)
`month`	number	O	출생월 (1-12)
`day`	number	O	출생일 (1-31)
`hour`	number		출생시간 (0-23, 기본값: 12)
`minute`	number		출생분 (0-59, 기본값: 0)
`timezone`	string		타임존 (예: Asia/Seoul, 기본값: Asia/Seoul)
`gender`	string	O	성별 ("male" 또는 "female", 필수)
`name`	string		성명 (선택사항)

응답 필드

필드	타입	설명
`wonkuk`	object	원국 (4주 pillar). 각 주(year/month/day/hour)는 stem, branch, ohaeng, stemHanja, branchHanja, jijanggan, sinsal 등을 포함
`ohaengBalance`	object	오행 균형 { 목, 화, 토, 금, 수 }
`yongshin`	string	용신 (예: "수")
`daeun`	array	대운 주기별 정보 (시작나이, 천간지지, 십신, 신살)
`seun`	array	세운 연도별 정보
`gyeokguk`	object\|null	격국 판정 (name, summary)
`branchRelations`	array	지지 관계 (형충회합)
`gongmang`	array	공망 지지 목록
`cheonEulGwiIn`	array	천을귀인 지지 목록

응답 예시 (요약)

{
  "success": true,
  "data": {
    "wonkuk": {
      "year": { "stem": "경", "branch": "오", "ohaeng": "금", "stemHanja": "庚", "branchHanja": "午", ... },
      "month": { "stem": "신", "branch": "사", "ohaeng": "금", ... },
      "day": { "stem": "경", "branch": "진", "ohaeng": "금", ... },
      "hour": { "stem": "계", "branch": "미", "ohaeng": "수", ... }
    },
    "ohaengBalance": { "목": 0, "화": 2, "토": 2, "금": 3, "수": 1 },
    "yongshin": "수",
    "ilganSummary": "庚金 — 강철의 기운. 결단력과 의리가 강합니다.",
    "daeun": [
      { "startAge": 7, "endAge": 17, "stem": "임", "branch": "오", "isCurrent": false, ... },
      { "startAge": 17, "endAge": 27, "stem": "계", "branch": "미", "isCurrent": false, ... }
    ],
    "seun": [...],
    "gyeokguk": { "name": "정관격", "summary": "..." },
    "branchRelations": [...],
    "gongmang": ["자", "해"],
    "cheonEulGwiIn": ["인", "술"],
    ...
  }
}

주의사항

복잡한 응답: 만세력 응답은 원국뿐만 아니라 대운, 세운, 격국, 신살 등 상세 정보를 포함합니다. 필요한 필드만 선택해 사용하세요.
선택적 필드: 시간 정보가 없으면 hour은 null이 될 수 있습니다.
한글 필드명: 모든 필드명(천간, 지지, 오행 등)은 한글로 표기됩니다.

궁합 API

두 사람의 사주를 분석하여 궁합도를 평가합니다. 띠별 상성, 형충회합 관계, 상세 해석을 제공합니다.

POST /api/v1/partners/v1/compat

두 사람의 사주를 기반으로 궁합을 분석합니다.

요청 파라미터

파라미터	타입	필수	설명
`personABirthDate`	string	O	A의 출생일 (YYYY-MM-DD 양력)
`personABirthTime`	string		A의 출생시간 (HH:MM, 선택사항)
`personAGender`	string		A의 성별 ("male"/"female", 선택사항)
`personBBirthDate`	string	O	B의 출생일 (YYYY-MM-DD 양력)
`personBBirthTime`	string		B의 출생시간 (HH:MM, 선택사항)
`personBGender`	string		B의 성별 ("male"/"female", 선택사항)

응답 예시

{
  "success": true,
  "data": {
    "personABirthDate": "1990-09-04",
    "personBBirthDate": "1985-02-20",
    "tti": {
      "userTti": "쥐",
      "partnerTti": "소",
      "tier": "길",
      "bookLine": "쥐와 소는 매우 잘 맞습니다.",
      "relation": { "type": "육합", "detail": "..." },
      "conflictFrame": false
    },
    "costPoints": 5
  }
}

주의사항

기본 정보: 두 사람의 출생일은 필수입니다. 시간과 성별은 선택사항입니다.
띠 기준: 궁합은 주로 띠(십간십이지)의 오행 관계를 기준으로 분석합니다.
비용: 호출당 ₩5가 차감됩니다.

성격유형 API

MBTI 기반 성격 검사를 제공합니다. 무료 라이트 버전(24문항)과 프리미엄 버전(93문항)을 지원합니다.

GET /api/v1/partners/v1/personality-type/questions

성격 검사 문항을 조회합니다.

요청 파라미터

파라미터	타입	설명
`tier`	string	검사 버전 ("free" 또는 "premium", 기본값: "free")

응답 예시

{
  "success": true,
  "data": {
    "tier": "free",
    "count": 24,
    "questions": [
      {
        "id": "q_001",
        "text": "갑자기 생긴 모임에도 일단 가본다",
        "choices": [
          { "value": 1, "label": "전혀 그렇지 않다" },
          { "value": 2, "label": "그렇지 않다" },
          { "value": 3, "label": "보통이다" },
          { "value": 4, "label": "그렇다" },
          { "value": 5, "label": "매우 그렇다" }
        ]
      }
    ]
  }
}

POST /api/v1/partners/v1/personality-type

성격 검사 답변을 제출하여 성격유형을 분석합니다.

요청 파라미터

파라미터	타입	필수	설명
`answers`	array	O	답변 배열 [{ "questionId": "q001", "answer": 4 }, ...]
`tier`	string	O	"free" 또는 "premium"

응답 예시

{
  "success": true,
  "data": {
    "personalityType": "ENTJ",
    "typeLabel": "지휘관형",
    "scores": {
      "extraversion": 72,
      "sensing": 45,
      "thinking": 68,
      "judging": 80
    },
    "tier": "premium",
    "costPoints": 10
  }
}

가격

무료 버전 (free): 24문항, ₩0 (무료)
프리미엄 (premium): 93문항, ₩10/회

인증 API

콘솔 계정 관리를 위한 인증 API입니다.

POST /api/v1/partners/v1/console/auth/login

계정으로 로그인합니다. 이메일/비밀번호 또는 소셜 로그인을 지원합니다.

요청 (이메일)

curl -X POST https://api.float.do/api/v1/partners/v1/console/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "email",
    "email": "[email protected]",
    "password": "your-password"
  }'

요청 (소셜)

curl -X POST https://api.float.do/api/v1/partners/v1/console/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "identityToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ..."
  }'

응답

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "user-123",
      "email": "[email protected]",
      "displayName": "John Doe"
    }
  }
}

POST /api/v1/partners/v1/console/auth/register

새로운 계정을 등록합니다.

요청

curl -X POST https://api.float.do/api/v1/partners/v1/console/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "secure-password",
    "displayName": "John Doe"
  }'

응답

{
  "success": true,
  "data": {
    "message": "회원가입이 완료되었습니다. 이메일 인증이 필요합니다."
  }
}

GET /api/v1/partners/v1/console/auth/verify-email?token={token}

이메일 인증 토큰을 확인합니다.

응답

{
  "success": true,
  "data": {
    "message": "이메일 인증이 완료되었습니다."
  }
}

조회 API

크레딧 잔액과 사용 현황을 조회하는 API입니다. 헤더에 X-Partner-Api-Key를 포함해야 합니다.

GET /api/v1/partners/v1/credits/balance

현재 크레딧 잔액을 조회합니다.

요청

curl -X GET https://api.float.do/api/v1/partners/v1/credits/balance \
  -H "X-Partner-Api-Key: your-api-key"

응답

{
  "success": true,
  "data": {
    "balanceWon": 25000,
    "estimatedMonthEndBalance": 15000,
    "warningThreshold": 5000
  }
}

GET /api/v1/partners/v1/usage/logs?limit=10&offset=0

API 호출 기록을 조회합니다.

요청 파라미터

파라미터	타입	설명
`limit`	number	조회할 항목 수 (기본: 10, 최대: 100)
`offset`	number	오프셋 (기본: 0)

응답

{
  "success": true,
  "data": {
    "logs": [
      {
        "id": "call-123",
        "endpoint": "/api/v1/partners/v1/manseryeok",
        "timestamp": "2026-08-10T14:30:00Z",
        "status": 200,
        "costWon": 5,
        "guestRemaining": null
      }
    ],
    "total": 1234,
    "pagination": {
      "limit": 10,
      "offset": 0
    }
  }
}

GET /api/v1/partners/v1/usage/summary?dateFrom=2026-08-01&dateTo=2026-08-31

기간별 사용 통계를 조회합니다.

요청 파라미터

파라미터	타입	설명
`dateFrom`	string	시작 날짜 (YYYY-MM-DD)
`dateTo`	string	종료 날짜 (YYYY-MM-DD)

응답

{
  "success": true,
  "data": {
    "totalCalls": 1234,
    "totalCostWon": 6170,
    "byEndpoint": [
      {
        "endpoint": "/api/v1/partners/v1/manseryeok",
        "calls": 1234,
        "costWon": 6170
      }
    ],
    "dailyBreakdown": [
      {
        "date": "2026-08-10",
        "calls": 150,
        "costWon": 750
      }
    ]
  }
}

게스트 체험

로그인 없이 사주를 체험할 수 있는 무료 API입니다.

POST /api/v1/partners/v1/playground/manseryeok

인증 없이 만세력을 계산합니다. 월 5회 무료 사용 가능하며, 횟수 초과 시 429 에러가 반환됩니다.

요청

curl -X POST https://api.float.do/api/v1/partners/v1/playground/manseryeok \
  -H "Content-Type: application/json" \
  -d '{
    "year": 1990,
    "month": 1,
    "day": 15,
    "hour": 14,
    "minute": 30,
    "timezone": "Asia/Seoul",
    "gender": "male"
  }'

응답

{
  "success": true,
  "data": {
    "year": { "cheongan": "경", "jiji": "진", "ohaeng": "목" },
    "month": { "cheongan": "정", "jiji": "유", "ohaeng": "금" },
    "day": { "cheongan": "을", "jiji": "해", "ohaeng": "수" },
    "hour": { "cheongan": "을", "jiji": "사", "ohaeng": "목" }
  },
  "guestRemaining": 4
}

유효값

천간 (Cheongan)

갑, 을, 병, 정, 무, 기, 경, 신, 임, 계

지지 (Jiji)

자, 축, 인, 묘, 진, 사, 오, 미, 신, 유, 술, 해

오행 (Ohaeng)

목(목), 화(불), 토(흙), 금(쇠), 수(물)

에러 코드

코드	설명
400	잘못된 요청 파라미터
401	API 키 미인증 또는 유효하지 않음
429	요청 한도 초과
500	서버 오류

Rate Limit

API는 다음의 속도 제한을 적용합니다:

분당 100 요청 (authenticated)
일일 10,000 요청 (authenticated)
월 5회 무료 테스트 (guest)

과금

모든 API 호출은 크레딧에서 차감됩니다. 신규 가입 시 무료 ₩10,000 크레딧을 제공합니다. 게스트는 월 5회까지 무료로 테스트 가능합니다.

API	요금
manseryeok (만세력)	₩5/호출
compat (궁합)	₩5/호출
personality-type (성격유형) - 무료	₩0 (무료)
personality-type (성격유형) - 프리미엄	₩10/회
reading (AI 사주 리딩)	토큰 기반 (사용 토큰 수에 따라 상이)
image (이미지 생성)	₩200/이미지

게스트 테스트

mansion를eok 게스트 엔드포인트: 월 5회 무료 (IP 기반 제한)
로그인 없이 플레이그라운드에서 테스트 가능
잔여 횟수는 응답에 포함됨 (guestRemaining)

멱등성

과금이 발생하는 POST 요청에 X-Idempotency-Key 헤더(요청당 고유 문자열, 최대 128자)를 붙이면 네트워크 재시도로 같은 요청이 두 번 도착해도 한 번만 과금되고 첫 응답이 그대로 반환됩니다. 키 없이 보낸 동일 요청은 각각 과금됩니다.

지원

연동 중 막히는 부분이나 응답이 문서와 다른 경우 알려주세요.

문의	연락처
기술 지원 · 장애 신고 · 제휴	[email protected]

문의 시 아래를 함께 보내주시면 확인이 빠릅니다.

호출한 엔드포인트와 시각(타임존 포함)
API 키 앞 12자리 (float_live_ 포함, 전체 키는 절대 보내지 마세요)
받은 응답의 HTTP 상태코드와 본문

약관·개인정보 처리에 관한 사항은 이용약관과 개인정보처리방침을 참고하세요.