{"openapi":"3.0.3","info":{"title":"APICK LLM 채팅 API 레퍼런스","version":"1.0.0","description":"선택한 모델에 질문이나 대화 기록을 보내고 답변을 받는 API의 전체 명세입니다. 입력 항목, 응답 필드, SSE 형식, 오류와 요금을 모두 정리했습니다."},"servers":[{"url":"https://apick.app"}],"paths":{"/rest/llm/chat":{"post":{"summary":"LLM 채팅 API 레퍼런스","description":"선택한 모델에 질문이나 대화 기록을 보내고 답변을 받는 API의 전체 명세입니다. 입력 항목, 응답 필드, SSE 형식, 오류와 요금을 모두 정리했습니다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"model":{"type":"string","description":"답변한 모델 ID"},"message":{"type":"object","properties":{"role":{"type":"string","description":"항상 assistant"},"content":{"type":"string","description":"답변 본문"}}},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","description":"입력 토큰 수(입력 단가 적용)"},"completion_tokens":{"type":"integer","description":"출력 토큰 수(출력 단가 적용)"},"total_tokens":{"type":"integer","description":"입력 + 출력 토큰 수"}}},"compacted_messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string"},"content":{"type":"string"}}},"description":"다음 요청의 messages로 그대로 보낼 대화 기록. compact를 적용한 기록 끝에 이번 답변이 붙어 있습니다."},"ic_id":{"nullable":true},"result":{"type":"integer","description":"1 성공, 0 실패"},"msg":{"type":"string","description":"실패 사유. 성공하면 빈 문자열"},"success":{"type":"integer"},"hint":{"type":"string","description":"잘못된 model·speed·compact 값으로 실패했을 때 고치는 방법"},"retryable":{"type":"boolean","description":"502 실패에서 true면 잠시 후 같은 요청을 다시 보내도 됩니다."}}},"api":{"type":"object","properties":{"success":{"type":"boolean"},"cost":{"type":"integer","description":"이번 요청에서 차감된 포인트. 실패하면 0"},"ms":{"type":"integer","description":"처리 시간(밀리초)"},"pl_id":{"type":"integer","description":"포인트 사용 내역 번호","nullable":true}}}}}},"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"},"content":{"type":"string","description":"단발 입력 — 사용자 메시지 한 건만 보내는 간편 형태. messages 와 둘 중 하나는 필수 (string)","example":"한 문장으로 자기소개 해 줘."},"messages[0][role]":{"type":"string","description":"각 메시지의 작성자. messages를 사용하면 각 항목에 필요합니다. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. 가능한 값은 3가지입니다. system = 대화의 규칙·역할을 지정하는 시스템 메시지입니다. 사용자 메시지보다 먼저 적용됩니다. user = 사용자가 보낸 질문·지시 메시지입니다. assistant = 모델이 이전에 답한 메시지입니다. 대화 맥락을 이어 갈 때 넣습니다. (string)","enum":["system","user","assistant"]},"messages[0][content]":{"type":"string","description":"각 메시지의 본문. 0부터 연속된 인덱스로 대화 순서를 전달합니다. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"},"messages[1][role]":{"type":"string","description":"두 번째 메시지 역할. 대화 순서대로 번호를 늘립니다. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"},"messages[1][content]":{"type":"string","description":"두 번째 메시지 내용. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"},"messages[2][role]":{"type":"string","description":"세 번째 메시지 역할. 마지막 메시지는 보통 이번에 묻는 user 메시지입니다. (string)"},"messages[2][content]":{"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][1][type]":{"type":"string","description":"두 번째 조각의 종류. 이미지면 image_url. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"},"messages[0][content][1][image_url][url]":{"type":"string","description":"이미지 주소. 로그인 없이 누구나 열 수 있는 https 주소를 넣습니다. (string)"},"system":{"type":"string","description":"system 프롬프트 (역할·페르소나·정책·배경지식). 미지정 시 기본 한국어 어시스턴트 프롬프트가 적용됩니다 (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"},"temperature":{"type":"string","description":"출력 다양성 0.0~2.0. 낮을수록 재현성, 높을수록 창의성 (미지정 시 모델 기본값) (number)"},"max_tokens":{"type":"string","description":"응답 최대 토큰. 미지정 시 모델 컨텍스트 기반 안전 상한으로 자동 설정, 명시한 값은 클램프 없이 그대로 적용 (integer)"},"speed":{"type":"string","description":"응답 속도/추론 깊이 — 'fast'(얕게, 빠름) | 'medium' | 'slow'(깊게, 느림). 한글 '빠름'|'중간'|'느림' 허용. 추론 특화 모델에서 효과가 큽니다 (string)"},"stream":{"type":"string","description":"true이면 SSE 응답을 받습니다. false이면 완성된 JSON 응답을 받습니다. 생성된 내용을 정리한 뒤 전송하며 토큰별 전송을 보장하지 않습니다. (boolean)","default":"false"},"messages[0][name]":{"type":"string","description":"메시지 작성자의 이름. 사용하는 모델의 지원 여부를 확인하세요. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (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":[{"title":"오류 코드","columns":["HTTP","data.msg","대처"],"rows":[["400","model required","model을 보내세요."],["400","unsupported model (text-generation 카탈로그 외)","모델 카탈로그의 id를 그대로 쓰세요."],["400","content/message/messages required","content 또는 messages를 보내세요."],["400","unsupported speed","fast·medium·slow(또는 한글 값)만 씁니다."],["400","unknown compact.strategy","none·sliding_window·relevance만 씁니다."],["402","잔액 부족 (최소 1포인트 필요)","포인트를 충전한 뒤 다시 요청하세요."],["402","payment failed after call","포인트 차감을 마치지 못했습니다. 잔액을 확인한 뒤 다시 요청하세요."],["500","서비스 설정을 확인할 수 없습니다.","잠시 후 다시 시도하고, 계속되면 문의하세요."],["502","외부 처리 서비스 응답 오류","data.retryable이 true면 1~2초 뒤 한 번만 다시 보내세요. 과금되지 않습니다."]]}],"x-service-errors":[],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}