Blog

Tutorial

How to Call kimi-k3.1-pro-highspeed via the HiAPI API: curl and Python Examples

Nov 12, 2026 13 min read
HiAPI blog cover image: on a dark coffee-colored background, wide woven bands interlace in a basket-weave rhythm, accented with beige and brass tones, forming a flat graphic composition.
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. system sets the persona and constraints; user carries the task. Order matters: later messages take precedence in steering behavior. For multi-turn flows, keep appending user and assistant turns 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 — false here means you get one JSON object back when generation finishes. The next sections cover true.

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=payload instead 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 a KeyError on choices three 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 delta may have no content key. Use .get() and skip empties.
  • Handle partial lines. Frame boundaries can split lines. iter_lines deals 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: false is 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 Authorization header 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-highspeed appears 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_tokens is 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 →

Start building with persistent AI artifacts

Get your API key and call image, video and audio models through one task-based API.

Read the API docs