개발가이드

  • 개발가이드

LLM 단발 호출 가이드

한 번 호출해서 답 하나만 받는 가장 단순한 사용법. 감성 분류·번역·요약·짧은 Q&A 같은 무상태 작업에 3줄 코드로 연동. axios 샘플 + system 지시문 패턴 + 에러 처리까지.

이런 상황에 사용하세요

"입력 텍스트 하나를 보내서 답 하나를 받기만 하면 된다" — 대화의 맥락이나 여러 턴의 기억이 필요 없는 경우입니다. 가장 간단한 LLM 호출 방식이며, 3줄 코드면 충분합니다.

시나리오
왜 단발이 맞는가
검색어 → 자연어 요약 1회
이전 검색 기억 불필요
상품 설명 자동 생성
각 상품은 독립적
이메일 제목 → 본문 1회 생성
후속 수정은 사용자가 직접
댓글·리뷰 감성 분류
각 댓글은 독립적
입력 번역 1회
원문-번역 쌍이 완결됨
JSON 슬롯 추출 (의도 분류)
이전 대화 맥락 없이도 처리 가능

여러 턴에 걸쳐 대화를 이어가야 한다면 멀티챗 가이드, 페르소나가 필요하면 챗봇/에이전트 가이드로 가세요.

전제 조건

항목
설명
API 키
/dev_guide/start 에서 CL_AUTH_KEY 발급
잔액
토큰 과금이 발생 — 최소 1포인트 이상 (1포인트 = 1원)
모델
/rest/llm/models 응답의 id 중 선택해 model 필드에 전달

최소 코드 (3줄)

단발 호출은 content 한 필드면 됩니다. messages[] 배열을 만들 필요 없고, 히스토리도 관리하지 않습니다.

JavaScript (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); // → "안녕하세요, 친절한 AI 어시스턴트입니다."
console.log(result.api.cost, '포인트');    // → 2 포인트
cURL

curl -k -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": "한 문장으로 자기소개 해줘."
}'

생략 가능한 옵션 (서버가 기본값으로 자동 동작) — max_tokens (각 모델의 max_context 까지 자동 허용), temperature (모델 기본), 기타 모든 파라미터. 모델 응답은 기본 한국어로 강제됩니다.

실전 패턴 — 지시문으로 원하는 답 받기

system 필드 한 줄을 추가하면 "어떤 방식으로 답할지" 를 지정할 수 있습니다. 단발 호출에서도 매우 유용합니다.

패턴 1 — 출력 형식 고정 (JSON 분류기)

const { data: result } = await axios.post('https://apick.app/rest/llm/chat', {
  model: 'meta-llama/Meta-Llama-3.1-8B-Instruct',
  system: `사용자 문장의 감성을 분류하는 분류기입니다.
오직 다음 JSON 만 출력하세요. 설명·주석 금지.
{"sentiment": "positive|negative|neutral", "confidence": 0.0~1.0}`,
  content: '이 상품 정말 최고예요! 배송도 빨랐어요.',
  temperature: 0.1,   // 재현성 극대화
  max_tokens: 64,
}, {
  headers: { 'CL_AUTH_KEY': process.env.API_KEY },
});

const json = JSON.parse(result.data.message.content);
// { sentiment: 'positive', confidence: 0.95 }
패턴 2 — 짧고 간결한 답 강제

const { data: result } = await axios.post('https://apick.app/rest/llm/chat', {
  model: 'meta-llama/Meta-Llama-3.1-8B-Instruct',
  system: '답은 반드시 1문장, 50자 이내로 작성하세요.',
  content: '하늘이 파란 이유를 설명해줘.',
  max_tokens: 80,
}, {
  headers: { 'CL_AUTH_KEY': process.env.API_KEY },
});
패턴 3 — 번역기

async function translate(text, targetLang = '영어') {
  const { data: result } = await axios.post('https://apick.app/rest/llm/chat', {
    model: 'meta-llama/Meta-Llama-3.1-8B-Instruct',
    system: `자연스러운 ${targetLang} 번역기. 번역문만 출력. 원문·설명 덧붙이지 마세요.`,
    content: text,
    temperature: 0.3,
  }, { headers: { 'CL_AUTH_KEY': process.env.API_KEY } });
  return result.data.message.content;
}

console.log(await translate('배송이 정말 빠르네요!', '영어'));
// → "The delivery was really fast!"

에러 처리 — 최소한의 방어

단발 호출이라도 네트워크·잔액·입력 오류가 있을 수 있습니다. axios 는 4xx/5xx 에서 자동으로 예외를 던지므로 try/catch 만 감싸주세요. 


import axios from 'axios';

async function askOnce(prompt) {
  try {
    const { data: result } = await axios.post('https://apick.app/rest/llm/chat', {
      model: 'meta-llama/Meta-Llama-3.1-8B-Instruct',
      content: prompt,
    }, {
      headers: { 'CL_AUTH_KEY': process.env.API_KEY },
      timeout: 30000,
    });
    return { ok: true, text: result.data.message.content, cost: result.api.cost };
  } catch (e) {
    const status = e.response?.status;
    if (status === 400) return { ok: false, msg: '입력이 올바르지 않습니다' };
    if (status === 402) return { ok: false, msg: '포인트가 부족합니다 — 충전 필요' };
    if (status === 502) return { ok: false, msg: '일시적 오류 — 잠시 후 다시 시도' };
    return { ok: false, msg: '요청 실패: ' + (e.message || 'unknown') };
  }
}

const r = await askOnce('...');
if (r.ok) console.log(r.text);
else      console.error(r.msg);

응답 예시


{
  "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 }
}

단발 호출에서 compacted_messages 는 "다음 호출에 이어갈 수 있는 형태" 로 내려오지만 단발에서는 무시하면 됩니다. 다음 턴으로 이어갈 계획이 있다면 멀티챗 가이드로 가세요.

현재 페이지 북마크