Kimi Vision

상위 문서: ← Kimi Model Capabilities 출처: Kimi API Platform 공식 문서 — Configure Kimi Vision Models 한글화 (2026-07-22) 공급사: Moonshot AI (月之暗面)

Kimi Vision Model(kimi-k3, moonshot-v1-8k-vision-preview, moonshot-v1-32k-vision-preview, moonshot-v1-128k-vision-preview, kimi-k2.5, kimi-k2.6, kimi-k2.7-code, kimi-k2.7-code-highspeed 등)은 이미지 내 텍스트, 색상, 객체의 모양 등 시각적 콘텐츠를 이해할 수 있습니다. kimi-k3, kimi-k2.6, kimi-k2.7-code, kimi-k2.7-code-highspeed 모델은 비디오 콘텐츠도 이해할 수 있습니다. 모델이 이미지나 비디오를 인식해야 한다면, 이 페이지의 설명대로 멀티모달 요청을 구성하세요.

---

1. Base64로 이미지 직접 업로드

다음 예제는 로컬 이미지를 base64로 인코딩해 Kimi에 image_url 메시지 part로 전달하고, 이미지에 대한 질문을 던집니다.

import os
import base64
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("MOONSHOT_API_KEY"),
    base_url="https://api.moonshot.ai/v1",
)

# kimi.png를 인식할 이미지 경로로 교체
image_path = "kimi.png"

with open(image_path, "rb") as f:
    image_data = f.read()

# 표준 라이브러리 base64.b64encode로 이미지를 base64 포맷 image_url로 인코딩
image_url = f"data:image/{os.path.splitext(image_path)[1].lstrip('.')};base64,{base64.b64encode(image_data).decode('utf-8')}"


completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "system", "content": "You are Kimi."},
        {
            "role": "user",
            # 원래 str 타입이었던 content가 list로 변경됨 — 이미지(image_url)와 텍스트(text)가 각각 part
            "content": [
                {
                    "type": "image_url",  # <-- image_url 타입으로 이미지 업로드, content는 base64 인코딩된 이미지
                    "image_url": {
                        "url": image_url,
                    },
                },
                {
                    "type": "text",
                    "text": "Describe the content of the image.",  # <-- text 타입으로 텍스트 지시 제공
                },
            ],
        },
    ],
)

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

⚠️ Vision 모델 사용 시: message.content는 반드시 array[object] (JSON 배열) 여야 합니다. JSON 배열을 직렬화해 message.content에 string으로 넣지 마세요 — 비표준 포맷이라 모델이나 버전에 따라 시각 입력으로 처리되지 않을 수 있습니다. 항상 위 예시처럼 배열 포맷을 사용하세요.

올바른 포맷 — content는 여러 part의 JSON 배열:

{
  "model": "kimi-k3",
  "messages": [
    {
      "role": "system",
      "content": "You are Kimi, an AI assistant provided by Moonshot AI, who excels in Chinese and English conversations. You provide users with safe, helpful, and accurate answers. You will reject any questions related to terrorism, racism, or explicit content. Moonshot AI is a proper noun and should not be translated into other languages."
    },
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,<base64 인코딩된 이미지>"
          }
        },
        {
          "type": "text",
          "text": "Please describe this image."
        }
      ]
    }
  ]
}

잘못된 포맷 — 배열을 문자열로 직렬화:

{
  "model": "kimi-k3",
  "messages": [
    {
      "role": "system",
      "content": "You are Kimi, an AI assistant provided by Moonshot AI..."
    },
    {
      "role": "user",
      "content": "[{\"type\": \"image_url\", \"image_url\": {\"url\": \"data:image/png;base64,...\"}}, {\"type\": \"text\", \"text\": \"Please describe this image\"}]"
    }
  ]
}

---

2. 파일 ID로 업로드된 이미지/비디오 참조

비디오 파일은 크기가 큰 경우가 많아, 먼저 Moonshot에 이미지나 비디오를 업로드한 뒤 파일 ID로 참조할 수 있습니다 — 업로드 API는 Image Understanding Upload 참고. 다음 예제는 비디오 파일을 업로드한 뒤 ms:// 프로토콜을 사용하는 video_url로 모델에 전달해 설명을 요청합니다.

import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("MOONSHOT_API_KEY"),
    base_url="https://api.moonshot.ai/v1",
)

# video.mp4를 인식할 비디오 경로로 교체
video_path = "video.mp4"

file_object = client.files.create(file=Path(video_path), purpose="video")  # 비디오를 Moonshot에 업로드

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {
            "role": "system",
            "content": "You are Kimi, an AI assistant provided by Moonshot AI, who excels in Chinese and English conversations. You provide users with safe, helpful, and accurate answers. You will refuse to answer any questions involving terrorism, racism, or explicit content. Moonshot AI is a proper noun and should not be translated into other languages."
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "video_url",
                    "video_url": {
                        "url": f"ms://{file_object.id}"  # base64가 아닌 ms:// 사용
                    }
                },
                {
                    "type": "text",
                    "text": "Please describe this video"
                }
            ]
        }
    ]
)

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

위 예제에서 video_url.url의 포맷은 ms://<file-id>입니다. ms는 moonshot storage의 약자로, Moonshot의 파일 참조용 내부 프로토콜입니다.

---

3. 지원 형식

이미지:

• png
• jpeg
• webp
• gif

비디오:

• mp4
• mpeg
• mov
• avi
• x-flv
• mpg
• webm
• wmv
• 3gpp

---

4. 토큰 사용량 및 비용 예측

• 이미지와 비디오는 동적 토큰 계산을 사용합니다 — estimate tokens API로 처리 시작 전에 예상 토큰 소비량을 확인할 수 있습니다
• 일반적으로 이미지 해상도가 높을수록 더 많은 토큰을 소비합니다
• 비디오는 여러 키프레임으로 구성되며, 키프레임이 많고 해상도가 높을수록 더 많은 토큰을 소비
• Vision 모델은 moonshot-v1 시리즈와 동일한 가격 모델을 사용 — 처리한 총 토큰 수 기반 과금. 토큰 가격은 Model Inference Pricing 참고

---

5. 해상도 제한

• 이미지: 4K (4096×2160) 이하 권장
• 비디오: FHD (1920×1080) 이하 권장

권장보다 높은 해상도는 모델 이해 성능 개선 없이 처리 시간만 늘립니다.

---

6. Base64 vs 파일 업로드 선택 기준

• 요청 본문 크기 제한 때문에, 매우 큰 비디오는 반드시 파일 업로드 방식을 사용해야 시각 이해가 가능
• 여러 번 참조될 이미지/비디오도 파일 업로드 권장
• 파일 업로드 제한은 File Upload 문서 참고

---

7. 기능 지원 및 제한

Vision 모델이 지원하는 기능:

• 멀티턴 대화 (Multi-turn conversations)
• 스트리밍 출력 (Streaming output)
• 도구 호출 (Tool invocation)
• JSON Mode
• Partial Mode

지원하지 않거나 부분적으로만 지원되는 기능:

• URL 형식 이미지: 미지원 — 현재는 base64 인코딩된 이미지 콘텐츠와 파일 ID로 업로드된 이미지/비디오만 지원

기타 제한:

• 이미지 수량: Vision 모델은 이미지 수에 제한이 없으나, 요청 본문 크기가 100M를 넘지 않아야 함

서로 다른 모델은 temperature, top_p, n 등 파라미터에 대해 서로 다른 제약을 적용합니다. 수동 설정 대신 기본값 사용을 권장합니다. 자세한 내용은 Model Parameter Differences 참고.

---

변경 이력

날짜	변경
2026-07-22	초판 작성 (공식 Vision 가이드 한글화)
2026-07-22	제목에 "Kimi" 접두사 추가, 본문 H1 중복 제거