# DeepSeek Flash·Pro 대화 API DeepSeek Flash·Pro 모델로 대화·추론·코딩·긴 문서 분석을 처리합니다. 대화 API의 model에 deepseek-flash 또는 deepseek-pro를 넣으면 되고, 생각 깊이 조절과 서버 보관 대화 세션을 함께 쓸 수 있습니다. 인증: 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 필드도 함께 확인하세요. - `data.session` (object): session_id를 보냈을 때 세션 저장 결과(session_id·saved·message_count·expires_at) - `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 와 둘 중 하나는 필수 - `messages[0][role]` (string, 조건부): 각 메시지의 작성자. messages를 사용하면 각 항목에 필요합니다. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. 가능한 값은 3가지입니다. system = 대화의 규칙·역할을 지정하는 시스템 메시지입니다. 사용자 메시지보다 먼저 적용됩니다. user = 사용자가 보낸 질문·지시 메시지입니다. assistant = 모델이 이전에 답한 메시지입니다. 대화 맥락을 이어 갈 때 넣습니다. 허용값: system, user, assistant - `messages[0][content]` (string, 조건부): 각 메시지의 본문. 0부터 연속된 인덱스로 대화 순서를 전달합니다. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. - `system` (string, 선택): system 프롬프트 (역할·페르소나·정책·배경지식). 미지정 시 기본 한국어 어시스턴트 프롬프트가 적용됩니다 - `speed` (string, 선택): 응답 속도/추론 깊이 — 'fast'(얕게, 빠름) | 'medium' | 'slow'(깊게, 느림). 한글 '빠름'|'중간'|'느림' 허용. 추론 특화 모델에서 효과가 큽니다 - `session_id` (string, 선택): 대화 세션 ID. 보내면 이번 턴의 새 메시지만 보내도 앞선 대화가 이어집니다. - `max_tokens` (integer, 선택): 응답 최대 토큰. 미지정 시 모델 컨텍스트 기반 안전 상한으로 자동 설정, 명시한 값은 클램프 없이 그대로 적용 - `stream` (boolean, 선택): true이면 SSE 응답을 받습니다. false이면 완성된 JSON 응답을 받습니다. 생성된 내용을 정리한 뒤 전송하며 토큰별 전송을 보장하지 않습니다. 기본값: false - `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 토큰 누적 방지 - `temperature` (number, 선택): 출력 다양성 0.0~2.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 ### 응답 명세 ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "model": { "type": "string", "description": "요청한 모델 ID(deepseek-flash·deepseek-pro)" }, "message": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string", "description": "최종 답변" } } }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer", "description": "입력 토큰 수" }, "completion_tokens": { "type": "integer", "description": "출력 토큰 수(생각에 쓴 토큰 포함)" }, "total_tokens": { "type": "integer" } } }, "compacted_messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } } }, "description": "세션 없이 쓸 때 다음 요청의 messages로 보낼 대화 기록" }, "ic_id": { "nullable": true }, "result": { "type": "integer" }, "msg": { "type": "string" }, "success": { "type": "integer" }, "session": { "type": "object", "description": "session_id를 보냈을 때 세션 저장 결과(session_id·saved·message_count·expires_at)" } } }, "api": { "type": "object", "properties": { "success": { "type": "boolean" }, "cost": { "type": "integer", "description": "이번 요청에서 차감된 포인트" }, "ms": { "type": "integer" }, "pl_id": { "type": "integer" } } } } } ``` ### 정적 응답 예시 ```json { "data": { "model": "deepseek-flash", "message": { "role": "assistant", "content": "1. 구매 후 7일 안에 신청하면 전액 환불됩니다.\n2. 사용한 상품은 환불되지 않습니다.\n3. 배송비는 고객이 부담합니다." }, "usage": { "prompt_tokens": 1240, "completion_tokens": 58, "total_tokens": 1298 }, "compacted_messages": [ { "role": "system", "content": "당신은 한국어 AI 어시스턴트입니다. 모든 답변은 한국어로 작성합니다. 사용자가 명시적으로 다른 언어를 요청한 경우에만 해당 언어로 응답합니다. 답변은 명확하고 간결하게, 필요한 경우 Markdown 서식(목록·코드 블록·굵은 글씨)을 활용합니다." }, { "role": "user", "content": "환불 규정을 세 줄로 요약해 줘." }, { "role": "assistant", "content": "1. 구매 후 7일 안에 신청하면 전액 환불됩니다.\n2. 사용한 상품은 환불되지 않습니다.\n3. 배송비는 고객이 부담합니다." } ], "ic_id": null, "result": 1, "msg": "", "success": 1 }, "api": { "success": true, "cost": 5, "ms": 1830, "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 'speed=fast' \ --form-string 'content=환불 규정을 세 줄로 요약해 줘.' ``` ### Node.js (서버 ESM) ```javascript const form = new FormData(); form.append("model", process.env.APICK_MODEL); form.append("speed", "fast"); 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"])), ("speed", (None, "fast")), ("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 getenv('APICK_MODEL'), 'speed' => 'fast', '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. 빠른 답변(생각 없이) 챗봇 응답·분류처럼 빠른 답이 필요하면 `deepseek-flash`에 `speed=fast`를 보냅니다. ```bash curl --fail-with-body --request POST 'https://apick.app/rest/llm/chat' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'model=deepseek-flash' \ --form-string 'speed=fast' \ --form-string 'content=이 문의를 배송·환불·기타 중 하나로 분류해 줘: 상자가 찢어져서 왔어요.' ``` - 답변은 `data.message.content`에 있습니다. - `data.usage.completion_tokens`가 작을수록 비용이 줄어듭니다. ## 사용 예시 2. 어려운 문제를 깊게 생각해서 수학·코드·정책 해석처럼 정확도가 중요하면 `deepseek-pro`에 `speed=slow`를 보냅니다. ```bash curl --fail-with-body --request POST 'https://apick.app/rest/llm/chat' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'model=deepseek-pro' \ --form-string 'speed=slow' \ --form-string 'content=연 4.5% 복리로 1,000만 원을 7년 맡기면 얼마가 되는지 계산 과정과 함께 알려 줘.' ``` - 생각에 쓴 토큰은 `data.usage.completion_tokens`에 포함됩니다. 넉넉한 `max_tokens`를 두세요. ## 사용 예시 3. 정해진 규칙으로 상담하기 상담 규칙을 `system`에 넣고 고객 질문을 `content`로 보냅니다. ```bash curl --fail-with-body --request POST 'https://apick.app/rest/llm/chat' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'speed=fast' \ --form-string 'model=deepseek-flash' \ --form-string 'system=당신은 쇼핑몰 상담원입니다. 환불은 7일 이내, 사용한 상품은 불가, 배송비는 고객 부담입니다.' \ --form-string 'content=어제 받은 신발이 작아요. 환불되나요?' ``` - 답변이 `system`의 규칙(7일 이내·사용품 불가)을 따르는지 `data.message.content`로 확인합니다. ## 코드·오류 ## 상세 기능·요금 모델 고르기 model잘 맞는 일특징 deepseek-flash상담·요약·분류·번역, 대량 처리, 이미지가 섞인 질문빠르고 단가가 낮습니다. 이미지 입력을 받습니다. 최대 1M 토큰 컨텍스트. deepseek-pro어려운 추론·수학·코드 작성과 리뷰, 긴 계약서·보고서 분석더 깊고 정확한 답을 냅니다. 텍스트 전용. 최대 1M 토큰 컨텍스트. 두 모델의 1M 토큰당 입력·출력 단가는 모델 카탈로그에서 family=deepseek로 조회합니다. 생각 깊이(speed) speed동작쓰는 곳 fast · 빠름생각 단계 없이 바로 답합니다. 가장 빠르고 출력 토큰이 적습니다.챗봇 응답, 분류·추출, 대량 처리 medium · 중간짧게 생각한 뒤 답합니다.일반 질의응답, 간단한 계산·판단 slow · 느림 · 생략충분히 생각한 뒤 답합니다.수학·코딩·정책 해석처럼 정확도가 중요한 일 생각한 과정은 응답에 싣지 않고 최종 답변만 data.message.content로 돌려줍니다. 생각에 쓴 토큰은 data.usage.completion_tokens에 포함되어 출력 단가로 계산됩니다. 요금 입력·출력 토큰 수 × 모델별 1M 토큰당 단가로 정산하고, 요청 합계를 포인트 단위로 올림합니다. 시간대·반복 입력과 관계없이 같은 단가입니다. 요청당 기본요금 5P가 최소액입니다. 대화 세션의 생성·조회·보관은 무료입니다. 모델별 단가는 모델 카탈로그의 price에서 확인합니다. ## 상세 요청 MethodURL POST https://apick.app/rest/llm/chat 대화 API와 같은 경로입니다. 여기에는 DeepSeek 모델에서 자주 쓰는 항목만 적었습니다. 전체 항목은 대화 API 레퍼런스를 보세요. form-data 전체 예제 보기 ## 상세 응답 필드타입설명 data.modelString요청한 모델 ID(deepseek-flash·deepseek-pro) data.message.contentString최종 답변 data.usage.prompt_tokensInteger입력 토큰 수 data.usage.completion_tokensInteger출력 토큰 수(생각에 쓴 토큰 포함) data.compacted_messagesArray세션 없이 쓸 때 다음 요청의 messages로 보낼 대화 기록 data.sessionObjectsession_id를 보냈을 때 세션 저장 결과(session_id·saved·message_count·expires_at) api.costInteger이번 요청에서 차감된 포인트 { "data": { "model": "deepseek-flash", "message": { "role": "assistant", "content": "1. 구매 후 7일 안에 신청하면 전액 환불됩니다.\n2. 사용한 상품은 환불되지 않습니다.\n3. 배송비는 고객이 부담합니다." }, "usage": { "prompt_tokens": 1240, "completion_tokens": 58, "total_tokens": 1298 }, "compacted_messages": [ { "role": "system", "content": "당신은 한국어 AI 어시스턴트입니다. 모든 답변은 한국어로 작성합니다. 사용자가 명시적으로 다른 언어를 요청한 경우에만 해당 언어로 응답합니다. 답변은 명확하고 간결하게, 필요한 경우 Markdown 서식(목록·코드 블록·굵은 글씨)을 활용합니다." }, { "role": "user", "content": "환불 규정을 세 줄로 요약해 줘." }, { "role": "assistant", "content": "1. 구매 후 7일 안에 신청하면 전액 환불됩니다.\n2. 사용한 상품은 환불되지 않습니다.\n3. 배송비는 고객이 부담합니다." } ], "ic_id": null, "result": 1, "msg": "", "success": 1 }, "api": { "success": true, "cost": 5, "ms": 1830, "pl_id": 12345 } } ## 상세 코드·정책 오류 코드 HTTPdata.msg대처 400unsupported model (text-generation 카탈로그 외)deepseek-flash·deepseek-pro 철자를 확인하세요. 400unsupported speedfast·medium·slow(또는 한글 값)만 씁니다. 402잔액 부족 …포인트를 충전하거나 max_tokens를 낮추세요. 404세션을 찾을 수 없습니다. …만료·삭제된 세션입니다. 새 세션을 만드세요. 409이 세션은 다른 요청을 처리하는 중입니다. …같은 세션의 앞 요청이 끝난 뒤 보내세요. 503현재 이용 요금을 확인할 수 없습니다. …잠시 후 다시 요청하세요. 502외부 처리 서비스 응답 오류data.retryable이 true면 잠시 뒤 한 번만 다시 보내세요. 실패한 요청은 api.cost가 0이며 차감되지 않습니다.