개발가이드

  • 개발가이드

LLM 채팅 API 레퍼런스

POST /rest/llm/chat 단일 창구의 전체 스펙 레퍼런스. 노출 파라미터(model, messages/content, system, mode, temperature, max_tokens, speed, compact), 응답 스키마, 에러 코드, 스트리밍. 실전 사용법은 목적별 가이드(단발·멀티챗·챗봇·에이전트)를 참고하세요.

API 레퍼런스 페이지입니다

이 페이지는 /rest/llm/chat 의 전체 스펙 레퍼런스입니다. 처음 연동하신다면 실전 시나리오별 가이드부터 보시는 걸 권장합니다:

목적
가이드 페이지
한 번 호출하고 결과만 받기
여러 턴에 걸쳐 대화 이어가기
페르소나·UX 가진 챗봇 제품 구축
도메인 특화 AI 비서·업무 에이전트

정보

Method
URL
POST
https://apick.app/rest/llm/chat

과금 정책

실제 사용 토큰 기반 자동 과금. 1포인트 = 1원 (부가세별도). 모델별 1M 토큰당 input/output 단가는 /dev_guide/llm_models 응답의 price 필드에서 확인.

항목
값
과금 기준
토큰 사용량 기반 (input/output 별도 단가)
단위
포인트 / 1,000,000 토큰
최소 과금
각 파트(input/output) 사용량이 1포인트 미만이어도 1포인트씩 부과
PaymentLog uri
llm_chat

요청

Header
이름
필수
설명
Content-Type
O
application/json
CL_AUTH_KEY
O
인증키(MD5)
Body (JSON) — 노출 파라미터 (누구나 쉽게 사용)
이름
타입
필수
설명
model
String
O
카탈로그 id. /rest/llm/models 에서 조회
messages
Array
△
멀티턴 입력. [{ role:'user'|'assistant'|'system', content }...]. content/messages 중 하나 필수
content
String
△
단발 입력 — 사용자 한 문장 전송의 간편 형태. messages 와 동시 지정 시 messages 우선
system
String
X
role:system 최전방 prepend. 에이전트 페르소나·정책·배경지식을 직접 주입
compact.strategy
String
X
'none'(기본) · 'sliding_window'. 긴 대화의 input 토큰 누적 방지
compact.window_pairs
Integer
X
sliding_window 사용 시 유지할 user/assistant 페어 수 (기본 10, 최소 1)
temperature
Number
X
0.0~2.0. 낮을수록 재현성↑ (FAQ·정책 안내 권장 0.1~0.3), 높을수록 창의성↑ (브레인스토밍 0.7~1.0)
max_tokens
Integer
X
응답 최대 토큰. 미지정 시 각 모델의 max_context 로 자동 설정. 지정해도 모델 한계를 넘으면 서버가 조용히 클램프. 캐시 웜업 전·알 수 없는 모델은 32768 폴백
speed
String
X
응답 속도/추론 깊이 — 'fast'(얕게, 빠름) · 'medium' · 'slow'(깊게, 느림). 한글 '빠름'·'중간'·'느림' 허용. tag:reasoning 모델에서 가장 효과 확연

서버가 무시하는(잘 안 쓰는) 파라미터: top_p, top_k, presence_penalty, frequency_penalty, seed, logit_bias, n, repetition_penalty, response_format, tools, tool_choice, stop, user — 대부분의 앱은 건드릴 필요가 없으며, 업스트림 기본값이 안전하게 동작합니다. 보내도 무시됩니다.

응답 포맷

공통 래퍼 { data, api }. 실제 응답은 data.message.content, 과금·소요시간은 api.

data (LLM 응답 본문)
이름
타입
설명
model
String
사용된 모델 id
message
Object
{ role:'assistant', content } — 모델 응답
usage
Object
prompt_tokens(input) / completion_tokens(output) / total_tokens
compacted_messages
Array
다음 턴 그대로 사용할 messages[]. 요청 messages + 이번 응답의 assistant 메시지가 append 된 최종 히스토리 (서버 compact 적용 후)
ic_id
null
LLM 은 항상 null (래퍼 구조 유지)
result / success
Integer
1 성공 / 0 실패
msg
String
에러 메시지 (성공 시 "")
api (공통 메타 + 과금)
이름
타입
설명
success
Boolean
처리 성공 여부
cost
Integer
실제 차감된 포인트 (input 과금 + output 과금)
ms
Integer
서버 처리 소요시간(ms)
pl_id
Integer/null
PaymentLog ID

에러 코드

HTTP
의미
400
model/content 누락 · 카탈로그 외 모델 · 잘못된 compact/speed 값
402
잔액 부족 (최소 1포인트 필요)
500
서버 api key 미설정 (운영자 문의)
502
업스트림 LLM 일시 오류 — 지수 백오프 재시도 권장

Stateless 운영 원칙

서버는 대화 히스토리를 보관하지 않습니다. 클라이언트가 매 호출마다 messages[] 로 전체 히스토리를 전송하고, 응답의 data.compacted_messages 를 다음 호출의 messages 로 그대로 사용합니다.

  • 세션 생성·조회·리셋·삭제 엔드포인트는 존재하지 않습니다.
  • 긴 대화는 compact.strategy="sliding_window" 로 서버가 최근 N 페어만 유지.
  • 서버 요약은 미제공. 더 긴 대화는 /chat 을 추가 호출해 요약 후 system 으로 치환.
  • 기본 응답 언어: 한국어. system/mode 미지정 시 서버가 한국어 강제 system 을 자동 주입.

고급: 스트리밍 (SSE)

응답이 긴 경우 stream: true 로 SSE 토큰 스트림을 받을 수 있습니다. 마지막 event: done 프레임에 cost·pl_id·compacted_messages 가 담깁니다. 프로토타입은 스트리밍 없이 시작하고, UX 개선이 필요해지면 도입하는 것을 권장합니다 (대부분의 앱에 필요 없음).

스트리밍 요청 예시 (cURL)

curl -Nk -X POST "https://apick.app/rest/llm/chat" \
-H "Content-Type: application/json" \
-H "CL_AUTH_KEY: $API_KEY" \
-d '{
  "model": "meta-llama/Meta-Llama-3.1-8B-Instruct",
  "content": "긴 이야기 해줘.",
  "stream": true
}'

최소 호출 예시 — axios


import axios from 'axios';

const { data: result } = await axios.post('https://apick.app/rest/llm/chat', {
  model: 'meta-llama/Meta-Llama-3.1-8B-Instruct',
  content: '한 문장으로 자기소개 해줘.',
}, {
  headers: { 'CL_AUTH_KEY': process.env.API_KEY },
});

console.log(result.data.message.content); // 모델 응답 텍스트
console.log('비용:', result.api.cost, '포인트');

max_tokens·temperature·system·compact·speed 모두 생략 가능 — 서버가 안전한 기본값(한국어 응답·max_tokens 은 각 모델의 max_context 까지 자동 허용)으로 동작합니다.

멀티턴 호출 예시 — axios


let history = [];   // 클라이언트가 소유하는 messages[]

async function ask(userText) {
  history.push({ role: 'user', content: userText });

  const { data: result } = await axios.post('https://apick.app/rest/llm/chat', {
    model: 'meta-llama/Meta-Llama-3.1-8B-Instruct',
    messages: history,
    compact: { strategy: 'sliding_window', window_pairs: 10 },
  }, {
    headers: { 'CL_AUTH_KEY': process.env.API_KEY },
  });

  history = result.data.compacted_messages; // ⚠️ 직접 push 금지 — 교체!
  return result.data.message.content;
}

console.log(await ask('내 이름은 지훈이야.'));
console.log(await ask('내 이름 기억해?'));

응답 예시


{
  "data": {
    "model": "meta-llama/Meta-Llama-3.1-8B-Instruct",
    "message": { "role": "assistant", "content": "안녕하세요! 반갑습니다." },
    "usage": { "prompt_tokens": 23, "completion_tokens": 6, "total_tokens": 29 },
    "compacted_messages": [
      { "role": "user",      "content": "한 문장으로 자기소개 해줘." },
      { "role": "assistant", "content": "안녕하세요! 반갑습니다." }
    ],
    "ic_id": null, "result": 1, "msg": "", "success": 1
  },
  "api": { "success": true, "cost": 2, "ms": 482, "pl_id": 12345 }
}
현재 페이지 북마크