古法编程

POST /v1/batches 是 Kimi Batch API 的入口接口，用于提交批量推理任务。需先上传 purpose=batch 的 JSONL 文件，再用返回的 file_id 创建批任务，指定处理时间窗口（12h~7d）。本文含完整参数说明和 Python/TS 代码示例。

创建批处理任务

接口信息 

POST https://api.moonshot.cn/v1/batches
Authorization: Bearer {MOONSHOT_API_KEY}
Content-Type: application/json

详细使用流程参考 Batch API 完整指南

请求参数

参数 类型 必填 说明
input_file_id string ✅ 上传 JSONL 文件后返回的文件 ID
endpoint string ✅ 目前仅支持 "/v1/chat/completions"
completion_window string ✅ 任务处理时间窗口，支持 12h、1d、3d，最小 12h，最大 7d
metadata object ❌ 自定义键值对，最多 16 个，key ≤ 64 字符，value ≤ 512 字符

请求示例 

const response = await fetch("https://api.moonshot.cn/v1/batches", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MOONSHOT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input_file_id: "file-abc123",
    endpoint: "/v1/chat/completions",
    completion_window: "24h",
    metadata: {
      job_name: "daily-analysis",
      environment: "production",
    },
  }),
});

const batch = await response.json();
console.log("批任务 ID:", batch.id);
console.log("状态:", batch.status);
import os
import requests

response = requests.post(
    "https://api.moonshot.cn/v1/batches",
    headers={
        "Authorization": f"Bearer {os.environ['MOONSHOT_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "input_file_id": "file-abc123",
        "endpoint": "/v1/chat/completions",
        "completion_window": "24h",
    },
)

batch = response.json()
print(f"批任务 ID: {batch['id']}, 状态: {batch['status']}")

响应（BatchObject）

字段 类型 说明
id string 批任务唯一 ID
object string 固定值 "batch"
status string 任务状态，见下表
input_file_id string 输入文件 ID
output_file_id string 结果文件 ID（完成后可用）
error_file_id string 失败请求的错误文件 ID
request_counts object {completed, failed, total}
created_at int 创建时间（Unix 时间戳）

任务状态：

状态 说明
validating 校验输入文件中
in_progress 正在执行
finalizing 准备结果中
completed 已完成，可下载结果
failed 校验失败
expired 超出 completion_window 时间
cancelling 取消中
cancelled 已取消

常见问题

Q: JSONL 输入文件格式是什么？

A: 每行一个 JSON 对象，包含 custom_id（自定义标识）和 body（完整的 chat completions 请求体）。详见 Batch API 指南。

Q: completion_window 填写多少合适？

A: 批处理任务使用低优先级队列，通常比在线 API 慢。建议给出至少 2 倍于预估执行时间的余量，常规任务用 24h，大批量任务用 3d。

Q: 创建后可以修改 completion_window 吗？

A: 不可以。如需调整，只能取消后重新创建任务。