Kimi Batch API 的三个管理接口：查询单任务状态、列出所有批任务（支持分页）、取消进行中的任务。所有接口返回标准 BatchObject，状态字段可追踪任务全生命周期。

Kimi Batch API 管理接口参考

获取批处理任务详情

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

const response = await fetch(
  `https://api.moonshot.cn/v1/batches/${batchId}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.MOONSHOT_API_KEY}`,
    },
  }
);

const batch = await response.json();
console.log(`状态: ${batch.status}`);
console.log(`完成: ${batch.request_counts.completed}/${batch.request_counts.total}`);

if (batch.status === "completed") {
  console.log(`结果文件 ID: ${batch.output_file_id}`);
}

---

列出批处理任务

GET https://api.moonshot.cn/v1/batches?limit=20&after={cursor}
Authorization: Bearer {MOONSHOT_API_KEY}

查询参数：

参数	类型	默认值	说明
limit	int	20	每页数量
after	string	—	分页游标，传入上一页最后一个任务的 ID

// 获取所有批任务（分页遍历）
async function listAllBatches(): Promise<any[]> {
  const batches: any[] = [];
  let after: string | undefined;

  while (true) {
    const url = new URL("https://api.moonshot.cn/v1/batches");
    url.searchParams.set("limit", "100");
    if (after) url.searchParams.set("after", after);

    const response = await fetch(url.toString(), {
      headers: { Authorization: `Bearer ${process.env.MOONSHOT_API_KEY}` },
    });
    const data = await response.json();

    batches.push(...data.data);

    if (!data.has_more) break;
    after = data.data[data.data.length - 1].id;
  }

  return batches;
}

响应格式：

{
  "object": "list",
  "data": [...],
  "has_more": false
}

---

取消批处理任务

POST https://api.moonshot.cn/v1/batches/{batch_id}/cancel
Authorization: Bearer {MOONSHOT_API_KEY}

可取消的状态：validating、in_progress、finalizing

取消后状态流转：→ cancelling → cancelled

const response = await fetch(
  `https://api.moonshot.cn/v1/batches/${batchId}/cancel`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MOONSHOT_API_KEY}`,
    },
  }
);

const batch = await response.json();
console.log(`取消后状态: ${batch.status}`); // "cancelling" 或 "cancelled"

错误码：

HTTP 状态	含义
400	任务状态不允许取消（如已 completed）
404	任务 ID 不存在

---

任务轮询最佳实践

async function waitForBatch(batchId: string): Promise<string | null> {
  const POLL_INTERVAL = 30000; // 每 30s 查询一次
  const MAX_WAIT = 24 * 60 * 60 * 1000; // 最长等待 24h
  const startTime = Date.now();

  while (Date.now() - startTime < MAX_WAIT) {
    const response = await fetch(
      `https://api.moonshot.cn/v1/batches/${batchId}`,
      { headers: { Authorization: `Bearer ${process.env.MOONSHOT_API_KEY}` } }
    );
    const batch = await response.json();

    if (batch.status === "completed") return batch.output_file_id;
    if (["failed", "expired", "cancelled"].includes(batch.status)) return null;

    await new Promise((r) => setTimeout(r, POLL_INTERVAL));
  }

  return null;
}

---

常见问题

Q: 批任务状态长时间停留在 in_progress 怎么办？

A: 批任务使用低优先级队列，队列满时等待时间可能较长。如果超过 completion_window 设定时间，任务状态会变为 expired，需要重新提交。

Q: 取消任务后已处理的请求费用还会收吗？

A: 会。取消只停止后续请求的处理，已完成的请求按正常费率计费，可在 request_counts.completed 中查看已完成数量。

Q: 分页查询时如何获取所有任务？

A: 按 has_more 字段判断是否还有更多，使用最后一条记录的 id 作为下一页的 after 参数，循环直到 has_more: false。