Kimi K3.1 Pro image and video input configuration: Base64, file IDs, and multimodal message structure

One-sentence takeaway

For Kimi K3.1 Pro vision requests, write the user message's content as a JSON array; images can use a Base64 image_url, while videos must be uploaded first and then referenced through a video_url using ms://<file-id>.

Use cases

• Suitable tasks: Configuring image understanding, video understanding, and multi-image messages in Kimi API Chat Completions.

• Unsuitable tasks: Passing a public image URL directly to the model, uploading an SVG as an image, or inferring unpublished file-size and video-duration limits from this information.

• Applicable model versions: kimi-k3.1-pro; the official page also lists kimi-k3, kimi-k2.6, kimi-k2.7-code, and kimi-k2.7-code-highspeed, and states that these models can understand videos.

• Applicable clients, agents, or APIs: Kimi API Chat Completions; the official example uses the Python OpenAI SDK and https://api.moonshot.ai/v1.

• Recommended reasoning level and parameters: This article does not add reasoning configuration; the official recommendation is to use the model's default parameter values and not set temperature, top_p, or n manually unless the constraints for the corresponding model have been checked.

Ready-to-use content

Image: Convert a local file to Base64

import base64
import os
from openai import OpenAI

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

image_path = "kimi.png"
with open(image_path, "rb") as f:
    image_data = f.read()
image_url = (
    f"data:image/{os.path.splitext(image_path)[1].lstrip('.')};base64,"
    f"{base64.b64encode(image_data).decode('utf-8')}"
)

completion = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": image_url}},
            {"type": "text", "text": "Describe this image."},
        ],
    }],
)
print(completion.choices[0].message.content)

The key structure is:

{
  "type": "image_url",
  "image_url": {"url": "data:image/png;base64,<base64-data>"}
}

Videos cannot use the image Base64 structure above. The official example first uploads the file with purpose="video", then uses the following in the message:

{
  "type": "video_url",
  "video_url": {"url": "ms://<file-id>"}
}

After an image or video, you can add task instructions as an object with type: "text" in the same content array. content must be an array of objects; the array cannot be serialized into a string.

Testing or workflow steps

1. Confirm that the request uses model: "kimi-k3.1-pro" and Chat Completions.

2. Read the image as binary and encode it as data:image/<extension>;base64,<data>.

3. Put the image and text instructions into separate objects in the same user message's content array.

4. Upload the video through the Files API first; the example uses purpose set to video.

5. Assemble the uploaded file ID as ms://<file-id> and put it in video_url.url.

6. For larger inputs or inputs that need to be referenced multiple times, prioritize file uploads; very large videos must use file uploads because the request body has an overall size limit.

7. Before sending a vision request, you can call the estimate tokens API to estimate image or video token consumption.

Original evidence and data

• The official page explicitly includes kimi-k3.1-pro in Kimi Vision Model and states that this model can understand images and videos.

• Supported image MIME types: image/jpeg, image/png, image/gif, image/webp, image/bmp, image/heic, and image/heif.

• Animated GIF and WebP are also passed through image_url, but the underlying system may decode them as video, with token usage calculated as video.

• SVG is not supported as image input; uploading an SVG or passing it through image_url (including Base64) will be rejected. To understand an SVG, put the SVG XML source code into the message as text.

• Supported video MIME types: video/mp4, video/mpeg, video/mov, video/avi, video/x-flv, video/mpg, video/webm, video/wmv, and video/3gpp.

• The official recommendation is to keep image resolution at or below 4K (4096×2160) and video resolution at or below FHD (1920×1080); higher resolutions only increase processing time and do not improve understanding performance.

• Vision models have no image-count limit, but a single request body must not exceed 100M. The page gives no separate numeric limit for a single image, a single file, or video duration.

• Images in URL format are unsupported; the current supported options are Base64 image content and images or videos referenced through file IDs.

• The page lists support for multi-turn conversations, streaming output, tool calls, JSON Mode, and Partial Mode.

• Images and videos are accounted for using dynamic tokens; higher resolution generally consumes more tokens, while video consumption also depends on the number of keyframes and the resolution.

• This article did not use an API key to make a local request and contains no locally measured success rate, latency, response content, or compatibility results.

Scope and limitations

• 100M is the maximum single-request body size given by the official source; it does not mean that each image or video file may occupy 100M.

• “No image-count limit” remains subject to the request-body size limit; the page gives no fixed number of images that a single request can contain.

• 4K and FHD are officially recommended resolutions, not hard rejection thresholds stated by the page.

• The page gives no fixed upper limit for video duration, frame rate, file size, or keyframe count; this article does not add those values.

• The official example uses an ms:// file reference; do not rewrite it as a public URL or disguise a video object as an image_url.

Reproduction notes

1. Open the official Configure Kimi Vision Models page and confirm the page body and normalized URL.

2. Run the Python example above with a non-sensitive image; set MOONSHOT_API_KEY before running and prepare a local kimi.png.

3. Inspect the request body and confirm that messages[0].content is an array whose elements are separate image_url and text objects.

4. To verify video input, upload a file through the Files API and record the returned file ID, then construct the video_url with ms://<file-id>.

5. This collection only verified the official documentation; no real API request was submitted, so there are no local API test results.