API 参考

平台对外提供 OpenAI 兼容 的 REST 接口。一个 Key 调用全部已开放模型，切换模型只需改 model 字段。

基础信息

项	值
Base URL	https://api.token.heimatianqi.com/v1
鉴权	Authorization: Bearer sk-heima-xxxxxxxx
计价货币	人民币（¥）；单位 ¥ / 100 万 tokens
计价维度	输入 / 缓存命中 / 输出（缓存命中仅在供应商真实返回命中时单独计价）
高峰	高峰时段按倍率计价，按请求进入平台时的价格计算（见「高峰与平峰」）
流式	支持 stream: true（SSE，data: [DONE] 结束）

公开模型与人民币售价见控制台「模型与价格」，或公开接口 /api/platform/pricing。

端点一览

方法	路径	说明	状态
POST	/v1/chat/completions	对话补全（主力接口，支持流式、多模态输入、推理强度）	开放
POST	/v1/responses	OpenAI Responses 兼容接口	开放
GET	/v1/models	列出当前 Key 可用模型	开放
POST	/v1/embeddings	向量化	未开放（按上游能力逐步开放）
POST	/v1/rerank	文档重排序	未开放
POST	/v1/images/generations	图像生成	未开放（图像渠道尚未接入）
POST	/v1/video/generations	视频生成任务	未开放
POST	/v1/audio/transcriptions	语音识别	未开放

「未开放」表示平台当前未接入对应上游渠道，网关不会路由；接入后本页会同步更新。

对话补全

curl -s "${HEIMA_BASE_URL:-https://api.token.heimatianqi.com/v1}/chat/completions" \
  -H "Authorization: Bearer $HEIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mock-chat",
    "messages": [
      {"role": "system", "content": "你是简洁的助手"},
      {"role": "user", "content": "用一句话介绍你自己"}
    ],
    "max_tokens": 64
  }'

返回为标准 chat.completion 对象，usage 含 prompt_tokens / completion_tokens / total_tokens； 平台另外按「缓存命中」单独计费，命中量以供应商返回为准。

流式输出

curl -N -s "${HEIMA_BASE_URL:-https://api.token.heimatianqi.com/v1}/chat/completions" \
  -H "Authorization: Bearer $HEIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mock-chat",
    "messages": [{"role": "user", "content": "数到三"}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

推理强度（DeepSeek 系列）

两个 DeepSeek 入口都通过同一个请求字段控制推理强度，互不影响：

{
  "model": "deepseek-v4-flash",
  "messages": [{"role": "user", "content": "..."}],
  "reasoning_effort": "high"
}

取值	效果
low	最省算力（默认）
high	加强推理
max	最强推理（等价官方的最高思考强度）

多模态输入

支持图像理解的模型可直接传 image_url 内容块（与 OpenAI 一致）：

{
  "model": "deepseek-v4-flash-vision-exp",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "这张图里有什么？"},
      {"type": "image_url", "image_url": {"url": "https://example.com/a.png"}}
    ]
  }]
}

Responses 兼容接口

POST /v1/responses 接受 OpenAI Responses 风格的请求体：

{
  "model": "deepseek-v4-flash",
  "input": "用一句话说明 Responses 接口"
}

该端点由上游渠道能力决定：官方 DeepSeek / 支持 Responses 的渠道可直接使用； DEV 的 mock 上游只实现了 chat/completions，因此本地文档验证不含此端点。 生产环境请以控制台「模型与价格」中该模型标注的支持接口为准。

模型清单

curl -s "${HEIMA_BASE_URL:-https://api.token.heimatianqi.com/v1}/models" \
  -H "Authorization: Bearer $HEIMA_API_KEY"

返回 data[]，每项含 id（模型名）、owned_by 与 supported_endpoints（该模型支持的接口类型）。 可用模型由你所持 Key 的「允许模型」设置决定。

错误格式

失败时返回 HTTP 4xx/5xx 与统一错误体：

{
  "error": {
    "message": "insufficient_user_quota",
    "type": "new_api_error",
    "code": ""
  }
}

常见错误与处理见「错误码与常见问题」。