{"openapi":"3.0.3","info":{"title":"APICK LLM 챗봇 구축 가이드","version":"1.0.0","description":"역할과 말투가 정해진 챗봇을 만드는 방법입니다. 매 요청에 같은 system 지시문과 대화 기록을 보내고, 응답 속도·길이·비용을 조절합니다."},"servers":[{"url":"https://apick.app"}],"paths":{"/rest/llm/chat":{"post":{"summary":"LLM 챗봇 구축 가이드","description":"역할과 말투가 정해진 챗봇을 만드는 방법입니다. 매 요청에 같은 system 지시문과 대화 기록을 보내고, 응답 속도·길이·비용을 조절합니다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"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"}}}}}},"text/event-stream":{"schema":{"type":"string","description":"stream=true의 SSE는 생성문을 정리한 뒤 choices[].delta.content를 전송합니다. event: done에는 model, usage, cost, pl_id, compacted_messages가 포함되고 실패는 event: error로 전달됩니다. 토큰별 즉시 전송을 보장하지 않습니다."}}}},"default":{"description":"HTTP 상태 및 서비스 오류코드 확인","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"모델 id (llm_models Tool로 조회 가능, 예: openai/gpt-oss-120b) (string)","example":"모델_목록에서_선택한_ID"},"system":{"type":"string","description":"system 프롬프트 (역할·페르소나·정책·배경지식). 미지정 시 기본 한국어 어시스턴트 프롬프트가 적용됩니다 (string)","example":"당신은 친절한 한국어 요리 도우미입니다. 재료와 조리 순서를 구분해 6문장 이내로 답하세요."},"messages[0][role]":{"type":"string","description":"각 메시지의 작성자. messages를 사용하면 각 항목에 필요합니다. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. 가능한 값은 3가지입니다. system = 대화의 규칙·역할을 지정하는 시스템 메시지입니다. 사용자 메시지보다 먼저 적용됩니다. user = 사용자가 보낸 질문·지시 메시지입니다. assistant = 모델이 이전에 답한 메시지입니다. 대화 맥락을 이어 갈 때 넣습니다. (string)","enum":["system","user","assistant"],"example":"user"},"messages[0][content]":{"type":"string","description":"각 메시지의 본문. 0부터 연속된 인덱스로 대화 순서를 전달합니다. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)","example":"집에 계란, 밥, 김치만 있어. 저녁 메뉴 추천해 줘."},"messages[1][role]":{"type":"string","description":"두 번째 메시지 역할. 대화가 길어지면 번호를 1씩 늘립니다. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"},"messages[1][content]":{"type":"string","description":"두 번째 메시지 내용. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"},"messages[2][role]":{"type":"string","description":"세 번째 메시지 역할. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"},"messages[2][content]":{"type":"string","description":"세 번째 메시지 내용. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"},"compact[strategy]":{"type":"string","description":"대화 유지 방식. none은 전체 유지, sliding_window는 최근 대화쌍을 유지, relevance는 최근 대화쌍과 마지막 질문에 필요한 이전 대화쌍만 모델에 보냅니다. 가능한 값은 3가지입니다. none = 해당 옵션을 적용하지 않는 값입니다. 생략했을 때의 기본 동작과 같습니다. sliding_window = 최근 대화쌍만 유지하는 압축 방식입니다. 오래된 대화는 모델에 전달되지 않습니다. relevance = 검색어와의 관련도가 높은 순서로 정렬하는 값입니다. 기본 정렬로 가장 많이 쓰입니다. (string)","enum":["none","sliding_window","relevance"],"default":"none"},"compact[window_pairs]":{"type":"string","description":"sliding_window·relevance에서 모델에 보낼 대화쌍 수. 최소 1, 기본 10입니다. (integer)","default":"10"},"max_tokens":{"type":"string","description":"응답 최대 토큰. 미지정 시 모델 컨텍스트 기반 안전 상한으로 자동 설정, 명시한 값은 클램프 없이 그대로 적용 (integer)","example":"512"},"speed":{"type":"string","description":"응답 속도/추론 깊이 — 'fast'(얕게, 빠름) | 'medium' | 'slow'(깊게, 느림). 한글 '빠름'|'중간'|'느림' 허용. 추론 특화 모델에서 효과가 큽니다 (string)","example":"fast"},"stream":{"type":"string","description":"true이면 SSE 응답을 받습니다. false이면 완성된 JSON 응답을 받습니다. 생성된 내용을 정리한 뒤 전송하며 토큰별 전송을 보장하지 않습니다. (boolean)","default":"false"},"content":{"type":"string","description":"단발 입력 — 사용자 메시지 한 건만 보내는 간편 형태. messages 와 둘 중 하나는 필수 (string)"},"temperature":{"type":"string","description":"출력 다양성 0.0~2.0. 낮을수록 재현성, 높을수록 창의성 (미지정 시 모델 기본값) (number)"},"messages[0][name]":{"type":"string","description":"메시지 작성자의 이름. 사용하는 모델의 지원 여부를 확인하세요. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"},"messages[0][content][0][type]":{"type":"string","description":"여러 종류의 콘텐츠를 담을 때 항목의 종류. 같은 메시지의 content 문자열과 함께 보낼 수 없습니다. 가능한 값은 3가지입니다. text = 텍스트 프롬프트만으로 결과를 만드는 값입니다. 이미지 입력 없이 문장 묘사만 사용합니다. image_url = 이미지 주소를 담은 콘텐츠 조각입니다. 텍스트와 함께 보낼 수 있습니다. input_audio = 음성 입력을 담은 콘텐츠 조각입니다. 지원 모델에서만 사용할 수 있습니다. (string)","enum":["text","image_url","input_audio"]},"messages[0][content][0][text]":{"type":"string","description":"콘텐츠 항목이 text일 때 실제 텍스트입니다. 빈 문자열은 허용되지 않으며, 같은 메시지의 다른 콘텐츠와 순서대로 결합됩니다. (string)"},"messages[0][content][0][image_url][url]":{"type":"string","description":"type=image_url일 때 이미지 URL 또는 data URL. 모델이 이미지 입력을 지원해야 합니다. (string)"},"messages[0][content][0][image_url][detail]":{"type":"string","description":"이미지 입력을 분석할 때 사용할 해상도 힌트입니다. auto는 모델 기본값, low는 빠르고 저렴, high는 작은 글자·세부 묘사에 유리합니다. 모델이 지원하지 않으면 무시됩니다. 가능한 값은 3가지입니다. auto = 서버·모델이 상황에 맞춰 자동으로 정하는 값입니다. 별도 지정이 필요 없습니다. low = 낮은 해상도·짧은 문맥처럼 비용과 속도를 우선하는 값입니다. high = 높은 해상도·긴 문맥처럼 정확도를 우선하는 값입니다. 토큰·처리 시간이 늘어납니다. (string)","enum":["auto","low","high"]},"messages[0][content][0][input_audio][data]":{"type":"string","description":"type=input_audio일 때 음성 Base64 값. 음성 입력 지원 모델에서만 사용합니다. (string)"},"messages[0][content][0][input_audio][format]":{"type":"string","description":"음성 입력 형식. 모델에서 지원하는 형식을 사용합니다. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"},"message[role]":{"type":"string","description":"단일 메시지 객체의 역할. content 대신 객체로 보낼 때 사용합니다. 가능한 값은 3가지입니다. system = 대화의 규칙·역할을 지정하는 시스템 메시지입니다. 사용자 메시지보다 먼저 적용됩니다. user = 사용자가 보낸 질문·지시 메시지입니다. assistant = 모델이 이전에 답한 메시지입니다. 대화 맥락을 이어 갈 때 넣습니다. (string)","enum":["system","user","assistant"]},"message[content]":{"type":"string","description":"단일 메시지 방식에서 사용하는 본문입니다. 문자열 또는 콘텐츠 배열을 받으며, messages 배열과 동시에 보내지 마세요. (string)"}},"required":["model"]}}}}}}},"x-code-tables":[],"x-service-errors":[],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}