Kimi Files API 用于上传文档、图片、视频供模型处理。支持的用途（purpose）有四种：file-extract（文档提取）、image（图片理解）、video（视频理解）、batch（批量任务）。本文是五个文件操作接口的完整参考。

Kimi Files API 参考

文件限制

限制	值
单文件大小	≤ 100MB
单账户文件总量	≤ 10GB
最大文件数	1000 个

支持格式：.pdf, .txt, .csv, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .jpeg, .png, .gif, .webp, .mp4, .mov, .avi, .py, .js, .ts, .tsx, .yaml, .json 等

---

上传文件

POST https://api.moonshot.cn/v1/files
Content-Type: multipart/form-data
Authorization: Bearer {MOONSHOT_API_KEY}

参数	类型	必填	说明
file	file	✅	要上传的文件
purpose	string	✅	file-extract / image / video / batch

from openai import OpenAI
from pathlib import Path

client = OpenAI(
    api_key="$MOONSHOT_API_KEY",
    base_url="https://api.moonshot.cn/v1",
)

# 上传文档（用于文字提取）
file_object = client.files.create(
    file=Path("report.pdf"),
    purpose="file-extract",
)
print(f"文件 ID: {file_object.id}")

# 上传图片（用于视觉理解）
image_file = client.files.create(
    file=Path("screenshot.png"),
    purpose="image",
)

import fs from "fs";

const fileObject = await client.files.create({
  file: fs.createReadStream("report.pdf"),
  purpose: "file-extract",
});
console.log("文件 ID:", fileObject.id);

响应（FileObject）：

{
  "id": "clg681objj8g9m7n4je0",
  "object": "file",
  "bytes": 761790,
  "created_at": 1700815879,
  "filename": "report.pdf",
  "purpose": "file-extract",
  "status": "ok"
}

---

获取文件内容（提取文本）

GET https://api.moonshot.cn/v1/files/{file_id}/content
Authorization: Bearer {MOONSHOT_API_KEY}

# 获取提取的文本内容
content = client.files.content(file_id=file_object.id).text

# 整合进对话
messages = [
    {"role": "system", "content": content},
    {"role": "user", "content": "请总结这份文档的主要内容。"},
]

此接口仅适用于 purpose=file-extract 的文件，返回纯文本。图片/视频文件通过 ms://{file_id} 在消息中引用。

---

获取文件元数据

GET https://api.moonshot.cn/v1/files/{file_id}
Authorization: Bearer {MOONSHOT_API_KEY}

file_info = client.files.retrieve(file_id=file_id)
print(f"文件名: {file_info.filename}")
print(f"大小: {file_info.bytes} bytes")
print(f"状态: {file_info.status}")

---

列出所有文件

GET https://api.moonshot.cn/v1/files
Authorization: Bearer {MOONSHOT_API_KEY}

file_list = client.files.list()
for file in file_list.data:
    print(f"{file.id} - {file.filename} ({file.purpose})")

---

删除文件

DELETE https://api.moonshot.cn/v1/files/{file_id}
Authorization: Bearer {MOONSHOT_API_KEY}

result = client.files.delete(file_id=file_id)
print(f"删除成功: {result.deleted}")

---

常见问题

Q: 上传文件后多久可以使用？

A: 文件上传后需要处理（提取文本/视频抽帧等），status 从 processing 变为 ok 后才可使用。通常几秒到几分钟，大文件可能更久。

Q: 文件内容会持久保存吗？

A: 上传的文件会在 Kimi 服务端保留，直到你主动删除。定期清理不再使用的文件，避免占满 10GB 配额。

Q: 同一文件是否可以多次引用，节省重复上传？

A: 可以。上传一次获得 file_id，之后可以在多个对话中反复使用 ms://{file_id}（视觉场景）或重复调用 /content（文档场景），避免重复传输大文件。