Tutorial
How to Call kimi-k3.1-pro-highspeed via the HiAPI API: curl and Python Examples
On this page
What kimi-k3.1-pro-highspeed Is and When to Reach for It
kimi-k3.1-pro-highspeed is one of the chat-style models available through HiAPI. You call it the same way you call any other chat model on the platform: send a list of messages, get back a completion. The "high-speed" in the name signals its intended trade-off — you reach for it when latency matters more than raw reasoning depth, and you want a predictable response time rather than the slowest, most thorough answer.
That makes it a good fit for a few concrete workloads:
- Interactive surfaces — chat UIs, autocomplete, and inline assistants where a user is waiting on the response.
- High-volume pipelines — classification, extraction, summarization, and rewrite jobs where you need throughput and the per-request result is short.
- Agent loops with many hops — multi-step flows where each individual call is small and the total latency is dominated by the number of round trips, not by any single one.
It is a less obvious choice when the task needs long, deliberate reasoning over a large context, or when you are generating something where a single slow, high-quality pass beats several fast ones. In those cases, benchmark the output quality first before optimizing for speed — a fast but wrong answer is more expensive than a slow correct one.
Because the model is served through HiAPI's unified interface, switching to or away from it later is a payload change, not a rewrite. Keep the model name in configuration rather than hard-coded at call sites, and you can A/B test it against other models without touching your request-building code.
What "chat-style" means in practice
Every request is a structure like this: a model identifier, an ordered list of messages (each with a role and content), and optional parameters such as stream, temperature, and max_tokens. The system prompt goes in as a message with role: "system". That is the entire mental model — everything in the rest of this guide is just plumbing around that shape.
Prerequisites: Credentials, Endpoint, and Model Name
Before you write any code, confirm you have these four things. Most first-call failures come from a gap in this list, not from a bug in the request body.
1. An API key
Generate a key from your HiAPI account dashboard. Treat it as a secret: load it from an environment variable, never commit it, and rotate it if it ever lands in logs or a shared notebook.
export HIAPI_API_KEY="your-key-here"
2. The base URL
The endpoint is the HiAPI base URL plus the chat completions path. Keep the base URL in configuration so that a change never means a code edit:
export HIAPI_BASE_URL="https://api.hiapi.ai/v1"
3. The model identifier
The model string to send is exactly:
kimi-k3.1-pro-highspeed
Copy it character for character. Model names are matched literally — an extra space, a different case, or a typo will come back as a model-not-found style error rather than a validation error on some other field, which can send you hunting in the wrong place.
4. A client that can send HTTPS
For the curl examples below you need nothing beyond a shell with curl installed, which is standard on macOS and most Linux images. For the Python section you need Python 3.8+ and the requests package:
pip install requests
If you prefer an SDK-style client, the same endpoint, key, and model name apply — the wire format is what matters, and this guide sticks to raw HTTP so nothing is hidden behind an abstraction.
Sanity check
Run a quick check that your key and base URL resolve before you build a full request — a deliberately minimal call with a one-word prompt. If that succeeds, any later failure is about your payload, not your credentials.
A Working curl Request
Here is a complete, copy-pasteable request. It uses a system message to set behavior, a user message as the actual ask, and a fixed max_tokens so the response stays short while you are testing.
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": "You are a concise technical assistant. Answer in two sentences or fewer."},
{"role": "user", "content": "Explain what an idempotency key is and why it matters for retries."}
],
"temperature": 0.3,
"max_tokens": 200,
"stream": false
}'
Field by field
model— the model identifier from the previous section. Required.messages— an ordered array.systemsets the persona and constraints;usercarries the task. Order matters: later messages take precedence in steering behavior. For multi-turn flows, keep appendinguserandassistantturns to the same array rather than concatenating everything into one giant user message.temperature— sampling randomness. Low values give more repeatable output, which is what you want for extraction and classification. Raise it only when you actually want variation.max_tokens— an upper bound on the generated response. Setting it explicitly protects you from a runaway generation and makes latency predictable.stream—falsehere means you get one JSON object back when generation finishes. The next sections covertrue.
What comes back
The response is a JSON object containing a choices array. The text you want is at choices[0].message.content. There is also a usage block describing token consumption — log it, because it is your only per-request cost signal when billing is token-based.
If you are debugging, pipe the output through a formatter so it is readable:
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
Putting the body in payload.json and using -d @payload.json keeps the shell quoting out of your way once the payload grows past a few fields.
Porting the Request to Python
The goal here is not a demo script but a function you can import. Keep the payload identical to the curl version — the same fields, the same names, the same model string — so behavior does not change when you switch tools.
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 = "You are a concise technical assistant.",
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"]
Then:
print(chat("Summarize the difference between PUT and PATCH in one sentence."))
Why written this way
json=payloadinstead of hand-rolled JSON — requests serializes it correctly and sets the content type, which removes a whole class of quoting bugs.- An explicit
timeout— without one, a stalled connection can hang your worker indefinitely. Thirty seconds is generous for a short completion; tune it down for interactive paths. raise_for_status()early — you want HTTP-level failures to surface as exceptions at the call boundary, not as aKeyErroronchoicesthree lines later.- Configuration at module level — key, base URL, and model in one place. When you later A/B test another model, you change one constant.
Multi-turn conversations
For a real conversation, accept the message list as a parameter instead of building two fixed messages:
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"),
}
Append the assistant's reply back into messages with role: "assistant" to continue the thread, and trim old turns when the history gets long — context is billed, so an unbounded transcript quietly inflates every request.
Enabling and Consuming Streaming Responses
Set "stream": true and the server sends the response incrementally as server-sent events rather than one object at the end. For anything a user is watching, this is worth the extra client-side work: time-to-first-token drops dramatically even when total generation time is unchanged.
The curl view
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": "Write a haiku about retries."}],
"stream": true
}'
-N disables curl's output buffering so you actually see events arrive as they are sent. What you get is a sequence of lines, each starting with data: , carrying a JSON fragment. The final event is data: [DONE]. Treat that sentinel as the end-of-stream marker, not as parseable JSON.
The Python client
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)
Rules that keep streaming correct
- Concatenate, do not replace. Each chunk carries only the new fragment. Accumulate into a list and join once at the end; appending to a string in a loop is quadratic on long outputs.
- Guard against missing content. Some chunks carry only metadata, so
deltamay have nocontentkey. Use.get()and skip empties. - Handle partial lines. Frame boundaries can split lines.
iter_linesdeals with this, but if you parse the raw byte stream yourself, buffer until you see a newline. - Set a stream-appropriate timeout. The total stream can legitimately outlast a short request timeout. Use a longer read timeout or a per-chunk read deadline rather than disabling timeouts entirely.
- Keep a non-streaming path. When you only need the final text for a background job,
stream: falseis simpler and cheaper to reason about. Reserve streaming for the interactive path.
Reading Error Responses and Designing Retries
Retries help only when the failure is transient. Blindly retrying a malformed request just multiplies a mistake. The useful split is between errors you fix in code and errors the network or the server will resolve on their own.
Classify by status
Do not retry — fix the request:
- 400 Bad Request — malformed JSON, a missing required field, or an invalid parameter value. Read the error message, correct the payload, and add a test so it does not come back.
- 401 Unauthorized — missing, malformed, or revoked key. Check the
Authorizationheader format and that the environment variable is actually set in the running process, not just your shell. - 403 Forbidden — the key is valid but not permitted for this action or model. A retry loop here is pure noise.
- 404 Not Found — usually a wrong path or an unknown model identifier. Verify the base URL and the exact model string.
- 422-style validation errors — a parameter is the right type but an unacceptable value (for example an out-of-range
temperature). Clamp the value in code.
Retry with backoff:
- 429 Too Many Requests — you are over a rate limit. Back off, and if the response includes a retry-after hint, honor it rather than guessing.
- 500 / 502 / 503 / 504 — server-side or gateway failures. These are exactly what exponential backoff is for.
- Connection errors and timeouts — the socket failed before a response completed. Retry, but only if the operation is safe to repeat.
A retry loop that behaves
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"non-retryable {r.status_code}: {r.text[:200]}")
if attempt == max_attempts:
raise RuntimeError(f"exhausted retries, last {r.status_code}")
delay = base_delay * (2 ** (attempt - 1))
time.sleep(delay + random.uniform(0, 0.5))
raise RuntimeError("unreachable")
Two details that matter in production
- Jitter is not optional. Without it, a fleet of workers that hit a rate limit at the same moment retries in lockstep and recreates the spike. The random term above spreads them out.
- Bound the total time, not just the attempts. Four attempts with exponential backoff can exceed your request deadline. Cap the number of attempts so the worst case still fits inside the caller's budget, and pass the remaining time down as the timeout for the next attempt.
Do not retry streaming requests on a partial failure without deciding what to do with the text you already emitted to the user. The common pattern is to retry only if nothing has been shown yet, and otherwise surface the truncation.
Checklist Before You Ship
A short list to run before this code becomes load-bearing.
- Timeouts everywhere. Every request has an explicit connect/read timeout, and the value is chosen from your latency budget rather than copied from an example.
- Secrets outside the repo. The API key comes from the environment or a secret manager, and it is never written into logs. Scrub headers from any request logger.
- Model name in one place.
kimi-k3.1-pro-highspeedappears as a single constant so you can swap or A/B test it without a search-and-replace. - Errors classified, not swallowed. Retryable and non-retryable paths are distinct in code, backoff includes jitter, and the attempt count is capped.
- Usage logged. Record the token usage returned with each response alongside latency and status. When billing is token-based, this is your early warning for a prompt that has quietly grown too large.
- Streaming path tested for real. Verify that concatenated output equals the non-streaming output for the same prompt, and that a mid-stream disconnect does not leave your UI in a broken state.
- Cost awareness by design.
max_tokensis always set, conversation history is trimmed, and long documents are summarized before being stuffed into context — the three levers that keep spend proportional to value.
With that in place, moving from a curl proof-of-concept to a production caller is mostly configuration. Start with the non-streaming function, add streaming once the interactive path exists, and let the retry wrapper absorb the failures you cannot prevent.
Related articles
View all articles →-
Tutorial
gpt-6.2-sol in Practice: 5 High-Value Uses of a Text Model in Business
-
Tutorial
gpt-6.2-astra Practical Guide: Integration and Implementation Key Points for 5 High-Value Text Scenarios
A Developer's Checklist from Scenario Selection to Engineering Implementation
-
Tutorial
Tripo H3.1 Practical Application Scenarios: 5 High-Value Use Cases and Implementation Essentials
From text-to-3D to multiview reconstruction: choosing the right mode and parameters by business scenario