教程
如何通过 HiAPI API 调用 kimi-k3.1-pro-highspeed:curl 与 Python 示例
本页内容
kimi-k3.1-pro-highspeed 是什么,以及何时该选它
kimi-k3.1-pro-highspeed 是 HiAPI 提供的聊天式模型之一。调用方式与平台上任何其他聊天模型相同:发送一组消息,拿回一个补全结果。名字中的“high-speed”表明了它预期的取舍——当你更看重延迟而非原始推理深度,想要可预测的响应时间而不是最慢、最详尽的答案时,就选它。
因此它很适合以下几类具体工作负载:
- 交互式界面——聊天 UI、自动补全和内联助手,用户正等待响应。
- 高吞吐管道——分类、抽取、摘要和改写任务,你需要吞吐量,且单次请求结果较短。
- 多跳的智能体循环——多步骤流程中每次调用都很小,总延迟主要取决于往返次数,而非任何单次调用。
当任务需要在大量上下文上进行长时间、深思熟虑的推理,或者你生成的内容是“一次缓慢但高质量的通过胜过多次快速通过”时,它就不是显而易见的选择。在这些情况下,先对输出质量做基准测试,再针对速度做优化——快速但错误的答案比缓慢但正确的答案代价更高。
由于该模型通过 HiAPI 的统一接口提供,之后切换到其他模型或从其他模型切回它,只是改动请求负载,而非重写代码。把模型名放在配置中而不是在调用处硬编码,你就能在不改动请求构建代码的情况下与其他模型做 A/B 测试。
“聊天式”在实践中意味着什么
每个请求都是这样的结构:一个模型标识符、一个有序的消息列表(每条消息包含 role 和 content),以及可选参数,如 stream、temperature 和 max_tokens。系统提示词以 role: "system" 的消息传入。这就是全部的心智模型——本指南其余部分都只是围绕这一形状的管道工作。
前置条件:凭证、端点与模型名
在写任何代码之前,确认你已具备以下四项。大多数首次调用失败都源于此清单中的缺失,而非请求体中的 bug。
1. 一个 API 密钥
从你的 HiAPI 账户仪表盘生成密钥。将其视为机密:从环境变量加载,绝不提交到仓库,一旦它出现在日志或共享笔记本中就要轮换。
export HIAPI_API_KEY="your-key-here"
2. 基础 URL
端点由 HiAPI 基础 URL 加上聊天补全路径构成。将基础 URL 放在配置中,这样变更时无需改代码:
export HIAPI_BASE_URL="https://api.hiapi.ai/v1"
3. 模型标识符
要发送的模型字符串完全是:
kimi-k3.1-pro-highspeed
逐字符复制。模型名按字面匹配——多一个空格、大小写不同或拼写错误,都会返回模型未找到类的错误,而不是其他字段的校验错误,这可能让你去错误的地方排查。
4. 能发送 HTTPS 的客户端
对于下面的 curl 示例,你只需要一个安装了 curl 的 shell,这在 macOS 和大多数 Linux 镜像上是标配。对于 Python 部分,你需要 Python 3.8+ 和 requests 包:
pip install requests
如果你偏好 SDK 风格的客户端,同样的端点、密钥和模型名同样适用——重要的是线上格式,本指南坚持使用原始 HTTP,以免任何东西隐藏在抽象之后。
健全性检查
在构建完整请求之前,先跑一个快速检查,确认密钥和基础 URL 能解析——一个故意最小化、只含一个词提示词的调用。如果它成功,之后任何失败都关乎你的请求负载,而非凭证。
一个可用的 curl 请求
下面是一个完整、可直接复制粘贴的请求。它用一条系统消息设定行为,用一条用户消息作为实际请求,并固定 max_tokens,以便测试时响应保持简短。
curl -s "$HIAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kimi-k3.1-pro-highspeed",
"messages": [
{"role": "system", "content": "你是一个简洁的技术助手。请用两句话或更少作答。"},
{"role": "user", "content": "解释什么是幂等键,以及它为什么对重试很重要。"}
],
"temperature": 0.3,
"max_tokens": 200,
"stream": false
}'
逐字段说明
model——上一节中的模型标识符。必填。messages——一个有序数组。system设定人设和约束;user承载任务。顺序很重要:靠后的消息在引导行为上优先级更高。对于多轮流程,持续向同一数组追加user和assistant轮次,而不是把所有内容拼接成一条巨大的用户消息。temperature——采样随机性。低值给出更可重复的输出,这正是抽取和分类所需要的。只有当你确实想要变化时才调高它。max_tokens——生成响应的上限。显式设置它可以保护你免于失控的生成,并让延迟可预测。stream——此处为false,意味着生成完成时你会拿到一个 JSON 对象。后续章节会介绍true。
返回什么
响应是一个包含 choices 数组的 JSON 对象。你要的文本位于 choices[0].message.content。还有一个 usage 块描述 token 消耗——记录它,因为在按 token 计费时,这是你唯一的单次请求成本信号。
如果你在调试,把输出通过格式化器管道处理,使其可读:
curl -s "$HIAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @payload.json | python -m json.tool
把请求体放进 payload.json 并使用 -d @payload.json,一旦负载超过几个字段,就能避免 shell 引号带来的麻烦。
将请求移植到 Python
这里的目标不是演示脚本,而是一个可导入的函数。保持请求负载与 curl 版本完全一致——相同的字段、相同的名称、相同的模型字符串——这样切换工具时行为不会改变。
import os
import requests
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai/v1")
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kimi-k3.1-pro-highspeed"
def chat(
user_message: str,
system_message: str = "你是一个简洁的技术助手。",
temperature: float = 0.3,
max_tokens: int = 400,
timeout: float = 30.0,
) -> str:
payload = {
"model": MODEL,
"messages": [
{"role": "system", "content": system_message},
{"role": "user", "content": user_message},
],
"temperature": temperature,
"max_tokens": max_tokens,
"stream": False,
}
response = requests.post(
f"{BASE_URL}/chat/completions",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=timeout,
)
response.raise_for_status()
data = response.json()
return data["choices"][0]["message"]["content"]
然后:
print(chat("用一句话总结 PUT 和 PATCH 的区别。"))
为何这样写
- 用
json=payload而非手写 JSON——requests 会正确序列化并设置内容类型,消除了一整类引号 bug。 - 显式的
timeout——没有它,停滞的连接可能无限期挂起你的工作进程。对于简短补全,三十秒很宽裕;对于交互路径,调低它。 - 尽早
raise_for_status()——你希望 HTTP 层失败在调用边界就作为异常暴露,而不是三行之后在choices上抛出KeyError。 - 模块级配置——密钥、基础 URL 和模型集中在一处。之后 A/B 测试其他模型时,只需改一个常量。
多轮对话
对于真实对话,接受消息列表作为参数,而不是构建两条固定消息:
def chat_with_history(messages: list, **kwargs) -> dict:
payload = {"model": MODEL, "messages": messages, "stream": False, **kwargs}
r = requests.post(
f"{BASE_URL}/chat/completions",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=30.0,
)
r.raise_for_status()
body = r.json()
return {
"content": body["choices"][0]["message"]["content"],
"usage": body.get("usage"),
}
将助手的回复以 role: "assistant" 追加回 messages 以继续对话,并在历史变长时修剪旧轮次——上下文会计费,所以无限制的对话记录会悄悄抬高每个请求的成本。
启用并消费流式响应
设置 "stream": true,服务器会以服务器发送事件的形式增量发送响应,而不是在最后发送一个对象。对于任何用户正在观看的内容,这值得额外的客户端工作:即使总生成时间不变,首 token 时间也会显著下降。
curl 视角
curl -N -s "$HIAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kimi-k3.1-pro-highspeed",
"messages": [{"role": "user", "content": "写一首关于重试的俳句。"}],
"stream": true
}'
-N 禁用 curl 的输出缓冲,这样你才能真正看到事件在发送时到达。你得到的是一系列行,每行以 data: 开头,携带一个 JSON 片段。最后的事件是 data: [DONE]。把该哨兵视为流结束标记,而不是可解析的 JSON。
Python 客户端
import json
import requests
def stream_chat(user_message: str, timeout: float = 60.0) -> str:
payload = {
"model": MODEL,
"messages": [{"role": "user", "content": user_message}],
"stream": True,
}
pieces = []
with requests.post(
f"{BASE_URL}/chat/completions",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
stream=True,
timeout=timeout,
) as r:
r.raise_for_status()
for raw in r.iter_lines(decode_unicode=True):
if not raw or not raw.startswith("data: "):
continue
data = raw[len("data: "):].strip()
if data == "[DONE]":
break
chunk = json.loads(data)
delta = chunk["choices"][0].get("delta", {})
text = delta.get("content")
if text:
pieces.append(text)
print(text, end="", flush=True)
return "".join(pieces)
保持流式正确的规则
- 拼接,而非替换。每个块只携带新片段。累积到列表中,最后一次性 join;在循环中向字符串追加在长输出上是二次复杂度。
- 防范缺失内容。有些块只携带元数据,因此
delta可能没有content键。使用.get()并跳过空值。 - 处理不完整的行。帧边界可能拆分行。
iter_lines处理了这一点,但如果你自己解析原始字节流,要缓冲到看见换行符为止。 - 设置适合流的超时。总流可能合法地超过短请求超时。使用更长的读取超时或按块读取截止时间,而不是完全禁用超时。
- 保留非流式路径。当你只需要后台任务的最终文本时,
stream: false更简单,推理成本也更低。将流式留给交互路径。
解读错误响应并设计重试
只有失败是暂时性的,重试才有帮助。盲目重试格式错误的请求只会放大错误。有用的区分是:你在代码中修复的错误,与网络或服务器会自行解决的错误。
按状态码分类
不要重试——修复请求:
- 400 Bad Request——JSON 格式错误、缺少必填字段或参数值无效。阅读错误消息,修正请求负载,并添加测试以防再次出现。
- 401 Unauthorized——密钥缺失、格式错误或已撤销。检查
Authorization头格式,以及环境变量是否确实在运行进程中设置,而不仅仅是在你的 shell 中。 - 403 Forbidden——密钥有效,但不被允许执行此操作或使用此模型。此处的重试循环纯属噪音。
- 404 Not Found——通常是路径错误或模型标识符未知。核实基础 URL 和确切的模型字符串。
- 422 类校验错误——参数类型正确但值不可接受(例如超出范围的
temperature)。在代码中钳制该值。
带退避重试:
- 429 Too Many Requests——你超出了速率限制。退避,如果响应包含 retry-after 提示,遵照它而不是猜测。
- 500 / 502 / 503 / 504——服务器端或网关故障。这正是指数退避的用武之地。
- 连接错误和超时——在响应完成前套接字失败。重试,但仅当操作可安全重复时。
一个行为得当的重试循环
import random
import time
import requests
RETRYABLE_STATUS = {429, 500, 502, 503, 504}
def post_with_retries(url, headers, payload, max_attempts=4, base_delay=1.0):
for attempt in range(1, max_attempts + 1):
try:
r = requests.post(url, headers=headers, json=payload, timeout=30.0)
except (requests.ConnectionError, requests.Timeout):
if attempt == max_attempts:
raise
else:
if r.status_code < 400:
return r.json()
if r.status_code not in RETRYABLE_STATUS:
raise RuntimeError(f"不可重试 {r.status_code}: {r.text[:200]}")
if attempt == max_attempts:
raise RuntimeError(f"重试已耗尽,最后一次 {r.status_code}")
delay = base_delay * (2 ** (attempt - 1))
time.sleep(delay + random.uniform(0, 0.5))
raise RuntimeError("unreachable")
生产环境中重要的两个细节
- 抖动不是可选项。没有它,一群同时撞上速率限制的工作进程会步调一致地重试,重新制造尖峰。上面的随机项将它们分散开。
- 限制总时间,而不仅是尝试次数。四次指数退避尝试可能超过你的请求截止时间。限制尝试次数,使最坏情况仍能落在调用方预算内,并将剩余时间作为下一次尝试的超时时间向下传递。
不要在部分失败时重试流式请求,除非你决定如何处理已经发送给用户的文本。常见模式是仅在尚未展示任何内容时才重试,否则就暴露截断。
上线前的检查清单
在这段代码成为关键负载之前,运行一个简短清单。
- 到处都有超时。每个请求都有显式的连接/读取超时,且该值来自你的延迟预算,而不是从示例中复制。
- 机密在仓库之外。API 密钥来自环境或密钥管理器,且绝不写入日志。从任何请求日志记录器中清除请求头。
- 模型名集中在一处。
kimi-k3.1-pro-highspeed作为单一常量出现,这样你无需搜索替换即可替换或 A/B 测试它。 - 错误被分类,而非被吞掉。可重试和不可重试路径在代码中分明,退避包含抖动,且尝试次数有上限。
- 记录用量。将每次响应返回的 token 用量与延迟和状态一起记录。当计费基于 token 时,这是提示词悄悄变得过大的早期预警。
- 流式路径经过真实测试。验证相同提示词下拼接输出等于非流式输出,并且流中途断开不会让你的 UI 处于损坏状态。
- 按设计控制成本。始终设置
max_tokens,修剪对话历史,长文档在塞入上下文前先做摘要——这三个杠杆让花费与价值成比例。
做到这些之后,从 curl 概念验证到生产调用方主要就是配置工作。从非流式函数开始,交互路径存在后再添加流式,让重试包装器吸收你无法预防的失败。