黑马天启 · 多模型 Token 平台

对话补全 POST /v1/chat/completions

绝大多数业务都走这个端点：一问一答、流式输出、工具调用。

请求

字段 必填 说明
model 是 平台公开模型名（控制台「模型与价格」里复制）
messages 是 对话数组；支持 system / user / assistant / tool
stream 否 true 时以 SSE 逐块返回
max_tokens 否 输出上限，直接影响费用，建议显式设置
temperature / top_p 否 采样参数，按上游支持情况透传
tools / tool_choice 否 工具调用，需模型与上游支持
response_format 否 结构化输出，需模型与上游支持
stream_options 否 include_usage=true 可在流末尾拿到用量 
curl https://api.token.heimatianqi.com/v1/chat/completions \
  -H "Authorization: Bearer sk-heima-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"你好"}],"max_tokens":64}'

计费口径

输入按输入价、缓存命中按缓存价、输出按输出价；高峰时段乘高峰倍率；命中限免/折扣活动时按活动让利。

错误

状态 典型原因
400 请求体不合法
401 Key 无效或被禁用
403 无模型权限 / 需实名 / 来源被临时限制
429 限流或渠道容量已满
5xx 上游异常

错误响应里会带 request id，排查与对账时请保留（见错误码与限流）。

端点可达性验证

下面这段由文档验收套件真实执行：向本机网关发起一次未带 Key 的请求， 必须得到 401 与结构化 JSON 错误——证明该路径已被网关注册、且受鉴权中间件保护。

python3 -c "
import os,urllib.error,urllib.request
base=(os.environ.get('HEIMA_PROBE_BASE') or os.environ.get('HEIMA_BASE_URL','http://127.0.0.1:3000/v1')).split('/v1')[0]
req=urllib.request.Request(base+'/v1/chat/completions',data=b'{}',method='POST',headers={'Content-Type':'application/json'})
try:
    urllib.request.urlopen(req,timeout=15)
    raise SystemExit('expected 401 for unauthenticated request')
except urllib.error.HTTPError as e:
    body=e.read().decode('utf-8','ignore')
    assert e.code==401, 'unexpected status %s: %s'%(e.code,body[:160])
    assert 'error' in body or 'message' in body, 'non-JSON error body: %s'%body[:160]
print('endpoint reachable & auth-guarded: /v1/chat/completions')
"

说明：探针只证明"路由存在 + 鉴权生效"，不产生任何上游调用与费用。

常见问题

  • 这个端点要额外开通吗？ 取决于模型与上游：模型详情页会标注支持的端点；未开放时会返回明确错误， 不会静默降级到别的接口。
  • 并发/限流如何？ 平台有三层保护（模型 RPM、渠道容量、临时黑名单）， 拒绝时返回 429/403 且不消耗上游。

相关端点