百因智算

百因智算开发者文档

基于 MDX 内容结构组织的完整文档：快速开始、API 参考、教程与 Cookbook。

运行时合约

运行姿态

面向稳定生产级文本与多模态流量。

能力范围

文本与多模态统一走同一 Model API 合约。

接入协议

OpenAI-compatible、MCP、llms.txt 与 agents.md 同时开放。

流控语义

支持 TTFT 监控、背压、慢消费隔离与区域级限流。

公开地址与协议

OpenAPI

https://api.luminapath.tech/openapi.json

API base

https://api.luminapath.tech/v1

MCP

https://api.luminapath.tech/v1/mcp

公开路径

/v1/chat/completions · /v1/responses · /v1/embeddings · /v1/images · /v1/audio/* · /v1/videos

并发与结算语义

全球与国内入口分别服务对应客户，同时保持稳定的 API 接入体验。
按 key、workspace、lane、region 做范围化限流与超时控制，并对客户端可见失败语义做明确分类。
普通企业流量进入共享核心；更大客户、专属容量和 8 卡以上交付进入独立 lane。
中文站只展示支付宝自助充值；回执验证单独保留。

全球网络接入，统一控制平面

统一的高性能智能 API 网关，为全球不同市场提供一致的稳定推理交付。

BatchIn 协同智能调度、安全控制与算力资源，为海内外客户提供本地化支付接入与高可靠的工业级推理算力底座。

查看当前公开合约

全球入口

BatchIn 通过英文站和全球 API 面向海外开发者、AI 团队与企业客户。

这个入口承接美元定价、公开 MCP 发现、OpenAI 兼容调用，以及面向海外客户的销售与交付。

https://batchin.tech · https://api.batchin.tech/v1

中国入口

LuminaPath 通过中文站和国内 API 合约面向中国开发者、企业客户与本地合作伙伴。

这个入口承接人民币导向的开通、国内支持方式和本地化交付，并保持统一的 BatchIn 使用体验。

https://luminapath.tech · https://api.luminapath.tech/v1

运行姿态

面向稳定生产级流量。

流量类型

覆盖文本、视觉、音频、图像和视频混合流量。

流式主路径

区域入口、稳定流式输出与请求连续性。

控制护栏

范围化限流、请求隔离与背压控制。

公开合约与就绪度

OpenAI 兼容端点统一覆盖 chat、responses、embeddings、images、audio 和 video。
公开 MCP transport 与工具发现都走 BatchIn 合约，不暴露执行细节。
流量策略面向稳定生产级文本与多模态负载，而不是只服务演示级流量。
能力可用状态以 usage、cost、billing、trace 和验证记录的一致状态为准。

共享核心

自助开发者与普通企业流量先进入共享 BatchIn 控制核心。

这里统一承接公开 Model API、Batch、Usage、Billing 和公开 MCP 合约。

独立 lane

预留推理、专属端点和更大规模企业流量会进入更强隔离的容量 lane。

客户界面保持一个产品真相，交付、配额和隔离方式按合同切换。

算力真相

8 卡以上专属交付与更小规模小时租都基于同一套算力和容量真相。

公开页面只展示来自已验证算力注册表的库存与可用性。

边缘接入

全球流量先进入区域边缘入口，以保证接入稳定和会话连续性。

延迟优化从客户侧入口开始，再进入主执行链路。

流式交付

BatchIn 在跨区域和多模态负载下保持稳定的流式返回表现。

连接复用与消费隔离用于降低抖动和长尾失败。

流量策略

流量策略通过范围化保护、重试纪律和优雅过载处理保持明确。

客户看到简洁 API 与清晰限制，BatchIn 在幕后处理流量保护。

快速开始（3 种语言）

1) 安装

pip install openai

2) 首个请求

from openai import OpenAI

client = OpenAI(
  base_url="https://api.luminapath.tech/v1",
  api_key="YOUR_API_KEY"
)

resp = client.chat.completions.create(
  model="qwen3-32b",
  messages=[{"role": "user", "content": "Hello from 百因智算"}]
)
print(resp.choices[0].message.content)

3) 流式输出

stream = client.chat.completions.create(
  model="qwen3-32b",
  messages=[{"role": "user", "content": "Write a haiku about latency"}],
  stream=True
)

for chunk in stream:
  delta = chunk.choices[0].delta.content
  if delta:
    print(delta, end="")

平台操作手册

专属端点与 GPU 租用

查看专属端点、GPU 卡时使用、计费和结算的自助路径。

打开

Dedicated Capacity 路径

在启动容量项目之前，先明确专属端点、私有部署边界、密钥形态和计费隔离方式。

打开

路由控制与备用路径

在迁移生产流量前，先看清百因智算如何定义路由控制、批处理通道与备用路径行为。

打开

VaaS 浏览器验签路径

打开公开验证流程，检查签名证据包，并在浏览器里独立完成信任校验。

打开

OTLP 观测路径

查看预留的 OTLP 接入与导出能力，以及未来如何把请求追踪接入外部观测工具。

打开

API 参考

GET/v1/users/meBearer

当前用户信息

获取当前 API Key 对应用户信息。

请求示例

{}

响应示例

{
  "id": "f6e2c67b-90cf-4f4e-b1e5-31d45f3b1b0a",
  "email": "hello@luminapath.ai",
  "name": "BatchIn Team",
  "credit_balance_cents": 10000
}

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.luminapath.tech/v1/users/me",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
无参数

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
POST/v1/keysBearer

创建 API Key

创建新 API Key，可设置速率与月预算。

请求示例

{
  "name": "Production Key",
  "rate_limit_rpm": 120,
  "monthly_budget_cents": 500000
}

响应示例

{
  "id": "f40cf8b0-c367-4764-92e3-cbd358fa3d76",
  "key": "batchin_api_xxx",
  "key_prefix": "batchin_api",
  "name": "Production Key",
  "rate_limit_rpm": 120,
  "monthly_budget_cents": 500000,
  "created_at": "2026-04-08T18:00:00Z"
}

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.luminapath.tech/v1/keys",
    headers=headers,
    json={
  "name": "Production Key",
  "rate_limit_rpm": 120,
  "monthly_budget_cents": 500000
}
)

print(response.json())

参数表

NameType必填说明
namestring否密钥名称
rate_limit_rpmnumber否每分钟请求上限
monthly_budget_centsnumber否月预算（美分）

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
GET/v1/keysBearer

列出 API Keys

返回当前用户全部 API Keys。

请求示例

{}

响应示例

[
  {
    "id": "f40cf8b0-c367-4764-92e3-cbd358fa3d76",
    "key_prefix": "batchin_api",
    "name": "Production Key",
    "rate_limit_rpm": 120,
    "is_active": true,
    "created_at": "2026-04-08T18:00:00Z"
  }
]

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.luminapath.tech/v1/keys",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
无参数

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
DELETE/v1/keys/{id}Bearer

删除 API Key

删除指定 API Key。

请求示例

{}

响应示例

204 No Content

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "DELETE",
    "https://api.luminapath.tech/v1/keys/{id}",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
idpath:uuid是API Key ID

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
not_found404API Key 不存在确认 key id 后重试。
前往在线调试
POST/v1/chat/completionsBearer

聊天补全

用于文本/多轮对话，支持 SSE 流式输出。

请求示例

{
  "model": "qwen3.5-27b",
  "messages": [{"role":"user","content":"Explain attention in 3 bullets"}],
  "temperature": 0.7,
  "stream": false
}

响应示例

{
  "id": "chatcmpl_xxx",
  "object": "chat.completion",
  "model": "qwen3.5-27b",
  "choices": [{"index":0,"message":{"role":"assistant","content":"..."}}],
  "usage": {"prompt_tokens": 22, "completion_tokens": 90, "total_tokens": 112}
}

响应头

Header说明
traceparentW3C trace 上下文，可用于把请求串到外部追踪系统。
X-Request-Id请求级关联 ID，可用于支持与审计排障。
X-BatchIn-Run-Id本次运行的 BatchIn run id。
X-BatchIn-Prompt-Version绑定到本次运行的 prompt version。
X-VaaS-Record-Id审计证据记录 id。
X-VaaS-Signature审计证据签名。
X-VaaS-PublicKey审计验签公钥。

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.luminapath.tech/v1/chat/completions",
    headers=headers,
    json={
  "model": "qwen3.5-27b",
  "messages": [{"role":"user","content":"Explain attention in 3 bullets"}],
  "temperature": 0.7,
  "stream": false
}
)

print(response.json())

参数表

NameType必填说明
modelstring是模型 ID
messagesarray是对话消息数组
temperaturenumber否采样温度
max_tokensnumber否最大输出 tokens
streamboolean否是否流式返回

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
payment_required402余额不足或预算超限充值或提高月预算后重试。
前往在线调试
POST/v1/responsesBearer

Responses 接口

最小兼容版 Responses API，返回 response 对象与运行时回执头。

请求示例

{
  "model": "qwen3.5-27b",
  "input": "Explain batch inference in 3 bullets",
  "max_output_tokens": 256
}

响应示例

{
  "id": "resp_chatcmpl_xxx",
  "object": "response",
  "model": "qwen3.5-27b",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{"type":"output_text","text":"..."}]
    }
  ],
  "usage": {"input_tokens": 12, "output_tokens": 10, "total_tokens": 22}
}

响应头

Header说明
traceparentW3C trace 上下文，可用于把请求串到外部追踪系统。
X-Request-Id请求级关联 ID，可用于支持与审计排障。
X-BatchIn-Run-Id本次运行的 BatchIn run id。
X-BatchIn-Prompt-Version绑定到本次运行的 prompt version。
X-VaaS-Record-Id审计证据记录 id。
X-VaaS-Signature审计证据签名。
X-VaaS-PublicKey审计验签公钥。

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.luminapath.tech/v1/responses",
    headers=headers,
    json={
  "model": "qwen3.5-27b",
  "input": "Explain batch inference in 3 bullets",
  "max_output_tokens": 256
}
)

print(response.json())

参数表

NameType必填说明
modelstring是模型 ID
inputstring|array是输入文本或消息数组
max_output_tokensnumber否最大输出 tokens
streamboolean否是否流式返回（当前未实现）

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
not_implemented501流式 Responses 还未实现先使用非流式 /v1/responses 或 /v1/chat/completions。
前往在线调试
POST/v1/completionsBearer

文本补全 / FIM

兼容 OpenAI completions，并支持 prefix/suffix 形式的 FIM 请求。

请求示例

{
  "model": "qwen3.5-27b",
  "prompt": "Complete this sentence: Batch processing helps",
  "suffix": "for large workloads.",
  "max_tokens": 128
}

响应示例

{
  "id": "cmpl_xxx",
  "object": "text_completion",
  "choices": [{"index":0,"text":"reduce manual toil at scale.","finish_reason":"stop"}],
  "usage": {"prompt_tokens": 24, "completion_tokens": 12, "total_tokens": 36}
}

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.luminapath.tech/v1/completions",
    headers=headers,
    json={
  "model": "qwen3.5-27b",
  "prompt": "Complete this sentence: Batch processing helps",
  "suffix": "for large workloads.",
  "max_tokens": 128
}
)

print(response.json())

参数表

NameType必填说明
modelstring是补全模型 ID
promptstring|array是输入前缀或文本
suffixstring否FIM 后缀
max_tokensnumber否最大输出 tokens

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
POST/v1/embeddingsBearer

向量嵌入

将文本转换为向量表示。

请求示例

{
  "model": "bge-m3",
  "input": ["batch inference", "retrieval augmented generation"]
}

响应示例

{
  "object": "list",
  "data": [
    {"index":0,"embedding":[0.012,-0.043,...]},
    {"index":1,"embedding":[0.021,-0.011,...]}
  ]
}

响应头

Header说明
traceparentW3C trace 上下文。
X-BatchIn-Run-Id本次 embedding 运行的 run id。
X-BatchIn-Prompt-Version绑定到本次运行的 prompt version。
X-VaaS-Record-Id审计证据记录 id。

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.luminapath.tech/v1/embeddings",
    headers=headers,
    json={
  "model": "bge-m3",
  "input": ["batch inference", "retrieval augmented generation"]
}
)

print(response.json())

参数表

NameType必填说明
modelstring是嵌入模型 ID
inputstring|array是待向量化文本

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
POST/v1/audio/speechBearer

语音合成

使用 CosyVoice / TTS 模型把文本转换为音频响应。

请求示例

{
  "model": "cosyvoice",
  "input": "Welcome to BatchIn",
  "voice": "alloy",
  "response_format": "mp3"
}

响应示例

Binary audio payload (audio/mpeg)

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.luminapath.tech/v1/audio/speech",
    headers=headers,
    json={
  "model": "cosyvoice",
  "input": "Welcome to BatchIn",
  "voice": "alloy",
  "response_format": "mp3"
}
)

print(response.content)

参数表

NameType必填说明
modelstring是语音模型 ID
inputstring是待合成文本
voicestring否音色
response_formatstring否返回格式

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
POST/v1/audio/transcriptionsBearer

音频转录

将语音或音频文件转成文本，可返回简洁结果或带时间片段的详细结构。

请求示例

multipart/form-data
  file=@meeting.wav
  model=whisper-large-v3-turbo
  response_format=verbose_json
  language=en

响应示例

{
  "text": "BatchIn transcription output",
  "language": "en",
  "duration": 3.42,
  "segments": [{"id":0,"start":0.0,"end":3.42,"text":"BatchIn transcription output"}]
}

代码示例

import os
import requests

with open("meeting.wav", "rb") as audio_file:
    response = requests.request(
        "POST",
        "https://api.luminapath.tech/v1/audio/transcriptions",
        headers={"Authorization": f"Bearer {os.environ['BATCHIN_API_KEY']}"},
        files={"file": audio_file},
        data={
            "model": "whisper-large-v3-turbo",
            "response_format": "verbose_json",
            "language": "en",
        },
    )

print(response.json())

参数表

NameType必填说明
filebinary是音频文件
modelstring是转录模型 ID
languagestring否语言代码
promptstring否转录提示
response_formatstring否返回格式
temperaturenumber|string否采样温度

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
POST/v1/videosBearer

视频任务

通过统一的 Model API 视频入口提交视频生成任务。

请求示例

{
  "model": "wan-2.2",
  "prompt": "Create a product teaser for an AI cloud launch",
  "duration_seconds": 6
}

响应示例

{
  "id": "video_xxx",
  "object": "video.generation",
  "status": "queued",
  "duration_seconds": 6,
  "output_url": "https://api.luminapath.tech/v1/files/file_video_xxx/content"
}

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.luminapath.tech/v1/videos",
    headers=headers,
    json={
  "model": "wan-2.2",
  "prompt": "Create a product teaser for an AI cloud launch",
  "duration_seconds": 6
}
)

print(response.json())

参数表

NameType必填说明
modelstring是视频模型 ID
promptstring是视频提示词
duration_secondsnumber否视频秒数
aspect_ratiostring否画幅比例

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
POST/v1/imagesBearer

图像生成

通过统一的 Model API 图像入口进行文本生成图像。

请求示例

{
  "model": "flux-schnell",
  "prompt": "A futuristic city at sunrise",
  "size": "1024x1024"
}

响应示例

{
  "created": 1775671200,
  "data": [{"url":"https://batchin.tech/images/generated/abc.png"}]
}

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.luminapath.tech/v1/images",
    headers=headers,
    json={
  "model": "flux-schnell",
  "prompt": "A futuristic city at sunrise",
  "size": "1024x1024"
}
)

print(response.json())

参数表

NameType必填说明
modelstring是图像模型 ID
promptstring是图像提示词
sizestring否输出尺寸

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
GET/v1/models公开

模型列表

返回模型状态、价格、上下文与许可证信息。

请求示例

{}

响应示例

{
  "object": "list",
  "data": [
    {
      "id":"qwen3.5-27b",
      "status":"always_on",
      "context_length":131072,
      "pricing":{"std_input":0.02,"std_output":0.08}
    }
  ]
}

代码示例

import os
import requests

headers = {}
response = requests.request(
    "GET",
    "https://api.luminapath.tech/v1/models",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
无参数

错误码

CodeHTTP信息处理建议
service_unavailable503模型服务不可用查看状态页并稍后重试。
前往在线调试
POST/v1/batchesBearer

创建批处理

提交批处理任务（支持混合模型与优先级）。

请求示例

{
  "priority": "fill",
  "webhook_url": "https://your-domain.com/webhooks/batchin",
  "tasks": [
    {"custom_id":"task-1","model":"qwen3.5-27b","request_body":{"messages":[{"role":"user","content":"translate this"}]}},
    {"custom_id":"task-2","model":"glm-5.1","request_body":{"messages":[{"role":"user","content":"summarize this"}]}}
  ]
}

响应示例

{
  "id":"0b0db2a6-0baf-4ec4-a5e7-bce60da57db6",
  "status":"pending",
  "priority":"fill",
  "total_tasks":2,
  "completed_tasks":0,
  "failed_tasks":0
}

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.luminapath.tech/v1/batches",
    headers=headers,
    json={
  "priority": "fill",
  "webhook_url": "https://your-domain.com/webhooks/batchin",
  "tasks": [
    {"custom_id":"task-1","model":"qwen3.5-27b","request_body":{"messages":[{"role":"user","content":"translate this"}]}},
    {"custom_id":"task-2","model":"glm-5.1","request_body":{"messages":[{"role":"user","content":"summarize this"}]}}
  ]
}
)

print(response.json())

参数表

NameType必填说明
tasksarray是任务数组（每项可指定 model）
prioritystring(high|low|fill)否调度优先级
webhook_urlstring(url)否回调地址

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
payload_too_large413批任务 JSON 超过 2MB拆分批次或减少单批任务数。
前往在线调试
GET/v1/batchesBearer

列出批处理

列出当前用户批处理任务。

请求示例

{}

响应示例

[
  {
    "id":"0b0db2a6-0baf-4ec4-a5e7-bce60da57db6",
    "status":"completed",
    "priority":"fill",
    "total_tasks":2,
    "completed_tasks":2,
    "failed_tasks":0
  }
]

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.luminapath.tech/v1/batches",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
无参数

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
GET/v1/batches/{id}Bearer

获取批处理详情

获取批处理任务与子任务详情。

请求示例

{}

响应示例

{
  "id":"0b0db2a6-0baf-4ec4-a5e7-bce60da57db6",
  "status":"completed",
  "tasks":[{"custom_id":"task-1","status":"completed"}]
}

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.luminapath.tech/v1/batches/{id}",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
idpath:uuid是批处理 ID

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
not_found404批处理不存在确认 batch id 是否正确。
前往在线调试
POST/v1/batches/{id}/cancelBearer

取消批处理

取消进行中的批处理任务。

请求示例

{}

响应示例

{
  "id":"0b0db2a6-0baf-4ec4-a5e7-bce60da57db6",
  "status":"cancelled"
}

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "POST",
    "https://api.luminapath.tech/v1/batches/{id}/cancel",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
idpath:uuid是批处理 ID

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
POST/v1/topup/stripe/checkoutBearer

创建 Stripe Checkout

创建充值支付会话。

请求示例

{
  "amount_cents": 5000
}

响应示例

{
  "checkout_url":"https://buy.stripe.com/9B65kD4US2fLeEF4zweME00",
  "session_id":"cs_test_xxx"
}

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.luminapath.tech/v1/topup/stripe/checkout",
    headers=headers,
    json={
  "amount_cents": 5000
}
)

print(response.json())

参数表

NameType必填说明
amount_centsnumber是充值金额（美分）

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
GET/v1/topup/historyBearer

充值历史

查询充值记录。

请求示例

{}

响应示例

[
  {
    "id":"1544d6df-8fca-46f3-9091-95f81dc37efa",
    "amount_cents":5000,
    "source":"stripe",
    "reference_id":"cs_test_xxx"
  }
]

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.luminapath.tech/v1/topup/history",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
无参数

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
GET/v1/topup/usdc/chainsBearer

USDC 链路信息

获取 USDC 充值链与地址。

请求示例

{}

响应示例

{
  "chains":[
    {"chain":"ethereum","deposit_address":"0x...","required_confirmations":12},
    {"chain":"polygon","deposit_address":"0x...","required_confirmations":12}
  ]
}

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.luminapath.tech/v1/topup/usdc/chains",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
无参数

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
GET/v1/usage/logs?limit=50&offset=0Bearer

使用日志

查询请求级别使用日志。

请求示例

{}

响应示例

[
  {
    "id":"e73f9476-00ea-491f-ba6f-899602247a15",
    "model":"qwen3.5-27b",
    "input_tokens":120,
    "output_tokens":88,
    "cost_cents":2
  }
]

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.luminapath.tech/v1/usage/logs?limit=50&offset=0",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
limitquery:number否返回条数（1-500）
offsetquery:number否偏移量

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
GET/v1/usage/summaryBearer

用量汇总

获取总请求、tokens 与成本统计。

请求示例

{}

响应示例

{
  "total_requests": 1304,
  "total_input_tokens": 2341122,
  "total_output_tokens": 1111400,
  "total_cost_cents": 18640
}

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.luminapath.tech/v1/usage/summary",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
无参数

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
payment_required402API Key 月预算已超限提高月预算或更换 key。
前往在线调试
GET/v1/usage/by-modelBearer

按模型聚合

按模型维度统计用量。

请求示例

{}

响应示例

[
  {
    "model":"qwen3.5-27b",
    "total_requests": 880,
    "total_input_tokens": 1620012,
    "total_output_tokens": 801202,
    "total_cost_cents": 9900
  }
]

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.luminapath.tech/v1/usage/by-model",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
无参数

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
POST/v1/vaasBearer

创建审计记录

创建可验证审计记录并返回签名。

请求示例

{
  "input_text": "What is a zero-knowledge proof?",
  "output_text": "A cryptographic method...",
  "model_id": "qwen3.5-27b",
  "gpu_id": "execution-a19c-42ef"
}

响应示例

{
  "audit_id":"ee3cc19e-710d-4a2d-bf01-0edca0c5fdf4",
  "input_hash":"9a5f...",
  "output_hash":"2f1b...",
  "carbon_grams_co2e":0.0126,
  "energy_wh":0.2107,
  "energy_source":"Renewable grid mix",
  "carbon_offset_vs_us_cloud":0.0717,
  "signature":"bfc4..."
}

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.luminapath.tech/v1/vaas",
    headers=headers,
    json={
  "input_text": "What is a zero-knowledge proof?",
  "output_text": "A cryptographic method...",
  "model_id": "qwen3.5-27b",
  "gpu_id": "execution-a19c-42ef"
}
)

print(response.json())

参数表

NameType必填说明
input_textstring是输入文本
output_textstring是输出文本
model_idstring是模型 ID
gpu_idstring否执行环境标识（脱敏）

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
GET/v1/vaas/{id}公开

查询审计记录

按 audit_id 获取审计详情。

请求示例

{}

响应示例

{
  "audit_id":"ee3cc19e-710d-4a2d-bf01-0edca0c5fdf4",
  "input_hash":"9a5f...",
  "output_hash":"2f1b...",
  "carbon_grams_co2e":0.0126,
  "energy_wh":0.2107,
  "energy_source":"Renewable grid mix",
  "carbon_offset_vs_us_cloud":0.0717,
  "signature":"bfc4..."
}

代码示例

import os
import requests

headers = {}
response = requests.request(
    "GET",
    "https://api.luminapath.tech/v1/vaas/{id}",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
idpath:uuid是审计 ID

错误码

CodeHTTP信息处理建议
not_found404审计记录不存在检查 audit_id。
前往在线调试
GET/v1/vaas/{id}/verify公开

验证审计签名

验证审计记录签名是否合法。

请求示例

{}

响应示例

{
  "audit_id":"ee3cc19e-710d-4a2d-bf01-0edca0c5fdf4",
  "valid": true
}

代码示例

import os
import requests

headers = {}
response = requests.request(
    "GET",
    "https://api.luminapath.tech/v1/vaas/{id}/verify",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
idpath:uuid是审计 ID

错误码

CodeHTTP信息处理建议
前往在线调试
GET/v1/vaas/{id}/evidence公开

导出证据包

返回浏览器验签和合规导出使用的 audit evidence pack。

请求示例

{}

响应示例

{
  "record_id":"vaas_xxx",
  "run_id":"run_xxx",
  "trace_id":"0123456789abcdef0123456789abcdef",
  "route_id":"default-route",
  "provider":"batchin-managed",
  "environment":"development",
  "prompt_version_id":"default",
  "verification_method":"Ed25519Signature2020",
  "public_key":"ed25519:pk_xxx",
  "signature":"ed25519:xxx",
  "payload": {"record_id":"vaas_xxx","input_hash":"sha256:...","output_hash":"sha256:..."}
}

响应头

Header说明
Content-TypeJSON evidence pack，可直接保存或交给 /verify。

代码示例

import os
import requests

headers = {}
response = requests.request(
    "GET",
    "https://api.luminapath.tech/v1/vaas/{id}/evidence",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
idpath:uuid是审计 ID

错误码

CodeHTTP信息处理建议
前往在线调试
GET/v1/vaas/pubkey/current公开

获取当前公钥

获取浏览器验签所需公钥。

请求示例

{}

响应示例

{
  "verify_key_hex":"1fbd9285..."
}

代码示例

import os
import requests

headers = {}
response = requests.request(
    "GET",
    "https://api.luminapath.tech/v1/vaas/pubkey/current",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
无参数

错误码

CodeHTTP信息处理建议
前往在线调试
GET/v1/traces?limit=20Bearer

列出运行追踪

返回原生 runtime trace 列表，关联 route、prompt version 与 审计记录。

请求示例

{}

响应示例

{
  "items": [
    {
      "trace_id":"0123456789abcdef0123456789abcdef",
      "run_id":"run_xxx",
      "record_id":"vaas_xxx",
      "route_id":"default-route",
      "provider":"batchin-managed",
      "environment":"development",
      "prompt_version_id":"default",
      "model_id":"qwen3.5-27b"
    }
  ]
}

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.luminapath.tech/v1/traces?limit=20",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
limitquery:number否返回条数（1-100）

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
GET/v1/traces/{trace_id}Bearer

获取单条追踪

按 trace_id 获取单条 runtime trace。

请求示例

{}

响应示例

{
  "trace_id":"0123456789abcdef0123456789abcdef",
  "run_id":"run_xxx",
  "record_id":"vaas_xxx",
  "route_id":"default-route",
  "provider":"batchin-managed",
  "environment":"development",
  "prompt_version_id":"default",
  "model_id":"qwen3.5-27b"
}

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.luminapath.tech/v1/traces/{trace_id}",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
trace_idpath:string是Trace ID

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
not_found404Trace 不存在确认 trace_id 后重试。
前往在线调试
GET/v1/promptsBearer

提示词注册表

返回 prompt 注册表、已提升版本、最新观测版本与版本明细。

请求示例

{}

响应示例

{
  "status":"ready",
  "docs":"/docs/prompts",
  "items":[
    {
      "registry_id":"support",
      "display_name":"support",
      "source":"auto_backfill",
      "latest_version_id":"support@v2",
      "promoted_version_id":"support@v2",
      "total_runs":4,
      "versions":[
        {
          "version_id":"support@v1",
          "status":"observed",
          "total_runs":2
        },
        {
          "version_id":"support@v2",
          "status":"promoted",
          "total_runs":2
        }
      ]
    }
  ]
}

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.luminapath.tech/v1/prompts",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
无参数

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
GET/v1/prompt-regressionsBearer

Prompt Regression 结果

返回自动 sampled replay 的 regression 结果、样本数、相似度与延迟汇总。

请求示例

{}

响应示例

{
  "status":"ready",
  "docs":"/docs/experiments",
  "items":[
    {
      "regression_id":"preg_demo",
      "registry_id":"support",
      "baseline_prompt_version_id":"support@v1",
      "candidate_prompt_version_id":"support@v2",
      "status":"passed",
      "judge":"deterministic_replay",
      "sample_count":3,
      "pass_count":3,
      "fail_count":0,
      "avg_similarity":1,
      "baseline_avg_latency_ms":420,
      "candidate_avg_latency_ms":390
    }
  ]
}

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.luminapath.tech/v1/prompt-regressions",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
无参数

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
GET/v1/experimentsBearer

实验工作区

返回候选 prompt version 的自动实验、回放状态与自动提升结果。

请求示例

{}

响应示例

{
  "status":"ready",
  "docs":"/docs/experiments",
  "items":[
    {
      "experiment_id":"pexp_demo",
      "registry_id":"support",
      "baseline_prompt_version_id":"support@v1",
      "candidate_prompt_version_id":"support@v2",
      "status":"passed",
      "promotion_status":"promoted",
      "sample_count":3,
      "pass_rate":1
    }
  ]
}

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.luminapath.tech/v1/experiments",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
无参数

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
POST/v1/otlp/tracesBearer

OTLP Trace Ingest

接收 OTLP/HTTP JSON 或 protobuf trace，并把 span 合并进统一 trace 视图。

请求示例

{
  "resourceSpans": []
}

响应示例

{}

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
headers["Content-Type"] = "application/json"
response = requests.request(
    "POST",
    "https://api.luminapath.tech/v1/otlp/traces",
    headers=headers,
    json={
  "resourceSpans": []
}
)

print(response.json())

参数表

NameType必填说明
无参数

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
GET/v1/otlp/exportBearer

OTLP Trace Export

把统一 trace 视图中的 span 导出为 OTLP protobuf 或 JSON。

请求示例

{}

响应示例

{
  "resourceSpans":[]
}

代码示例

import os
import requests

headers = {}
headers["Authorization"] = f"Bearer {os.environ['BATCHIN_API_KEY']}"
response = requests.request(
    "GET",
    "https://api.luminapath.tech/v1/otlp/export",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
无参数

错误码

CodeHTTP信息处理建议
unauthorized401API Key 无效或缺失检查 Authorization: Bearer <API_KEY>。
前往在线调试
GET/health公开

系统健康检查

服务健康状态探活端点。

请求示例

{}

响应示例

{
  "status":"ok"
}

代码示例

import os
import requests

headers = {}
response = requests.request(
    "GET",
    "https://api.luminapath.tech/health",
    headers=headers,
    
)

print(response.json())

参数表

NameType必填说明
无参数

错误码

CodeHTTP信息处理建议
前往在线调试

教程

批处理教程

  1. 上传 JSONL 输入文件（每行一个任务）。
  2. 创建批处理任务并记录 batch_id。
  3. 轮询状态，完成后下载输出文件。

Responses 教程

  1. 当你需要更轻量的 response 对象时，向 /v1/responses 发送单次输入。
  2. 读取 traceparent 与 X-BatchIn-* 运行回执头，拿到路由、模板版本和运行上下文。
  3. 再从 /console/traces 跳到对应追踪记录，并在 /verify 中打开关联的审计证据。

VaaS 教程

  1. 发送文本到 /v1/vaas。
  2. 根据 risk_score 设置阈值策略。
  3. 将决策链路接入审核日志。

Cookbook

百万文档批处理流水线

将 1,000,000 条文档拆分为 JSONL 任务，按优先级分批处理并自动回调入库。

生产级 RAG 管线

组合 Embeddings + 检索 + 重排序 + 生成，构建可观测、可回滚的问答系统。

VaaS 一体化接入

在输入、输出、人工复核三个节点写入审计证据，并完成 Ed25519 验签。

Changelog

Release truth lives in the live model catalog, pricing surfaces, and verified route behavior. Use the public site and console evidence paths as the current changelog source of truth.