개발가이드AI•LLMLLM 대화 세션 관리 API

LLM 대화 세션 관리 API

명세 내보내기
OpenAPI 3.0.3Postman 컬렉션Markdown

대화 기록을 서버에 맡깁니다. 세션을 만든 뒤 대화 API에 session_id와 이번 질문만 보내면 앞선 대화가 이어집니다. 모든 대화 모델에서 쓸 수 있고 세션 생성·조회·보관은 무료입니다.

POSThttps://apick.app/rest/llm/sessions/create전체 5개 경로
인증
Bearer 키
요청 형식
form-data
응답
JSON
경로
5개

알아둘 점

흐름

순서
요청
하는 일
1
POST /rest/llm/sessions/create
세션을 만들고 data.session_id를 받습니다. 지시문(system)을 함께 저장할 수 있습니다.
2
POST /rest/llm/chat
session_id와 이번 질문(content)만 보냅니다. 서버가 저장된 대화 뒤에 붙여 모델에 보내고 답변을 세션에 저장합니다.
3
POST /rest/llm/sessions/get
지금까지의 대화를 확인합니다(화면 다시 그리기 등).
4
POST /rest/llm/sessions/reset · delete
대화를 비우거나 세션을 지웁니다.

대화 이어 가기

  • 대화 요청에 session_id를 넣고 content(또는 이번 턴의 messages)에 새 질문만 담습니다. 이전 질문·답변을 다시 보내지 않습니다.
  • messages에 system 메시지는 넣지 않습니다. 지시문을 바꾸려면 대화 요청의 system 항목으로 보냅니다. 바꾼 지시문은 세션에 저장됩니다.
  • 응답에는 compacted_messages 대신 data.session이 옵니다. data.session.saved가 false면 답변은 정상이지만 이번 턴이 저장되지 않았으니, 다음 질문에 이번 내용을 함께 보내세요.
  • 한 세션은 한 번에 한 요청만 처리합니다. 앞 요청이 끝나기 전에 같은 세션으로 보내면 409입니다. 동시에 여러 대화를 하려면 세션을 나눕니다.
  • 실패한 요청(잔액 부족·처리 오류 등)은 세션에 저장되지 않습니다.
  • compact는 모델에 보내는 대화에만 적용되고, 세션에는 줄이지 않은 대화가 남습니다.

대화 요청의 전체 항목과 응답은 대화 API 레퍼런스, DeepSeek 모델과 함께 쓰는 예는 DeepSeek 대화 가이드를 보세요.

보관 기간과 한도

항목
기준
보관 기간
마지막 대화 후 7일. 대화할 때마다 다시 7일로 늘어나며, 조회만으로는 늘어나지 않습니다. 지나면 자동으로 지워집니다.
세션 수
계정당 1,000개까지 보관합니다. 넘으면 만들 때 409입니다.
세션 크기
메시지 1,000개 또는 약 4MB를 넘으면 오래된 메시지부터 지워집니다. 지시문(system)은 지워지지 않습니다.
접근
세션을 만든 계정만 쓰고 볼 수 있습니다. 대화 내용은 암호화해 보관합니다.
요금
세션 생성·목록·조회·초기화·삭제와 보관은 무료입니다. 대화 요청은 평소처럼 사용한 토큰만큼 과금됩니다.

요청과 응답

1API 요청
POST/rest/llm/sessions/create
  • Bearer 인증
  • multipart/form-data
  • JSON 응답
요청 파라미터 6개
파라미터
설명
session_idstring조건부
세션 ID(llms_로 시작). get·reset·delete에서 필수입니다.
systemstring선택
대화 전체에 적용할 지시문(최대 100,000자). create에서 저장하고, reset에서 보내면 바꿉니다. 비워 두면 한국어로 답하도록 하는 기본 지시문을 씁니다.
예시
당신은 쇼핑몰 반품 상담원입니다. 존댓말로 짧게 답합니다.
titlestring선택
create에서 붙이는 세션 이름(최대 100자). 생략하면 첫 질문 앞부분으로 정해집니다.
예시
반품 상담
modelstring선택
create에서 기록해 둘 모델 ID. 실제 대화의 모델은 대화 요청의 model이 정합니다.
limitinteger선택
list에서 받을 개수. 기본 20, 최대 100. 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.
offsetinteger선택
list에서 건너뛸 개수. 기본 0. 최근에 쓴 세션부터 정렬됩니다. 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.
응답 필드 24개
응답 필드
설명
dataobject
요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.
data.session_idstring
세션 ID(create·get·reset·delete) 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.titlestring
대상의 제목 또는 이름입니다. 서비스에 따라 상품명·영상 제목·페이지 제목을 뜻하며, 줄바꿈·이모지가 포함될 수 있습니다.
data.modelstring
응답을 생성한 모델 ID입니다. 요청에서 지정한 모델과 같으며, 모델 목록 API의 id 값과 비교해 확인합니다. null 허용.
data.message_countinteger
저장된 메시지 수(system 제외) 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.created_atstring
작업이 접수된 일시입니다. ISO 8601 형식이며, 결과 만료 시각을 계산할 때 기준으로 사용합니다.
data.updated_atstring
마지막으로 대화한 시각 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.expires_atstring
자동으로 지워지는 시각 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.systemstring
저장된 지시문(get·reset). 비어 있으면 기본 지시문을 씁니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.messagesarray
저장된 대화(get·reset). role·content 순서대로 들어 있습니다.
data.ic_idstring
이번 조회에 부여된 식별자입니다. 같은 요청의 결과를 추적하거나 문의할 때 사용하며, 값이 없으면 null입니다. null 허용.
data.resultinteger
조회 결과 본문입니다. 서비스가 찾은 실제 데이터가 들어 있으며, 자료가 없거나 조회에 실패하면 null이거나 필드가 생략됩니다.
data.msgstring
처리 결과를 사람이 읽을 수 있는 문장으로 설명합니다. 성공·실패 사유가 담기며, 오류 코드는 별도 필드에서 확인합니다.
data.successinteger
업무 처리 결과 코드입니다. 1은 정상 결과, 0은 실패 또는 무료 응답입니다. 서비스에 따라 2·3처럼 추가 코드를 쓰므로 같은 응답의 status·msg·error 필드도 함께 확인하세요.
data.sessionsarray
list의 세션 목록. 항목마다 위의 session_id~expires_at가 있고 대화 내용은 없습니다.
data.totalinteger
list에서 보관 중인 전체 세션 수 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.deletedboolean
delete 성공 시 true true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다.
apiobject
API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.
api.successboolean
API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.
api.costinteger
이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.
api.msinteger
서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다.
api.pl_idstring
포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다. null 허용.
하위 필드 2개 더 보기
응답 필드
설명
data.messages[].rolestring
'role' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.
data.messages[].contentstring
'content' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.
2API 요청
POST/rest/llm/sessions/list
  • Bearer 인증
  • multipart/form-data
  • JSON 응답
요청 파라미터 6개
파라미터
설명
session_idstring조건부
세션 ID(llms_로 시작). get·reset·delete에서 필수입니다.
systemstring선택
대화 전체에 적용할 지시문(최대 100,000자). create에서 저장하고, reset에서 보내면 바꿉니다. 비워 두면 한국어로 답하도록 하는 기본 지시문을 씁니다.
titlestring선택
create에서 붙이는 세션 이름(최대 100자). 생략하면 첫 질문 앞부분으로 정해집니다.
modelstring선택
create에서 기록해 둘 모델 ID. 실제 대화의 모델은 대화 요청의 model이 정합니다.
limitinteger선택
list에서 받을 개수. 기본 20, 최대 100. 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.
offsetinteger선택
list에서 건너뛸 개수. 기본 0. 최근에 쓴 세션부터 정렬됩니다. 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.
응답 필드 24개
응답 필드
설명
dataobject
요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.
data.session_idstring
세션 ID(create·get·reset·delete) 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.titlestring
대상의 제목 또는 이름입니다. 서비스에 따라 상품명·영상 제목·페이지 제목을 뜻하며, 줄바꿈·이모지가 포함될 수 있습니다.
data.modelstring
응답을 생성한 모델 ID입니다. 요청에서 지정한 모델과 같으며, 모델 목록 API의 id 값과 비교해 확인합니다. null 허용.
data.message_countinteger
저장된 메시지 수(system 제외) 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.created_atstring
작업이 접수된 일시입니다. ISO 8601 형식이며, 결과 만료 시각을 계산할 때 기준으로 사용합니다.
data.updated_atstring
마지막으로 대화한 시각 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.expires_atstring
자동으로 지워지는 시각 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.systemstring
저장된 지시문(get·reset). 비어 있으면 기본 지시문을 씁니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.messagesarray
저장된 대화(get·reset). role·content 순서대로 들어 있습니다.
data.ic_idstring
이번 조회에 부여된 식별자입니다. 같은 요청의 결과를 추적하거나 문의할 때 사용하며, 값이 없으면 null입니다. null 허용.
data.resultinteger
조회 결과 본문입니다. 서비스가 찾은 실제 데이터가 들어 있으며, 자료가 없거나 조회에 실패하면 null이거나 필드가 생략됩니다.
data.msgstring
처리 결과를 사람이 읽을 수 있는 문장으로 설명합니다. 성공·실패 사유가 담기며, 오류 코드는 별도 필드에서 확인합니다.
data.successinteger
업무 처리 결과 코드입니다. 1은 정상 결과, 0은 실패 또는 무료 응답입니다. 서비스에 따라 2·3처럼 추가 코드를 쓰므로 같은 응답의 status·msg·error 필드도 함께 확인하세요.
data.sessionsarray
list의 세션 목록. 항목마다 위의 session_id~expires_at가 있고 대화 내용은 없습니다.
data.totalinteger
list에서 보관 중인 전체 세션 수 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.deletedboolean
delete 성공 시 true true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다.
apiobject
API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.
api.successboolean
API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.
api.costinteger
이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.
api.msinteger
서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다.
api.pl_idstring
포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다. null 허용.
하위 필드 2개 더 보기
응답 필드
설명
data.messages[].rolestring
'role' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.
data.messages[].contentstring
'content' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.
3API 요청
POST/rest/llm/sessions/get
  • Bearer 인증
  • multipart/form-data
  • JSON 응답
요청 파라미터 6개
파라미터
설명
session_idstring조건부
세션 ID(llms_로 시작). get·reset·delete에서 필수입니다.
systemstring선택
대화 전체에 적용할 지시문(최대 100,000자). create에서 저장하고, reset에서 보내면 바꿉니다. 비워 두면 한국어로 답하도록 하는 기본 지시문을 씁니다.
titlestring선택
create에서 붙이는 세션 이름(최대 100자). 생략하면 첫 질문 앞부분으로 정해집니다.
modelstring선택
create에서 기록해 둘 모델 ID. 실제 대화의 모델은 대화 요청의 model이 정합니다.
limitinteger선택
list에서 받을 개수. 기본 20, 최대 100. 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.
offsetinteger선택
list에서 건너뛸 개수. 기본 0. 최근에 쓴 세션부터 정렬됩니다. 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.
응답 필드 24개
응답 필드
설명
dataobject
요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.
data.session_idstring
세션 ID(create·get·reset·delete) 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.titlestring
대상의 제목 또는 이름입니다. 서비스에 따라 상품명·영상 제목·페이지 제목을 뜻하며, 줄바꿈·이모지가 포함될 수 있습니다.
data.modelstring
응답을 생성한 모델 ID입니다. 요청에서 지정한 모델과 같으며, 모델 목록 API의 id 값과 비교해 확인합니다. null 허용.
data.message_countinteger
저장된 메시지 수(system 제외) 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.created_atstring
작업이 접수된 일시입니다. ISO 8601 형식이며, 결과 만료 시각을 계산할 때 기준으로 사용합니다.
data.updated_atstring
마지막으로 대화한 시각 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.expires_atstring
자동으로 지워지는 시각 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.systemstring
저장된 지시문(get·reset). 비어 있으면 기본 지시문을 씁니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.messagesarray
저장된 대화(get·reset). role·content 순서대로 들어 있습니다.
data.ic_idstring
이번 조회에 부여된 식별자입니다. 같은 요청의 결과를 추적하거나 문의할 때 사용하며, 값이 없으면 null입니다. null 허용.
data.resultinteger
조회 결과 본문입니다. 서비스가 찾은 실제 데이터가 들어 있으며, 자료가 없거나 조회에 실패하면 null이거나 필드가 생략됩니다.
data.msgstring
처리 결과를 사람이 읽을 수 있는 문장으로 설명합니다. 성공·실패 사유가 담기며, 오류 코드는 별도 필드에서 확인합니다.
data.successinteger
업무 처리 결과 코드입니다. 1은 정상 결과, 0은 실패 또는 무료 응답입니다. 서비스에 따라 2·3처럼 추가 코드를 쓰므로 같은 응답의 status·msg·error 필드도 함께 확인하세요.
data.sessionsarray
list의 세션 목록. 항목마다 위의 session_id~expires_at가 있고 대화 내용은 없습니다.
data.totalinteger
list에서 보관 중인 전체 세션 수 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.deletedboolean
delete 성공 시 true true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다.
apiobject
API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.
api.successboolean
API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.
api.costinteger
이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.
api.msinteger
서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다.
api.pl_idstring
포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다. null 허용.
하위 필드 2개 더 보기
응답 필드
설명
data.messages[].rolestring
'role' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.
data.messages[].contentstring
'content' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.
4API 요청
POST/rest/llm/sessions/reset
  • Bearer 인증
  • multipart/form-data
  • JSON 응답
요청 파라미터 6개
파라미터
설명
session_idstring조건부
세션 ID(llms_로 시작). get·reset·delete에서 필수입니다.
systemstring선택
대화 전체에 적용할 지시문(최대 100,000자). create에서 저장하고, reset에서 보내면 바꿉니다. 비워 두면 한국어로 답하도록 하는 기본 지시문을 씁니다.
titlestring선택
create에서 붙이는 세션 이름(최대 100자). 생략하면 첫 질문 앞부분으로 정해집니다.
modelstring선택
create에서 기록해 둘 모델 ID. 실제 대화의 모델은 대화 요청의 model이 정합니다.
limitinteger선택
list에서 받을 개수. 기본 20, 최대 100. 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.
offsetinteger선택
list에서 건너뛸 개수. 기본 0. 최근에 쓴 세션부터 정렬됩니다. 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.
응답 필드 24개
응답 필드
설명
dataobject
요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.
data.session_idstring
세션 ID(create·get·reset·delete) 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.titlestring
대상의 제목 또는 이름입니다. 서비스에 따라 상품명·영상 제목·페이지 제목을 뜻하며, 줄바꿈·이모지가 포함될 수 있습니다.
data.modelstring
응답을 생성한 모델 ID입니다. 요청에서 지정한 모델과 같으며, 모델 목록 API의 id 값과 비교해 확인합니다. null 허용.
data.message_countinteger
저장된 메시지 수(system 제외) 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.created_atstring
작업이 접수된 일시입니다. ISO 8601 형식이며, 결과 만료 시각을 계산할 때 기준으로 사용합니다.
data.updated_atstring
마지막으로 대화한 시각 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.expires_atstring
자동으로 지워지는 시각 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.systemstring
저장된 지시문(get·reset). 비어 있으면 기본 지시문을 씁니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.messagesarray
저장된 대화(get·reset). role·content 순서대로 들어 있습니다.
data.ic_idstring
이번 조회에 부여된 식별자입니다. 같은 요청의 결과를 추적하거나 문의할 때 사용하며, 값이 없으면 null입니다. null 허용.
data.resultinteger
조회 결과 본문입니다. 서비스가 찾은 실제 데이터가 들어 있으며, 자료가 없거나 조회에 실패하면 null이거나 필드가 생략됩니다.
data.msgstring
처리 결과를 사람이 읽을 수 있는 문장으로 설명합니다. 성공·실패 사유가 담기며, 오류 코드는 별도 필드에서 확인합니다.
data.successinteger
업무 처리 결과 코드입니다. 1은 정상 결과, 0은 실패 또는 무료 응답입니다. 서비스에 따라 2·3처럼 추가 코드를 쓰므로 같은 응답의 status·msg·error 필드도 함께 확인하세요.
data.sessionsarray
list의 세션 목록. 항목마다 위의 session_id~expires_at가 있고 대화 내용은 없습니다.
data.totalinteger
list에서 보관 중인 전체 세션 수 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.deletedboolean
delete 성공 시 true true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다.
apiobject
API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.
api.successboolean
API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.
api.costinteger
이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.
api.msinteger
서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다.
api.pl_idstring
포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다. null 허용.
하위 필드 2개 더 보기
응답 필드
설명
data.messages[].rolestring
'role' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.
data.messages[].contentstring
'content' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.
5API 요청
POST/rest/llm/sessions/delete
  • Bearer 인증
  • multipart/form-data
  • JSON 응답
요청 파라미터 6개
파라미터
설명
session_idstring조건부
세션 ID(llms_로 시작). get·reset·delete에서 필수입니다.
systemstring선택
대화 전체에 적용할 지시문(최대 100,000자). create에서 저장하고, reset에서 보내면 바꿉니다. 비워 두면 한국어로 답하도록 하는 기본 지시문을 씁니다.
titlestring선택
create에서 붙이는 세션 이름(최대 100자). 생략하면 첫 질문 앞부분으로 정해집니다.
modelstring선택
create에서 기록해 둘 모델 ID. 실제 대화의 모델은 대화 요청의 model이 정합니다.
limitinteger선택
list에서 받을 개수. 기본 20, 최대 100. 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.
offsetinteger선택
list에서 건너뛸 개수. 기본 0. 최근에 쓴 세션부터 정렬됩니다. 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.
응답 필드 24개
응답 필드
설명
dataobject
요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.
data.session_idstring
세션 ID(create·get·reset·delete) 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.titlestring
대상의 제목 또는 이름입니다. 서비스에 따라 상품명·영상 제목·페이지 제목을 뜻하며, 줄바꿈·이모지가 포함될 수 있습니다.
data.modelstring
응답을 생성한 모델 ID입니다. 요청에서 지정한 모델과 같으며, 모델 목록 API의 id 값과 비교해 확인합니다. null 허용.
data.message_countinteger
저장된 메시지 수(system 제외) 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.created_atstring
작업이 접수된 일시입니다. ISO 8601 형식이며, 결과 만료 시각을 계산할 때 기준으로 사용합니다.
data.updated_atstring
마지막으로 대화한 시각 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.expires_atstring
자동으로 지워지는 시각 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.systemstring
저장된 지시문(get·reset). 비어 있으면 기본 지시문을 씁니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.messagesarray
저장된 대화(get·reset). role·content 순서대로 들어 있습니다.
data.ic_idstring
이번 조회에 부여된 식별자입니다. 같은 요청의 결과를 추적하거나 문의할 때 사용하며, 값이 없으면 null입니다. null 허용.
data.resultinteger
조회 결과 본문입니다. 서비스가 찾은 실제 데이터가 들어 있으며, 자료가 없거나 조회에 실패하면 null이거나 필드가 생략됩니다.
data.msgstring
처리 결과를 사람이 읽을 수 있는 문장으로 설명합니다. 성공·실패 사유가 담기며, 오류 코드는 별도 필드에서 확인합니다.
data.successinteger
업무 처리 결과 코드입니다. 1은 정상 결과, 0은 실패 또는 무료 응답입니다. 서비스에 따라 2·3처럼 추가 코드를 쓰므로 같은 응답의 status·msg·error 필드도 함께 확인하세요.
data.sessionsarray
list의 세션 목록. 항목마다 위의 session_id~expires_at가 있고 대화 내용은 없습니다.
data.totalinteger
list에서 보관 중인 전체 세션 수 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.deletedboolean
delete 성공 시 true true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다.
apiobject
API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.
api.successboolean
API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.
api.costinteger
이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.
api.msinteger
서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다.
api.pl_idstring
포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다. null 허용.
하위 필드 2개 더 보기
응답 필드
설명
data.messages[].rolestring
'role' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.
data.messages[].contentstring
'content' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.
입력 조건·전송 규칙

사용 예시

상황별로 보내는 값과 응답에서 확인할 값을 모았습니다. 언어 탭에서 그대로 복사해 쓸 수 있습니다.

예시 1. 세션 만들기

대화를 시작할 때 지시문과 이름을 정해 세션을 만듭니다.

요청POST/rest/llm/sessions/create
curl --fail-with-body --request POST 'https://apick.app/rest/llm/sessions/create' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'title=반품 상담' \
  --form-string 'system=당신은 쇼핑몰 반품 상담원입니다. 존댓말로 짧게 답합니다.'
  • data.session_id를 대화 요청의 session_id로 보냅니다.
  • data.expires_at이 지나면 세션이 지워집니다. 대화할 때마다 7일 뒤로 늘어납니다.
예시 2. 내 세션 목록

최근에 쓴 세션부터 20개씩 받아 대화 목록 화면을 만듭니다.

요청POST/rest/llm/sessions/list
curl --fail-with-body --request POST 'https://apick.app/rest/llm/sessions/list' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'limit=20' \
  --form-string 'offset=0'
  • data.sessions[].title·updated_at으로 목록을 그리고, data.total로 다음 페이지가 있는지 판단합니다.
예시 3. 대화 내용 다시 불러오기

앱을 다시 열었을 때 지난 대화를 화면에 그립니다.

요청POST/rest/llm/sessions/get
curl --fail-with-body --request POST 'https://apick.app/rest/llm/sessions/get' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'session_id=llms_0f1e2d3c4b5a69788796a5b4'
  • data.messages에 질문·답변이 순서대로 있습니다.
예시 4. 대화 지우고 새로 시작

지시문은 그대로 두고 대화만 비웁니다. 세션을 통째로 지우려면 /rest/llm/sessions/delete를 씁니다.

요청POST/rest/llm/sessions/reset
curl --fail-with-body --request POST 'https://apick.app/rest/llm/sessions/reset' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'session_id=llms_0f1e2d3c4b5a69788796a5b4'
  • data.message_count가 0이면 비워진 것입니다.

응답 처리

HTTP 성공과 업무 결과를 구분하세요. 경로별 응답 필드와 예시는 위 요청과 응답에 함께 있습니다.

{
  "data": {
    "session_id": "llms_0f1e2d3c4b5a69788796a5b4",
    "title": "반품 상담",
    "model": "deepseek-flash",
    "message_count": 2,
    "created_at": "2026-10-27T01:00:00.000Z",
    "updated_at": "2026-10-27T01:02:10.000Z",
    "expires_at": "2026-11-03T01:02:10.000Z",
    "system": "당신은 쇼핑몰 반품 상담원입니다. 존댓말로 짧게 답합니다.",
    "messages": [
      { "role": "user", "content": "어제 받은 상품을 반품하고 싶어요." },
      { "role": "assistant", "content": "불편을 드려 죄송합니다. 주문번호를 알려 주시면 반품 접수를 도와드리겠습니다." }
    ],
    "ic_id": null, "result": 1, "msg": "", "success": 1
  },
  "api": { "success": true, "cost": 0, "ms": 12, "pl_id": null }
}
원문 응답 필드 표 보기
필드
타입
설명
data.session_id
String
세션 ID(create·get·reset·delete)
data.title
String
세션 이름
data.model
String/null
마지막 대화에 쓴 모델 ID
data.message_count
Integer
저장된 메시지 수(system 제외)
data.created_at
String
만든 시각(ISO 8601)
data.updated_at
String
마지막으로 대화한 시각
data.expires_at
String
자동으로 지워지는 시각
data.system
String
저장된 지시문(get·reset). 비어 있으면 기본 지시문을 씁니다.
data.messages
Array
저장된 대화(get·reset). role·content 순서대로 들어 있습니다.
data.sessions
Array
list의 세션 목록. 항목마다 위의 session_id~expires_at가 있고 대화 내용은 없습니다.
data.total
Integer
list에서 보관 중인 전체 세션 수
data.deleted
Boolean
delete 성공 시 true
api.cost
Integer
항상 0

오류 코드

응답을 아래 순서로 확인하세요. 결과 유무와 과금 여부는 서로 다릅니다.

  1. HTTP 상태전송·인증·입력 오류
  2. api.successAPI 처리 여부
  3. data · result업무 결과와 오류 문구
  4. api.cost이번 요청의 과금
업무 실패 응답 data.error
  • 입력값이 맞지 않거나 대상 자료가 없거나 일시적으로 처리하지 못하면 data.error(사유 문구)와 data.success=0을 돌려줍니다. HTTP 상태는 사유에 따라 400·404·408·424 중 하나입니다.
  • 이때 api.cost는 0이며 과금되지 않습니다. data.error 문구를 그대로 기록하고 사용자에게 보여 주세요.
  • 입력 오류(400)는 값을 고친 뒤 다시 요청하세요. 408·424는 잠시 후 한 번 다시 시도하고, 같은 입력으로 짧은 간격의 자동 반복은 하지 마세요.
{
  "data": {
    "error": "입력값을 확인해 주세요.",
    "success": 0
  },
  "api": {
    "success": true,
    "cost": 0,
    "ms": 5
  }
}
서비스 코드·조건

오류 코드

HTTP
data.code
대처
400
SESSION_ID_REQUIRED
session_id를 보내세요.
400
UNSUPPORTED_MODEL
model은 모델 카탈로그의 ID를 씁니다.
400
SESSION_SYSTEM_TOO_LONG
system을 100,000자 이하로 줄이세요.
401
-
인증키를 확인하세요.
404
SESSION_NOT_FOUND
만료(마지막 대화 후 7일)·삭제됐거나 다른 계정의 세션입니다. 새 세션을 만드세요.
409
SESSION_BUSY
같은 세션의 대화가 진행 중입니다. 끝난 뒤 다시 보내세요.
409
SESSION_LIMIT
보관 세션이 1,000개입니다. 쓰지 않는 세션을 지우세요.
503
SESSION_UNAVAILABLE
잠시 후 다시 시도하세요.
인증·포인트 오류 result.error 문구
코드
HTTP
의미·조치
유효하지 않은 API키 입니다.
401
Authorization: Bearer 헤더의 인증키를 확인하세요.
허용되지 않은 IP주소 입니다.
401
마이페이지의 허용 IP 설정과 요청 서버 IP를 확인하세요.
비활성화된 계정입니다.
401
계정 이용 상태를 고객지원으로 문의하세요.
사용 가능한 포인트이 부족합니다.
200
HTTP 200이어도 result.error가 있으면 실패입니다. 포인트를 충전한 뒤 다시 요청하세요. 이 응답은 과금되지 않습니다.
인증 정보를 확인할 수 없습니다.
424
일시적인 확인 실패입니다. 잠시 후 다시 시도하세요.
폼 입력 오류 error.code
코드
HTTP
의미·조치
FORM_DATA_INVALID
400
필드 이름·값의 타입·배열 인덱스를 확인하세요. 인덱스는 0부터 연속으로 사용합니다.
FORM_DATA_FIELD_CONFLICT
400
같은 값과 중첩 경로를 동시에 지정하지 마세요.
MULTIPART_LIMIT_OR_PARSE_ERROR
400·413
boundary·파일 크기·필드 개수를 확인하세요. 서비스별 제한이 우선 적용됩니다.

요금·이용 조건

기본 요금서비스별 요금 조건 확인

실제 차감 금액은 응답의 api.cost로 확인하세요. 상세 요금은 요금정책에서 볼 수 있습니다.

연동 팁

  • 요청 예제의 오류 처리 포함 모드는 시간 제한과 업무 실패 판정을 함께 보여줍니다.
  • 인증키는 서버 환경변수에 두고 브라우저·앱에 넣지 마세요.
  • HTTP 성공과 업무 결과를 구분하고, 실패 응답의 오류 문구를 그대로 기록하세요.

개발가이드 검색

API 이름·경로·파라미터·오류 코드로 찾을 수 있습니다.

표시 가격은 기본 단가입니다. 상세 과금 조건은 각 가이드에서 확인하세요.