채팅 엔드포인트

채팅 엔드포인트 (Chat Endpoints)

Chat Completion API입니다. 대화를 주고받으며 모델이 응답을 생성하는 핵심 엔드포인트예요.

출처: 문서

본문

대화형 완성(chat completion)을 요청하는 엔드포인트입니다. 메시지 목록과 모델을 넘기면 모델이 이어지는 응답을 만들어내요.

POST /v1/chat/completions — Chat Completion (채팅 완성)

채팅 완성 결과를 요청합니다.

요청 본문:

  • messages#array<SystemMessage|UserMessage|AssistantMessage|ToolMessage> (필수) — 완성을 생성할 프롬프트 목록. role과 content를 담은 dict 리스트로 인코딩돼요.
  • model#string (필수) — 사용할 모델의 ID. 사용 가능한 모델 목록은 List Available Models API로 확인하거나, 모델 개요를 참고하세요.
  • max_tokens#integer|null — 생성할 최대 토큰 수. 프롬프트 토큰 수 + max_tokens가 모델의 컨텍스트 길이를 넘으면 안 돼요.
  • temperature#number|null — 샘플링 온도. 0.0~0.7 사이를 권장해요. 0.7에 가까우면 더 다양한(랜덤한) 출력, 0.2에 가까우면 더 집중적이고 결정적인 출력이 나와요. 보통 temperature와 top_p 중 하나만 바꾸는 걸 권장해요. 기본값은 타깃 모델에 따라 달라지며, /models 엔드포인트로 확인할 수 있어요.
  • top_p#number|null — Nucleus sampling. 모델이 상위 top_p 확률 질량에 해당하는 토큰만 고려해요. 예를 들어 0.1이면 상위 10% 확률 질량의 토큰만 보는 거예요. temperature와 둘 다 바꾸기보다 하나만 바꾸는 걸 권장해요.
  • n#integer|null — 요청당 반환할 완성 개수. 입력 토큰은 한 번만 청구돼요.
  • stop#string|array<string>|null — 이 토큰이 감지되면 생성을 멈춰요. 배열이면 그중 하나라도 감지되면 종료.
  • stream#boolean — 기본값 false. 부분 진행을 스트리밍할지 여부. true면 토큰이 data-only 서버 이벤트로 전송되고 data: [DONE] 메시지로 종료돼요. false면 서버가 완료까지 요청을 붙잡고 전체 결과를 JSON으로 반환해요.
  • random_seed#integer|null — 랜덤 샘플링 시드. 설정하면 같은 입력에 대해 결정적인 결과가 나와요.
  • frequency_penalty#number|null — 생성 텍스트에서 단어의 빈도에 기반해 반복을 패널티하는 값. 높을수록 자주 등장한 단어 반복을 억제해서 다양성을 높여요.
  • presence_penalty#number|null — 단어·구 반복을 얼마나 패널티할지 결정. 높을수록 더 다양한 단어를 쓰게 돼 다양하고 창의적인 출력이 나와요.
  • response_format#ResponseFormat|null — 모델이 출력해야 할 형식. 기본은 { "type": "text" }. { "type": "json_object" }로 설정하면 JSON 모드가 켜져 모델이 JSON으로 출력함을 보장해요. JSON 모드에선 system/user 메시지로 스스로 JSON을 만들 것을 지시해야 해요. { "type": "json_schema" }로 설정하면 JSON 스키마 모드가 켜져 JSON이면서 제공한 스키마를 따르는 출력을 보장해요.
  • tools#array<Tool|WebSearchTool|WebSearchPremiumTool|CodeInterpreterTool|ImageGenerationTool|DocumentLibraryTool|CustomConnector>|null — 모델이 호출할 수 있는 도구 목록. 모델이 JSON 입력을 생성할 수 있는 함수 목록을 제공하는 데 씁니다.
  • tool_choice#ToolChoice|"auto"|"none"|"any"|"required" — 모델이 호출할 도구(있으면)를 제어. none은 도구를 호출하지 않고 메시지만 생성. auto는 메시지 생성과 도구 호출 중 선택. any/required는 반드시 하나 이상의 도구를 호출. {"type": "function", "function": {"name": "my_function"}}처럼 특정 도구를 지정하면 그 도구를 강제로 호출해요.
  • parallel_tool_calls#boolean — 기본값 true. 도구 사용 중 병렬 함수 호출을 켤지 여부. 켜면 모델이 여러 도구를 병렬로 호출할 수 있어요.
  • guardrails#array<GuardrailConfig>|null — 가드레일 설정.
  • metadata#map<any>|null — 메타데이터.
  • safe_prompt#boolean — 기본값 false. 모든 대화 앞에 안전 프롬프트를 주입할지 여부.
  • service_tier#"auto"|"standard_only" — 요청을 우선순위 용량으로 처리할지 표준 용량으로 처리할지 결정.
  • prompt_cache_key#string|null — 프롬프트 캐싱용 캐시 키. 멀티턴 대화나 반복되는 system 프롬프트처럼 공유 프롬프트 접두어가 있는 요청에 같은 키를 쓰면 캐시 히트율이 올라가요. 캐시된 토큰은 표준 입력 토큰 가격의 10%로 청구돼요.
  • prompt_mode#"reasoning" — chat completion 엔드포인트의 prompt_mode 인자에 쓸 수 있는 값. 값은 높은 수준의 의도를 나타내며, 실제 SP 할당은 내부적으로 처리돼요. system 프롬프트는 지식 컷오프 날짜, 모델 능력, 사용할 톤, 안전 지침 등을 포함할 수 있어요.
  • reasoning_effort#"none"|"minimal"|"low"|"medium"|"high"|"xhigh" — 추론 강도.
  • prediction#Prediction|null — 예상 완성을 지정해 알려진·예측 가능한 콘텐츠를 활용해 응답 시간을 최적화할 수 있어요.

응답:

  • 200 (application/json) — Successful Response:
    • id#string (필수)
    • object#string (필수)
    • created#integer (필수)
    • model#string (필수)
    • choices#array<ChatCompletionChoice> (필수)
    • usage#UsageInfo (필수)
  • 200 (text/event-stream) — 타입 event-stream<CompletionEvent>:
    • CompletionEvent — {object}

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({ apiKey: proces..._KEY });

const response = await client.chat.complete({
  model: "mistral-large-latest",
  messages: [
    {
      role: "user",
      content: "Who is the best French painter? Answer in one short sentence.",
    },
  ],
});

console.log(response.choices[0].message.content);

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:
    response = mistral.chat.complete(
        model="mistral-large-latest",
        messages=[
            {
                "role": "user",
                "content": "Who is the best French painter? Answer in one short sentence.",
            }
        ],
    )

    print(response.choices[0].message.content)

curl:

curl https://api.mistral.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "mistral-large-latest",
    "messages": [
      {
        "role": "user",
        "content": "Who is the best French painter? Answer in one short sentence."
      }
    ]
  }'

응답 예시 (200, application/json):

{
  "choices": [
    {
      "finish_reason": "stop",
      "index": "<to fill>"
    }
  ],
  "created": "1702256327",
  "id": "cmpl-e5cc70bb28c444948073e77776eb30ef",
  "model": "mistral-small-latest",
  "object": "chat.completion",
  "usage": {}
}

더 알아보기 (Learn more)