# LLM 단발 호출 가이드



질문 하나를 보내고 답 하나를 받는 가장 간단한 호출 방법입니다. 이전 대화를 기억할 필요가 없을 때 model과 content만 보내면 됩니다.



인증: Authorization: Bearer $APICK_API_KEY

본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다.

인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다.



## POST /rest/llm/chat 응답 필드

- `data` (object): 요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.

- `data.model` (string): 응답을 생성한 모델 ID입니다. 요청에서 지정한 모델과 같으며, 모델 목록 API의 id 값과 비교해 확인합니다.

- `data.message` (object): 모델이 생성한 응답 메시지 묶음입니다. 작성자 역할과 답변 본문이 들어 있습니다.

- `data.message.role` (string): 메시지 작성자 역할입니다. 응답에서는 assistant입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.message.content` (string): 모델이 생성한 답변 텍스트입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.usage` (object): 이번 응답의 토큰 사용량 묶음입니다. 입력·출력·합계 토큰 수가 들어 있으며 과금 계산의 기준이 됩니다.

- `data.usage.prompt_tokens` (integer): 입력(프롬프트)에 사용한 토큰 수입니다. 과금 계산의 입력 단가에 적용됩니다.

- `data.usage.completion_tokens` (integer): 출력(응답)에 사용한 토큰 수입니다. 과금 계산의 출력 단가에 적용됩니다.

- `data.usage.total_tokens` (integer): 입력과 출력 토큰을 합한 수입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.compacted_messages` (array): 문맥 압축으로 요약된 이전 메시지 목록입니다. 대화가 길어져 오래된 메시지를 압축했을 때 포함됩니다.

- `data.compacted_messages[].role` (string): 압축된 이전 메시지의 작성자 역할입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.compacted_messages[].content` (string): 문맥 압축으로 요약된 이전 메시지 내용입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.ic_id` (undefined): 이번 조회에 부여된 식별자입니다. 같은 요청의 결과를 추적하거나 문의할 때 사용하며, 값이 없으면 null입니다. null 허용.

- `data.result` (integer): 조회 결과 본문입니다. 서비스가 찾은 실제 데이터가 들어 있으며, 자료가 없거나 조회에 실패하면 null이거나 필드가 생략됩니다.

- `data.msg` (string): 처리 결과를 사람이 읽을 수 있는 문장으로 설명합니다. 성공·실패 사유가 담기며, 오류 코드는 별도 필드에서 확인합니다.

- `data.success` (integer): 업무 처리 결과 코드입니다. 1은 정상 결과, 0은 실패 또는 무료 응답입니다. 서비스에 따라 2·3처럼 추가 코드를 쓰므로 같은 응답의 status·msg·error 필드도 함께 확인하세요.

- `api` (object): API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.

- `api.success` (boolean): API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.

- `api.cost` (integer): 이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.

- `api.ms` (integer): 서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다.

- `api.pl_id` (integer): 포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.

## API 요청: POST /rest/llm/chat



### 입력

- `model` (string, 필수): 모델 id (llm_models Tool로 조회 가능, 예: openai/gpt-oss-120b)

- `content` (string, 필수): 단발 입력 — 사용자 메시지 한 건만 보내는 간편 형태. messages 와 둘 중 하나는 필수

- `system` (string, 선택): system 프롬프트 (역할·페르소나·정책·배경지식). 미지정 시 기본 한국어 어시스턴트 프롬프트가 적용됩니다

- `temperature` (number, 선택): 출력 다양성 0.0~2.0. 낮을수록 재현성, 높을수록 창의성 (미지정 시 모델 기본값)

- `max_tokens` (integer, 선택): 응답 최대 토큰. 미지정 시 모델 컨텍스트 기반 안전 상한으로 자동 설정, 명시한 값은 클램프 없이 그대로 적용

- `speed` (string, 선택): 응답 속도/추론 깊이 — 'fast'(얕게, 빠름) | 'medium' | 'slow'(깊게, 느림). 한글 '빠름'|'중간'|'느림' 허용. 추론 특화 모델에서 효과가 큽니다

- `messages` (array, 선택): OpenAI 형식 [{role, content}] 배열. role 은 'system'|'user'|'assistant'. content 와 둘 중 하나는 필수, 동시 지정 시 messages 우선. 멀티턴 대화는 응답의 compacted_messages 를 다음 턴에 그대로 전송

- `compact` (object, 선택): 히스토리 압축 옵션 { strategy: 'none'(기본) | 'sliding_window' | 'relevance', window_pairs: 유지할 user/assistant 페어 수 (기본 10, 최소 1) }. relevance 는 최근 대화와 함께 최신 질문에 필요한 이전 대화를 골라 남긴다. 긴 대화의 input 토큰 누적 방지

- `messages[0][role]` (string, 조건부): 각 메시지의 작성자. messages를 사용하면 각 항목에 필요합니다. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. 가능한 값은 3가지입니다. system = 대화의 규칙·역할을 지정하는 시스템 메시지입니다. 사용자 메시지보다 먼저 적용됩니다. user = 사용자가 보낸 질문·지시 메시지입니다. assistant = 모델이 이전에 답한 메시지입니다. 대화 맥락을 이어 갈 때 넣습니다. 허용값: system, user, assistant

- `messages[0][content]` (string, 조건부): 각 메시지의 본문. 0부터 연속된 인덱스로 대화 순서를 전달합니다. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다.

- `messages[0][name]` (string, 선택): 메시지 작성자의 이름. 사용하는 모델의 지원 여부를 확인하세요. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다.

- `messages[0][content][0][type]` (string, 조건부): 여러 종류의 콘텐츠를 담을 때 항목의 종류. 같은 메시지의 content 문자열과 함께 보낼 수 없습니다. 가능한 값은 3가지입니다. text = 텍스트 프롬프트만으로 결과를 만드는 값입니다. 이미지 입력 없이 문장 묘사만 사용합니다. image_url = 이미지 주소를 담은 콘텐츠 조각입니다. 텍스트와 함께 보낼 수 있습니다. input_audio = 음성 입력을 담은 콘텐츠 조각입니다. 지원 모델에서만 사용할 수 있습니다. 허용값: text, image_url, input_audio

- `messages[0][content][0][text]` (string, 조건부): 콘텐츠 항목이 text일 때 실제 텍스트입니다. 빈 문자열은 허용되지 않으며, 같은 메시지의 다른 콘텐츠와 순서대로 결합됩니다.

- `messages[0][content][0][image_url][url]` (string, 조건부): type=image_url일 때 이미지 URL 또는 data URL. 모델이 이미지 입력을 지원해야 합니다.

- `messages[0][content][0][image_url][detail]` (string, 선택): 이미지 입력을 분석할 때 사용할 해상도 힌트입니다. auto는 모델 기본값, low는 빠르고 저렴, high는 작은 글자·세부 묘사에 유리합니다. 모델이 지원하지 않으면 무시됩니다. 가능한 값은 3가지입니다. auto = 서버·모델이 상황에 맞춰 자동으로 정하는 값입니다. 별도 지정이 필요 없습니다. low = 낮은 해상도·짧은 문맥처럼 비용과 속도를 우선하는 값입니다. high = 높은 해상도·긴 문맥처럼 정확도를 우선하는 값입니다. 토큰·처리 시간이 늘어납니다. 허용값: auto, low, high

- `messages[0][content][0][input_audio][data]` (string, 조건부): type=input_audio일 때 음성 Base64 값. 음성 입력 지원 모델에서만 사용합니다.

- `messages[0][content][0][input_audio][format]` (string, 조건부): 음성 입력 형식. 모델에서 지원하는 형식을 사용합니다. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다.

- `message[role]` (string, 선택): 단일 메시지 객체의 역할. content 대신 객체로 보낼 때 사용합니다. 가능한 값은 3가지입니다. system = 대화의 규칙·역할을 지정하는 시스템 메시지입니다. 사용자 메시지보다 먼저 적용됩니다. user = 사용자가 보낸 질문·지시 메시지입니다. assistant = 모델이 이전에 답한 메시지입니다. 대화 맥락을 이어 갈 때 넣습니다. 허용값: system, user, assistant

- `message[content]` (string, 선택): 단일 메시지 방식에서 사용하는 본문입니다. 문자열 또는 콘텐츠 배열을 받으며, messages 배열과 동시에 보내지 마세요.

- `compact[strategy]` (string, 선택): 대화 유지 방식. none은 전체 유지, sliding_window는 최근 대화쌍을 유지, relevance는 최근 대화쌍과 마지막 질문에 필요한 이전 대화쌍만 모델에 보냅니다. 가능한 값은 3가지입니다. none = 해당 옵션을 적용하지 않는 값입니다. 생략했을 때의 기본 동작과 같습니다. sliding_window = 최근 대화쌍만 유지하는 압축 방식입니다. 오래된 대화는 모델에 전달되지 않습니다. relevance = 검색어와의 관련도가 높은 순서로 정렬하는 값입니다. 기본 정렬로 가장 많이 쓰입니다. 기본값: none 허용값: none, sliding_window, relevance

- `compact[window_pairs]` (integer, 선택): sliding_window·relevance에서 모델에 보낼 대화쌍 수. 최소 1, 기본 10입니다. 기본값: 10

- `stream` (boolean, 선택): true이면 SSE 응답을 받습니다. false이면 완성된 JSON 응답을 받습니다. 생성된 내용을 정리한 뒤 전송하며 토큰별 전송을 보장하지 않습니다. 기본값: false



### 응답 명세

```json

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "model": {
          "type": "string"
        },
        "message": {
          "type": "object",
          "properties": {
            "role": {
              "type": "string"
            },
            "content": {
              "type": "string"
            }
          }
        },
        "usage": {
          "type": "object",
          "properties": {
            "prompt_tokens": {
              "type": "integer"
            },
            "completion_tokens": {
              "type": "integer"
            },
            "total_tokens": {
              "type": "integer"
            }
          }
        },
        "compacted_messages": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "role": {
                "type": "string"
              },
              "content": {
                "type": "string"
              }
            }
          }
        },
        "ic_id": {
          "nullable": true
        },
        "result": {
          "type": "integer"
        },
        "msg": {
          "type": "string"
        },
        "success": {
          "type": "integer"
        }
      }
    },
    "api": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "cost": {
          "type": "integer"
        },
        "ms": {
          "type": "integer"
        },
        "pl_id": {
          "type": "integer"
        }
      }
    }
  }
}

```

### 정적 응답 예시

```json

{
  "data": {
    "model": "meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo",
    "message": {
      "role": "assistant",
      "content": "{\"sentiment\":\"positive\",\"confidence\":0.95}"
    },
    "usage": {
      "prompt_tokens": 74,
      "completion_tokens": 14,
      "total_tokens": 88
    },
    "compacted_messages": [
      {
        "role": "system",
        "content": "사용자 문장의 감성을 분류합니다. 다음 JSON만 출력하세요. 설명 금지. {\"sentiment\":\"positive|negative|neutral\",\"confidence\":0.0~1.0}"
      },
      {
        "role": "user",
        "content": "이 상품 정말 최고예요! 배송도 빨랐어요."
      },
      {
        "role": "assistant",
        "content": "{\"sentiment\":\"positive\",\"confidence\":0.95}"
      }
    ],
    "ic_id": null,
    "result": 1,
    "msg": "",
    "success": 1
  },
  "api": {
    "success": true,
    "cost": 5,
    "ms": 640,
    "pl_id": 12345
  }
}

```

### curl

```curl

curl --fail-with-body --request POST 'https://apick.app/rest/llm/chat' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string "model=${APICK_MODEL}" \
  --form-string 'content=한 문장으로 자기소개 해 줘.'

```

### Node.js (서버 ESM)

```javascript

const form = new FormData();
form.append("model", process.env.APICK_MODEL);
form.append("content", "한 문장으로 자기소개 해 줘.");
const response = await fetch("https://apick.app/rest/llm/chat", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

```

### python

```python

import os
import requests
parts = [
    ("model", (None, os.environ["APICK_MODEL"])),
    ("content", (None, "한 문장으로 자기소개 해 줘.")),
]
response = requests.request("POST", "https://apick.app/rest/llm/chat",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

```

### php

```php

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'model' => getenv('APICK_MODEL'),
    'content' => '한 문장으로 자기소개 해 줘.',
];
$curl = curl_init('https://apick.app/rest/llm/chat');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

```

## 사용 예시 1. 리뷰 감성을 JSON으로 분류

리뷰 한 건씩 정해진 JSON으로 분류합니다. 같은 입력에 같은 답이 나오도록 `temperature`를 낮춥니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/llm/chat' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'model=meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo' \
  --form-string 'system=사용자 문장의 감성을 분류합니다. 다음 JSON만 출력하세요. 설명 금지. {"sentiment":"positive|negative|neutral","confidence":0.0~1.0}' \
  --form-string 'content=이 상품 정말 최고예요! 배송도 빨랐어요.' \
  --form-string 'temperature=0.1' \
  --form-string 'max_tokens=64'

```

- `data.message.content`에서 첫 `{`부터 마지막 `}`까지 잘라 JSON으로 읽습니다.

- 읽기에 실패하면 같은 요청을 한 번 더 보내거나 수동 확인 목록으로 넘깁니다.

## 사용 예시 2. 문장 번역

번역문만 받도록 `system`에 지시합니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/llm/chat' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'model=meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo' \
  --form-string 'system=자연스러운 영어로 번역합니다. 번역문만 출력하고 원문이나 설명을 덧붙이지 마세요.' \
  --form-string 'content=배송이 정말 빠르네요!' \
  --form-string 'temperature=0.3'

```

- 번역문은 `data.message.content`에 있습니다.

## 사용 예시 3. 한 문장으로 짧게 답하기

알림·툴팁처럼 짧은 답만 필요하면 문장 수 지시와 `max_tokens`를 함께 씁니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/llm/chat' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'model=meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo' \
  --form-string 'system=답은 반드시 1문장, 50자 이내로 작성하세요.' \
  --form-string 'content=하늘이 파란 이유를 설명해 줘.' \
  --form-string 'max_tokens=80' \
  --form-string 'speed=fast'

```

- `data.usage.completion_tokens`가 작을수록 비용이 줄어듭니다.

## 코드·오류

## 상세 기능·요금

이런 상황에 사용하세요 상황단발 호출이 맞는 이유 상품 설명·이메일 본문 자동 작성건마다 독립적으로 만들면 됩니다. 리뷰·댓글 감성 분류, 문의 유형 분류한 건씩 판단하며 앞 건의 맥락이 필요 없습니다. 문장 번역·요약원문과 결과가 한 번에 끝납니다. 문장에서 이름·날짜·금액 같은 값 뽑기정해진 형식으로 한 번 답하면 됩니다. 앞선 대화를 이어가야 하면 멀티챗 가이드, 말투·역할이 정해진 챗봇은 챗봇 구축 가이드를 보세요. system으로 답 모양 정하기 단발 호출에서도 system 한 줄로 답의 형식과 길이를 고정할 수 있습니다. 아래 지시문을 그대로 넣어 시작해 보세요. 목적system 지시문함께 보낼 값 JSON으로 분류 사용자 문장의 감성을 분류합니다. 다음 JSON만 출력하세요. 설명 금지. {"sentiment":"positive|negative|neutral","confidence":0.0~1.0} temperature=0.1, max_tokens=64 짧은 답 답은 반드시 1문장, 50자 이내로 작성하세요. max_tokens=80 번역 자연스러운 영어로 번역합니다. 번역문만 출력하고 원문이나 설명을 덧붙이지 마세요. temperature=0.3 값 추출 문장에서 날짜(YYYY-MM-DD)와 금액(숫자)만 뽑아 {"date":"","amount":0} JSON으로 출력하세요. 없으면 null. temperature=0.1 JSON을 받을 때는 data.message.content에서 첫 {부터 마지막 }까지만 잘라 파싱하면 앞뒤에 문장이 붙어도 안전하게 읽을 수 있습니다. 실패 처리 HTTP뜻앱에서 할 일 400입력 오류(모델 ID, 빈 질문 등)다시 보내지 말고 data.msg·data.hint를 보고 입력을 고칩니다. 402잔액 부족충전 안내를 보여 줍니다. 502일시적 처리 실패data.retryable이 true면 1~2초 뒤 한 번만 다시 보냅니다. 실패한 요청은 과금되지 않습니다(api.cost 0). 추론 모델이나 긴 답변은 몇 분이 걸릴 수 있으니 클라이언트 시간 제한을 넉넉히(최대 10분) 두세요.

## 상세 요청

MethodURL POST https://apick.app/rest/llm/chat form-data 전체 예제 보기 전체 입력 항목은 대화 API 레퍼런스에 있습니다.

## 상세 응답

답변은 data.message.content, 차감 포인트는 api.cost입니다. 단발 호출에서는 data.compacted_messages를 쓰지 않아도 됩니다. { "data": { "model": "meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo", "message": { "role": "assistant", "content": "{\"sentiment\":\"positive\",\"confidence\":0.95}" }, "usage": { "prompt_tokens": 74, "completion_tokens": 14, "total_tokens": 88 }, "compacted_messages": [ { "role": "system", "content": "사용자 문장의 감성을 분류합니다. 다음 JSON만 출력하세요. 설명 금지. {\"sentiment\":\"positive|negative|neutral\",\"confidence\":0.0~1.0}" }, { "role": "user", "content": "이 상품 정말 최고예요! 배송도 빨랐어요." }, { "role": "assistant", "content": "{\"sentiment\":\"positive\",\"confidence\":0.95}" } ], "ic_id": null, "result": 1, "msg": "", "success": 1 }, "api": { "success": true, "cost": 5, "ms": 640, "pl_id": 12345 } }

## 상세 예제

호출 예시 같은 요청을 JavaScript와 Python으로 옮긴 예시입니다. 키는 환경변수 APICK_API_KEY 에서 읽습니다. JavaScript 예시 form-data 전체 예제 보기 Python 예시 form-data 전체 예제 보기