Kimi K3.1 Pro

공개 모델 ID kimi-k3.1-pro를 사용합니다. 모델 페이지에서 Playground와 실시간 요금을 확인할 수 있습니다. 중첩된 요청과 응답의 전체 스키마는 OpenAPI 명세를 다운로드해 확인하세요.

빠른 시작

curl https://api.seedrouter.ai/v1/chat/completions \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"kimi-k3.1-pro",
    "messages":[{"role":"user","content":"How can an idempotency key prevent a duplicate payment?"}],
    "max_completion_tokens":2048,
    "reasoning_effort":"low"
  }'

네이티브 요청 형식

Authorization: Bearer $SEEDROUTER_API_KEY를 사용합니다. Messages에서는 anthropic-version: 2023-06-01도 사용합니다. 각 형식은 고유한 JSON 또는 SSE 이벤트를 반환합니다. Responses는 상태를 저장하지 않으므로 전체 기록을 재전송해야 합니다. previous_response_id는 지원되는 요청 필드가 아닙니다.

요청 매개변수

Playground에서 빈 필드는 생략됩니다. 유효한 경우 명시적인 false와 0은 유지됩니다. 생략 가능하다고 null이 허용되는 것은 아닙니다. 알 수 없는 최상위 확장 필드는 버리고, 잘못된 공식 필드는 거부합니다. 중첩 도구 스키마와 반환된 기록은 그대로 유지됩니다.

Chat Completions

Responses

Messages

Chat에는 최상위 필드가 22개 있습니다. model, 고정 샘플링 필드 5개, 가변 입력 16개로 구성됩니다. Responses는 model과 입력 12개, Messages는 model과 입력 10개입니다. Playground에서는 고정 model과 고정 샘플링 설정을 숨깁니다.

추론 및 출력 한도

사고 기능은 항상 활성화됩니다. Chat의 reasoning_effort, Responses의 reasoning.effort, Messages의 output_config.effort는 low, high, max를 허용하며 기본값은 max입니다. 모든 출력 한도에는 추론이 포함됩니다. Chat과 Responses의 기본 출력은 131,072 토큰이며 최대 1,048,576입니다. Messages에는 양수인 max_tokens가 필수입니다. Chat은 지원 중단 예정인 max_tokens도 허용하지만, 새 연동에는 max_completion_tokens를 권장합니다.

컨텍스트 윈도우는 1,048,576 토큰입니다. 입력 자체가 이 범위 안에 있어야 합니다. 입력과 생성 한도의 합이 윈도우를 넘으면 서비스가 한도를 남은 공간으로 줄일 수 있습니다. 출력 상한이 작으면 표시할 답변이 나오기 전에 중단될 수 있습니다.

Chat 샘플링 값은 temperature:1, top_p:0.95, n:1, frequency_penalty:0, presence_penalty:0으로 고정됩니다. 다른 값은 유효하지 않습니다. 중지 시퀀스는 텍스트와 정확히 일치할 때 적용되며 답변에서 제외됩니다. 32바이트 제한은 문자 수가 아닌 UTF-8 바이트 수를 뜻합니다.

구조화 출력 및 예측 출력

Chat의 response_format.type은 text, json_object, json_schema를 허용합니다. JSON 모드에서는 프롬프트에서도 JSON을 요청해야 합니다. JSON Schema에는 json_schema.name과 json_schema.schema가 필수이며 strict의 기본값은 true입니다.

Responses는 text.format에 type:json_schema, schema, 선택 사항인 name과 strict를 사용합니다. Messages는 output_config.format에 type:json_schema와 schema를 사용합니다. Moonshot Flavored JSON Schema를 따르세요. 일반 JSON Schema의 모든 확장 기능이 강제된다고 가정하면 안 됩니다. 완성된 출력은 앱에서 검증하세요.

Chat 예측 출력은 prediction:{type:"content",content:...}를 사용합니다. content는 문자열 또는 텍스트 전용 부분입니다. 소폭 수정하는 파일처럼 출력 대부분을 이미 아는 경우에 사용합니다.

도구 및 대화 기록 보존

Chat 도구는 type:function과 function.name, function.parameters를 사용합니다. 선택 필드는 description과 strict이며 strict의 기본값은 true입니다. 이름은 ^[a-zA-Z_][a-zA-Z0-9-_]{0,127}$와 일치해야 합니다. 도구 선택은 auto, none, required를 지원하며 required에는 사용 가능한 도구가 최소 하나 필요합니다. 이름을 지정해 함수를 강제 호출하는 방식은 항상 켜진 사고 기능과 충돌합니다.

동적 Chat 도구 메시지는 content가 없는 {role:"system",tools:[...]}입니다. 이 메시지를 대화에 보존하세요. reasoning_content와 tool_calls를 포함한 전체 assistant 응답을 추가한 뒤, 각 도구 결과를 일치하는 tool_call_id가 있는 role:tool 메시지로 반환합니다. assistant 도구 응답의 content는 null일 수 있습니다. 다른 메시지 역할에는 여전히 content가 필요합니다.

Responses는 네이티브 function, namespace, apply_patch 사용자 정의 도구, web_search 도구 정의를 tool_choice:"auto"와 함께 지원합니다. 호출 ID가 일치하는 function_call_output 또는 custom_tool_call_output 항목을 반환하세요. include 값인 web_search_call.results와 web_search_call.action.sources는 웹 검색 출력에만 영향을 줍니다.

Messages는 네이티브 도구 정의와 type이 auto, any, none인 도구 선택 객체를 지원합니다. assistant 사고 블록과 서명을 보존하세요. 도구 결과 블록은 user 메시지 안에 반환합니다. 앱이 인수를 검증하고 사용자 정의 함수를 실행하며 외부 작업을 제어합니다.

Chat Partial Mode는 마지막 assistant 메시지에만 partial:true를 설정합니다. Messages는 마지막 assistant 메시지를 바로 이어서 작성합니다. 표시된 답변 텍스트만으로 기록을 재구성하지 마세요.

미디어 제약

Chat은 텍스트, image_url, video_url 콘텐츠 블록을 지원합니다. base64 data URL 또는 허용되는 ms:// 참조를 사용하세요. 임의의 공개 미디어 URL은 지원되지 않습니다. 이미지 형식은 JPEG, PNG, GIF, WebP, BMP, HEIC, HEIF이며 동영상 형식은 MP4, MPEG, MOV, AVI, FLV, MPG, WebM, WMV, 3GPP입니다. 공식 가이드는 전체 요청 본문 한도를 100M으로 명시하며 이미지 수에는 별도 상한이 없습니다. 4K 이미지와 Full HD 동영상은 권장 사항이며 필수 제한이 아닙니다.

Responses는 data URL을 포함하는 input_image.image_url을 사용합니다. Messages는 {type:"base64",media_type:"image/png",data:"..."} 같은 이미지 소스 또는 type이 url이고 허용된 ms:// 참조를 가진 소스를 사용합니다. Messages의 인라인 이미지 형식은 JPEG, PNG, GIF, WebP입니다. 이 형식들이 Chat의 동영상 블록까지 지원한다고 추정하면 안 됩니다. 각 전용 스키마를 사용하세요.

Playground는 인라인 이미지를 첨부합니다. 동영상 블록과 파일 참조에는 네이티브 대화 필드 또는 JSON 편집기를 사용하세요. 파일 업로드와 관리는 이 생성 엔드포인트에 포함되지 않습니다. 다른 계정에서 만든 파일 ID는 사용하지 못할 수도 있습니다.

캐시 및 사용량

Chat과 Responses는 prompt_cache_key와 prompt_cache_options:{mode:"implicit",ttl:"5m"}를 사용합니다. TTL은 5m 또는 1h이며 기본값은 5분입니다. Messages는 최상위 cache_control:{type:"ephemeral",ttl:"5m"}과 선택적인 metadata.user_id를 사용합니다. 중첩된 Messages 캐시 제어 표시는 무시됩니다. 콘텐츠 수준의 prompt_cache_breakpoint는 유효하지 않습니다.

기존 캐시 접두부는 갱신되어도 원래 TTL을 유지합니다. 다른 유효 기간을 요청했다는 사실만으로 적용되었다고 볼 수 없습니다. Chat의 공식 캐시 쓰기 헤더는 실제 5분 및 1시간 수치를 보고합니다. Responses는 적용된 prompt_cache_options를 반환할 수 있습니다. Messages는 usage.cache_creation에서 두 TTL의 카운터를 보고합니다.

Chat과 Responses의 입력 합계에는 이미 캐시 읽기와 쓰기가 포함됩니다. 이 항목들과 캐시되지 않은 나머지는 서로 겹치지 않으므로 캐시 토큰을 두 번 더하지 마세요. 출력에는 추론이 포함됩니다. Messages는 쓰기를 ephemeral_5m_input_tokens와 ephemeral_1h_input_tokens로 나눕니다. 실시간 요금을 확인하세요. 공개 생성 응답에는 금액이 포함되지 않습니다.

스트리밍 및 완료

stream:true로 설정합니다. Chat은 데이터 청크와 [DONE]을 내보냅니다. stream_options.include_usage:true는 마지막 사용량 청크를 요청합니다. Responses는 response.output_text.delta, response.completed, response.incomplete 같은 이름 있는 이벤트를 사용합니다. Messages는 message_start, 콘텐츠 블록 이벤트, message_delta, message_stop을 사용합니다.

연결이 닫혔다는 사실만으로 완료되었다고 볼 수 없습니다. 형식별 종료 사유와 최종 상태를 확인하세요. 스트림이 중단되면 최종 사용량이 누락될 수 있습니다. 읽기를 중지해도 생성이 취소된다고 보장할 수 없습니다.

공식 참고 자료

2026년 10월 25일 확인: Kimi K3.1 Pro 가이드, Chat, Responses, Messages, 시각 입력, 캐싱.