Claude Message Batches

对于其他有效的活动凭证，现有的批量读取/控制操作在零余额时仍然可用，但是 POST /v1/messages/batches 在存储任何作业/项目行之前需要新的正余额/支出准入。因此，零余额密钥无法创建新的 Claude 批次或消耗 MariaDB 保留存储。当工作人员认领实际物品时，它们会重新检查入场情况，如果资金随后耗尽，它们会在持久队列中等待。输入是逐项增量解码的，而不是作为完整的 256 MB 内存中 JSON 文档加载，并且每个用户的活动作业/排队项目配额限制了独立于计费的存储滥用。

Model Gate 在上实现了与 Anthropic 兼容的 Message Batches API https://api.model-gate.com。它是一个兼容层：Model Gate 持久存储批次并通过普通 Model Gate 执行每个项目 /v1/messages 小路。确实如此 不是 向上游提交提供者本地 Anthropic 批次。

使用普通模型 API 密钥（mg_live_...）。每个项目都被视为单独的请求 request_mode=batch, batch_protocol=claude、批次 ID 及其 custom_id。

批处理内不支持流式处理。模型别名在项目排队之前解析。

创建消息批次

要求

curl https://api.model-gate.com/v1/messages/batches \
  -H "x-api-key: mg_live_..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "requests": [
      {
        "custom_id": "summary-1",
        "params": {
          "model": "ch-47",
          "max_tokens": 256,
          "messages": [{"role":"user","content":"Summarize this text."}]
        }
      }
    ]
  }'

回应 — 200

{
  "id": "msgbatch_01K...",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 1,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2026-08-13T08:30:00Z",
  "expires_at": "2026-08-14T08:30:00Z",
  "cancel_initiated_at": null,
  "results_url": null
}

检索批次

要求

curl https://api.model-gate.com/v1/messages/batches/msgbatch_01K... \
  -H "x-api-key: mg_live_..."

回应——结束

{
  "id": "msgbatch_01K...",
  "type": "message_batch",
  "processing_status": "ended",
  "request_counts": {
    "processing": 0,
    "succeeded": 1,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": "2026-08-13T08:30:04Z",
  "results_url": "https://api.model-gate.com/v1/messages/batches/msgbatch_01K.../results"
}

读取结果

结果以 JSON 行形式返回。不要假设应用程序逻辑依赖于原始输入顺序；匹配结果由 custom_id。

要求

curl https://api.model-gate.com/v1/messages/batches/msgbatch_01K.../results \
  -H "x-api-key: mg_live_..."

回应 — 200

{"custom_id":"summary-1","result":{"type":"succeeded","message":{"id":"msg_...","type":"message","role":"assistant","content":[{"type":"text","text":"..."}]}}}

列出批次

limit 默认为 20 并且必须来自 1 到 100。使用 after_id 或者 before_id 用于光标分页；不要在一个请求中同时发送两者。

要求

curl "https://api.model-gate.com/v1/messages/batches?limit=20&after_id=msgbatch_01K..." \
  -H "x-api-key: mg_live_..."

回应 — 200

{
  "data": [],
  "has_more": false,
  "first_id": null,
  "last_id": null
}

取消批次

取消会阻止排队的项目被认领。已经处理的项目可能会完成。

要求

curl -X POST https://api.model-gate.com/v1/messages/batches/msgbatch_01K.../cancel \
  -H "x-api-key: mg_live_..."

回应 — 200

{
  "id": "msgbatch_01K...",
  "type": "message_batch",
  "processing_status": "canceling",
  "request_counts": {
    "processing": 1,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  }
}

删除已结束的批次

仅当批次达到最终状态后才接受删除。

要求

curl -X DELETE https://api.model-gate.com/v1/messages/batches/msgbatch_01K... \
  -H "x-api-key: mg_live_..."

回应 — 200

{
  "id": "msgbatch_01K...",
  "type": "message_batch_deleted"
}

恢复语义

批处理项目使用与本机异步请求相同的持久队列。恢复是 至少一次，不完全一次：在工作进程崩溃后，可以回收废弃的租约，并且如果第一个上游响应没有持久存储，则可以再次向上游发送项目。 Model Gate 请求 ID 在重试期间保持稳定，并且结算守卫可防止已完成的请求发生第二个帐户借记。

每件物品在工人领取之前立即被接纳。否则，当当前账户余额为负数或密钥/组可重置支出限额已用尽时，有效项目仍处于排队状态；等待资金不会消耗尝试或将项目标记为失败。稍后充值、使用重置或限制增加会自动恢复符合条件的排队项目。 Model Gate 不保留最坏情况下的批量成本，因此同时承认的项目可能会以负的最终余额或小额支出限额超支结束；仅保留后续新项目。

定价和会计

每个批次项目使用与正常模型门请求相同的模型路由、代币记账、定价快照、使用评估、API 密钥/组限制和结算逻辑。管理员可以配置 批量请求价格系数 在帐户定价模板上。默认为 1。

例如，使用正常的模型门成本 0.02 和批次系数 0.5，实际账户借方为 0.01。保存的官方提供商参考金额不会乘以该模型门批量系数。原生请求使用 "async": true 也不受影响。

如果系数不同于 1，它显示在型号价格页面和中 /v1/models 作为 batch_pricing 再加上有效的 batch_cost 费率。

错误

无效或重复 custom_id, 未知型号, stream:true, 嵌套 async:true、过大的请求或无效的正文会返回正常的人类风格的错误响应。

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "summary-1: stream=true is not supported inside a batch"
  }
}