上传文件
上传文件用于文本内容抽取、图片理解或视频理解，支持 pdf、doc、txt 等文本类格式。
POST
/
v1
/
files
上传文件
curl --request POST \
--url https://api.moonshot.cn/v1/files \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--form 'file=@example-file;type=text/plain'import requests
url = "https://api.moonshot.cn/v1/files"
files = { "file": ("example-file", open("example-file", "rb"), "text/plain") }
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, files=files, headers=headers)
print(response.text)const form = new FormData();
form.append('file', '{
"fileName": "example-file"
}');
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
options.body = form;
fetch('https://api.moonshot.cn/v1/files', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.moonshot.cn/v1/files",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: text/plain\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: multipart/form-data"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.moonshot.cn/v1/files"
payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: text/plain\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.moonshot.cn/v1/files")
.header("Authorization", "Bearer <token>")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: text/plain\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.moonshot.cn/v1/files")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: text/plain\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--"
response = http.request(request)
puts response.read_body{
"id": "file_01h455vb4pex5vsknk084sn02q",
"filename": "report.txt",
"mime_type": "text/plain",
"size_bytes": 15,
"created_at": "2026-08-26T12:00:00Z",
"purpose": "file-extract",
"extract_status": "ready"
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}单文件大小上限为 100 MiB，超限时返回文件过大错误。文件个数不再受限，改为按组织总存储量限制，默认 10 GiB。文件解析服务限时免费，请求高峰期平台可能会有限流策略。
支持的格式
支持的格式
文件接口支持以下格式：
.pdf、.txt、.csv、.doc、.docx、.xls、.xlsx、.ppt、.pptx、.md、.dot、.epub、.html、.json、.mobi、.log、.go、.h、.c、.cpp、.cxx、.cc、.cs、.java、.js、.css、.jsp、.php、.py、.py3、.asp、.yaml、.yml、.ini、.conf、.ts、.tsx 等。注意：图片文件不再支持内容抽取（file-extract）。如需图片理解，请使用 purpose="image" 上传图片，详见使用视觉模型。文件内容抽取示例
文件内容抽取示例
上传文件时选择 其中
purpose="file-extract"，随后可以让模型获取文件中的信息作为上下文。抽取结果为 Markdown 格式文本（加粗、标题、列表等以 Markdown 语法呈现），可直接放入 messages，详见获取文件内容。- python
- curl
- node.js
showLineNumbers
from pathlib import Path
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["MOONSHOT_API_KEY"],
base_url = "https://api.moonshot.cn/v1",
)
# xlnet.pdf 是一个示例文件, 我们支持 pdf, doc 等文本类格式
file_object = client.files.create(file=Path("xlnet.pdf"), purpose="file-extract")
# 获取结果
# 注意，之前 retrieve_content api 在最新版本标记了 warning, 可以用下面这行代替
# 如果是旧版本，可以用 retrieve_content
file_content = client.files.content(file_id=file_object.id).text
# 把它放进请求中
messages = [
{
"role": "system",
"content": "你是 Kimi，由 Moonshot AI 提供的人工智能助手，你更擅长中文和英文的对话。你会为用户提供安全，有帮助，准确的回答。同时，你会拒绝一切涉及恐怖主义，种族歧视，黄色暴力等问题的回答。Moonshot AI 为专有名词，不可翻译成其他语言。",
},
{
"role": "system",
"content": file_content,
},
{"role": "user", "content": "请简单介绍 xlnet.pdf 讲了啥"},
]
# 然后调用 chat-completion, 获取 Kimi 的回答
completion = client.chat.completions.create(
model="kimi-k3",
messages=messages,
temperature=0.6,
)
print(completion.choices[0].message)
showLineNumbers
# xlnet.pdf 是一个示例文件
curl https://api.moonshot.cn/v1/files \
-H "Authorization: Bearer $MOONSHOT_API_KEY" \
-F purpose="file-extract" \
-F file="@xlnet.pdf"
showLineNumbers
const OpenAI = require("openai");
const fs = require("fs")
const client = new OpenAI({
apiKey: process.env.MOONSHOT_API_KEY,
baseURL: "https://api.moonshot.cn/v1",
});
async function main() {
// xlnet.pdf 是一个示例文件, 我们支持 pdf, doc 等文本类格式
let file_object = await client.files.create({
file: fs.createReadStream("xlnet.pdf"),
purpose: "file-extract"
})
// 注意，之前 retrieve_content api 在最新版本标记了 warning, 可以用下面这行代替
// 如果是旧版本，可以用 retrieve_content
let file_content = await (await client.files.content(file_object.id)).text()
// 把它放进请求中
let messages = [
{
"role": "system",
"content": "你是 Kimi，由 Moonshot AI 提供的人工智能助手，你更擅长中文和英文的对话。你会为用户提供安全，有帮助，准确的回答。同时，你会拒绝一切涉及恐怖主义，种族歧视，黄色暴力等问题的回答。Moonshot AI 为专有名词，不可翻译成其他语言。",
},
{
"role": "system",
"content": file_content,
},
{"role": "user", "content": "请简单介绍 xlnet.pdf 讲了啥"},
]
const completion = await client.chat.completions.create({
model: "kimi-k3",
messages: messages,
temperature: 0.6
});
console.log(completion.choices[0].message.content);
}
main();
$MOONSHOT_API_KEY 部分需要替换为您自己的 API Key。或者在调用前给它设置好环境变量。多文件对话示例
多文件对话示例
如果你想一次性上传多个文件，并根据这些文件与 Kimi 对话，你可以参考如下示例：
from typing import *
import os
import json
from pathlib import Path
from openai import OpenAI
client = OpenAI(
base_url="https://api.moonshot.cn/v1",
api_key=os.environ["MOONSHOT_API_KEY"],
)
def upload_files(files: List[str]) -> List[Dict[str, Any]]:
"""
upload_files 会将传入的文件（路径）全部通过文件上传接口 '/v1/files' 上传，并获取上传后的
文件内容生成文件 messages。每个文件会是一个独立的 message，这些 message 的 role 均为
system，Kimi 大模型会正确识别这些 system messages 中的文件内容。
:param files: 一个包含要上传文件的路径的列表，路径可以是绝对路径也可以是相对路径，请使用字符串
的形式传递文件路径。
:return: 一个包含了文件内容的 messages 列表，请将这些 messages 加入到 Context 中，
即请求 `/v1/chat/completions` 接口时的 messages 参数中。
"""
messages = []
for file in files:
file_object = client.files.create(file=Path(file), purpose="file-extract")
file_content = client.files.content(file_id=file_object.id).text
messages.append({
"role": "system",
"content": file_content,
})
return messages
def main():
file_messages = upload_files(files=["upload_files.py"])
messages = [
*file_messages,
{
"role": "system",
"content": "你是 Kimi，由 Moonshot AI 提供的人工智能助手，你更擅长中文和英文的对话。你会为用户提供安全，有帮助，"
"准确的回答。同时，你会拒绝一切涉及恐怖主义，种族歧视，黄色暴力等问题的回答。Moonshot AI 为专有名词，不"
"可翻译成其他语言。",
},
{
"role": "user",
"content": "总结一下这些文件的内容。",
},
]
print(json.dumps(messages, indent=2, ensure_ascii=False))
completion = client.chat.completions.create(
model="kimi-k3",
messages=messages,
)
print(completion.choices[0].message.content)
if __name__ == '__main__':
main()
用于图片或视频理解
用于图片或视频理解
上传文件时，选择
purpose="image" 或 purpose="video"，上传后的图片或视频可以用于模型的原生理解。请参阅使用视觉模型了解完整示例。请求头
本次请求使用的 API 版本，格式为 YYYY-MM-DD。发送 2026-09-01-beta 即使用本文档所述版本。/v1/files* 之外必传：未携带请求头将被拒绝并返回 400 invalid_request_error；在 /v1/files* 上缺省时选择兼容行为。所有端点对未知取值均返回 400 invalid_request_error。
平台当前支持的 API 版本。新的日期版本发布时加入；版本在公告的 Sunset 日期后移除。
可用选项:
2026-09-01-beta 请求体
multipart/form-data
响应
上传文件的记录。
此页面对您有帮助吗？
⌘I
上传文件
curl --request POST \
--url https://api.moonshot.cn/v1/files \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--form 'file=@example-file;type=text/plain'import requests
url = "https://api.moonshot.cn/v1/files"
files = { "file": ("example-file", open("example-file", "rb"), "text/plain") }
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, files=files, headers=headers)
print(response.text)const form = new FormData();
form.append('file', '{
"fileName": "example-file"
}');
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
options.body = form;
fetch('https://api.moonshot.cn/v1/files', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.moonshot.cn/v1/files",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: text/plain\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: multipart/form-data"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.moonshot.cn/v1/files"
payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: text/plain\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.moonshot.cn/v1/files")
.header("Authorization", "Bearer <token>")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: text/plain\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.moonshot.cn/v1/files")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: text/plain\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--"
response = http.request(request)
puts response.read_body{
"id": "file_01h455vb4pex5vsknk084sn02q",
"filename": "report.txt",
"mime_type": "text/plain",
"size_bytes": 15,
"created_at": "2026-08-26T12:00:00Z",
"purpose": "file-extract",
"extract_status": "ready"
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}