> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Kimi Chat Completion API 신청 및 사용 > Kimi API guide - Ace Data Cloud Kimi는 월의 어두운 면에서 출시한 AI 모델 시리즈입니다. 현재 추천하는 `kimi-k3`는 장기 프로그래밍, 에이전트, 복잡한 추론 및 지식 작업을 대상으로 하며, OpenAI 호환 Chat Completions API를 통해 호출할 수 있습니다. 이 문서는 Kimi Chat Completion API 작업의 사용 프로세스를 주로 소개하며, 이를 통해 공식 Kimi의 대화 기능을 쉽게 사용할 수 있습니다. ## 신청 프로세스 Kimi Chat Completion API를 사용하려면 먼저 [Ace Data Cloud 콘솔](https://platform.acedata.cloud/console/applications)에서 API Token을 받아야 하며, 이를 보관해 두십시오. ![](https://cdn.acedata.cloud/5hmkdg.jpg) 로그인 또는 등록이 되어 있지 않은 경우, 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 요청합니다. 완료 후 현재 페이지로 자동으로 돌아옵니다. **하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스에 대해 별도로 신청할 필요가 없습니다.** 처음 신청 시 무료 크레딧이 제공되어 무료로 체험할 수 있으며, 크레딧이 부족할 경우 [콘솔](https://platform.acedata.cloud/console/coin)에서 일반 잔액을 충전할 수 있습니다. > 📘 전체 문서: [Kimi Chat Completion API →](https://platform.acedata.cloud/documents/kimi-chat-completions) ## 기본 사용 이제 인터페이스에 해당 내용을 입력할 수 있습니다. 아래 그림과 같이 진행하십시오:

이 인터페이스를 처음 사용할 때는 최소한 세 가지 내용을 입력해야 합니다: `authorization`은 드롭다운 목록에서 직접 선택할 수 있으며; `model`은 Kimi 모델을 선택하는 데 사용되며, `kimi-k3`를 추천합니다; `messages`는 대화 메시지 배열로, 각 메시지는 `role`과 `content`를 포함하며, `role`은 `user`, `assistant`, `system` 및 `tool`을 지원합니다. 또한 오른쪽에 해당 호출 코드 생성이 있음을 알 수 있으며, 코드를 복사하여 직접 실행할 수도 있고, "Try" 버튼을 클릭하여 테스트할 수도 있습니다.

다음은 `reasoning_effort: max`를 사용하여 얻은 실제 K3 응답입니다(사용하지 않은 확장 필드는 생략됨): ```json theme={null} { "id": "msg_2D4Btbg1WgvkNE3tCYkR4xGA", "object": "chat.completion", "created": 1784466588, "model": "kimi-k3", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "안녕하세요! 오늘 무엇을 도와드릴까요?" }, "logprobs": null, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 86, "completion_tokens": 206, "total_tokens": 292 } } ``` 반환 결과는 여러 필드를 포함하며, 다음과 같이 설명됩니다: * `id`, 이번 대화 작업을 생성한 ID로, 이번 대화 작업을 고유하게 식별하는 데 사용됩니다. * `model`, 선택한 Kimi 공식 모델입니다. * `choices`, Kimi가 질문에 대해 제공한 답변 정보입니다. * `usage`: 이번 질문-답변 쌍에 대한 토큰 통계 정보입니다. 그 중 `choices`는 Kimi의 답변 정보를 포함하고 있으며, 그 안의 `choices`는 Kimi의 구체적인 답변 정보를 포함하고 있습니다. 아래 그림과 같이 확인할 수 있습니다.

`choices` 안의 `content` 필드에는 Kimi의 구체적인 답변 내용이 포함되어 있습니다. K3는 또한 추론 과정을 나타내기 위해 `reasoning_content`를 반환할 수 있습니다. ## K3 추론 강도 `kimi-k3`는 항상 추론을 활성화합니다. 요청 본문의 최상위는 `reasoning_effort` 필드를 지원하며, 현재 유일하게 지원되는 값은 `max`입니다; 이 필드를 생략할 경우에도 `max`가 사용됩니다. `standard`, `high` 또는 기타 문자열은 일부 호환되는 상위에서 느슨하게 수용될 수 있지만, 추론 동작을 변경할 것이라는 보장은 없으므로 의존하지 마십시오. ```bash theme={null} curl https://api.acedata.cloud/kimi/chat/completions \ -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "kimi-k3", "messages": [{"role": "user", "content": "이 코드를 검토하고 수정안을 제시하십시오"}], "reasoning_effort": "max" }' ``` OpenAI SDK를 사용할 때는 이 필드를 직접 전달할 수 있습니다: ```python theme={null} response = client.chat.completions.create( model="kimi-k3", messages=[{"role": "user", "content": "신뢰할 수 있는 작업 큐를 설계하십시오"}], reasoning_effort="max", ) ``` 다중 대화 및 도구 호출 시, 이전 라운드의 전체 assistant 메시지를 `messages`에 다시 전달해야 하며, `reasoning_content` 및 `tool_calls`를 포함해야 합니다. ### 공식 참고 * [Thinking Effort](https://platform.kimi.ai/docs/guide/use-thinking-effort): Kimi K3가 항상 추론을 활성화하며, 현재 `reasoning_effort`의 유일한 지원 값이 `max`임을 설명합니다. * [Model Parameter Reference](https://platform.kimi.ai/docs/api/models-overview): K3와 K2 시리즈의 추론 매개변수, 컨텍스트 창 및 도구 호출 차이를 비교합니다. * [Create Chat Completion](https://platform.kimi.ai/docs/api/chat): Moonshot 공식 Chat Completions 요청, 응답 및 OpenAPI 필드 정의입니다. ## 스트리밍 응답 이 인터페이스는 스트리밍 응답도 지원하며, 이는 웹 페이지 통합에 매우 유용하여 웹 페이지에서 글자 단위로 표시하는 효과를 구현할 수 있습니다. 응답을 스트리밍으로 반환하려면 요청 헤더의 `stream` 매개변수를 `true`로 변경하면 됩니다. 아래 그림과 같이 수정하되, 호출 코드는 스트리밍 응답을 지원하도록 적절한 변경이 필요합니다.

`stream`을 `true`로 변경하면 API는 해당 JSON 데이터를 줄 단위로 반환하며, 코드 측면에서 우리는 줄 단위 결과를 얻기 위해 적절한 수정을 해야 합니다. Python 샘플 호출 코드: ```python theme={null} import requests url = "https://api.acedata.cloud/kimi/chat/completions" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "kimi-k3", "messages": [{"role":"user","content":"안녕하세요"}], "reasoning_effort": "max", "stream": True } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` 다음은 동일한 실제 K3 Max 스트리밍 응답에서 시작, 추론, 본문, 종료 및 사용량 데이터 블록의 발췌입니다: ```json theme={null} data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[{"index":0,"delta":{"content":"","role":"assistant"},"finish_reason":null}],"usage":null} data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[{"index":0,"delta":{"reasoning_content":"그"},"finish_reason":null}],"usage":null} data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[{"index":0,"delta":{"content":"안녕하세요"},"finish_reason":null}],"usage":null} data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":null} data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[],"usage":{"prompt_tokens":172,"completion_tokens":168,"total_tokens":340}} data: [DONE] ``` 볼 수 있듯이, 응답 안에는 많은 `data`가 있으며, `data` 안의 `choices`는 최신의 답변 내용으로, 위에서 소개한 내용과 일치합니다. `choices`는 추가된 답변 내용이며, 결과에 따라 시스템에 연결할 수 있습니다. 또한 스트리밍 응답의 종료는 `data`의 내용을 기준으로 판단하며, 내용이 `[DONE]`일 경우 스트리밍 응답이 모두 종료되었음을 나타냅니다. 반환된 `data` 결과는 여러 필드를 포함하며, 설명은 다음과 같습니다: * `id`, 이번 대화 작업을 생성한 ID로, 이번 대화 작업을 고유하게 식별하는 데 사용됩니다. * `model`, 선택한 Kimi 공식 모델입니다. * `choices`, Kimi가 질문에 대해 제공한 답변 정보입니다. JavaScript도 지원되며, 예를 들어 Node.js의 스트리밍 호출 코드는 다음과 같습니다: ```javascript theme={null} const options = { method: "post", headers: { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" }, body: JSON.stringify({ "model": "kimi-k3", "messages": [{"role":"user","content":"안녕하세요"}], "stream": true }) }; fetch("https://api.acedata.cloud/kimi/chat/completions", options) .then(response => response.json()) .then(response => console.log(response)) .catch(err => console.error(err)); ``` Java 샘플 코드: ```java theme={null} JSONObject jsonObject = new JSONObject(); jsonObject.put("model", "kimi-k3"); jsonObject.put("messages", [{"role":"user","content":"안녕하세요"}]); jsonObject.put("stream", true); MediaType mediaType = "application/json; charset=utf-8".toMediaType(); RequestBody body = jsonObject.toString().toRequestBody(mediaType); Request request = new Request.Builder() .url("https://api.acedata.cloud/kimi/chat/completions") .post(body) .addHeader("accept", "application/json") .addHeader("authorization", "Bearer {token}") .addHeader("content-type", "application/json") .build(); OkHttpClient client = new OkHttpClient(); Response response = client.newCall(request).execute(); System.out.print(response.body!!.string()) ``` 다른 언어는 별도로 수정할 수 있으며, 원리는 모두 동일합니다. ## 다중 대화 여러 번의 대화 기능을 연결하려면 `messages` 필드에 여러 질문을 업로드해야 하며, 여러 질문의 구체적인 예시는 아래 그림과 같습니다:

Python 샘플 호출 코드: ```python theme={null} import requests url = "https://api.acedata.cloud/kimi/chat/completions" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "kimi-k3", "messages": [{"role":"assistant","content":"안녕하세요! 오늘 무엇을 도와드릴까요?"},{"role":"user","content":"어떤 모델인가요?"}], "reasoning_effort": "max" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` 여러 질문을 업로드하면 쉽게 다중 대화를 구현할 수 있습니다. 다음은 해당 요청으로 얻은 실제 K3 Max 응답입니다(사용하지 않은 확장 필드는 생략됨): ```json theme={null} { "id": "msg_Rqp8nPGBDHWwBlL4VpxuafOp", "object": "chat.completion", "created": 1784466628, "model": "kimi-k3", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "저는 Kimi입니다, Moonshot AI(달의 어두운 면)에서 개발한 AI 어시스턴트입니다. 여기서 공유할 특정 공개 모델 버전 식별자는 없습니다." }, "logprobs": null, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 134, "completion_tokens": 346, "total_tokens": 480 } } ``` `choices`에 포함된 정보는 기본 사용 내용과 일치하며, 이는 Kimi가 여러 대화에 대해 응답한 구체적인 내용을 포함하고 있어, 여러 대화 내용을 기반으로 해당 질문에 답변할 수 있습니다. ## 오류 처리 API를 호출할 때 오류가 발생하면, API는 해당 오류 코드와 정보를 반환합니다. 예를 들어: * `400 token_mismatched`: 잘못된 요청, 누락되었거나 잘못된 매개변수 때문일 수 있습니다. * `400 api_not_implemented`: 잘못된 요청, 누락되었거나 잘못된 매개변수 때문일 수 있습니다. * `401 invalid_token`: 인증되지 않음, 잘못되었거나 누락된 인증 토큰입니다. * `429 too_many_requests`: 너무 많은 요청, 비율 제한을 초과했습니다. * `500 api_error`: 내부 서버 오류, 서버에서 문제가 발생했습니다. ### 오류 응답 예시 ``` { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## 결론 이 문서를 통해 Kimi Chat Completion API를 사용하여 일반 대화, 스트리밍 응답, 다중 대화 및 `reasoning_effort`를 통해 K3의 추론 강도를 제어하는 방법을 이해하게 되었습니다.