Tutorial
How to Use gpt-6-sol via the HiAPI API: curl, Python, and a Working Request
On this page
What you need before the first call
Before you write any code, get three things in place. Everything else in this tutorial builds on them.
A HiAPI API key
Every request to the HiAPI API is authenticated with an API key. Create one in your HiAPI account dashboard and store it somewhere safe, ideally in an environment variable rather than in your source files. Treat it like a password: if it leaks, rotate it.
export HIAPI_API_KEY="your-api-key-here"
The base endpoint
All calls in this guide go to the HiAPI API base endpoint, and each model is addressed through the same request path shape. You do not need a separate host or SDK per model — gpt-6-sol is selected in the request body, not by changing your client setup.
An HTTP client
You need one of the following:
curl, available by default on most Linux and macOS systems and in Windows terminals.- Python with the
requestslibrary installed (pip install requests), or the standard libraryurllibif you prefer no dependencies.
No other tooling is required. You do not need a vendor-specific SDK, and you do not need to install anything model-specific. If you can send an HTTPS POST with a JSON body and a header, you can call gpt-6-sol.
One habit worth adopting now: keep a scratch file with your working request so that when something fails you can compare the failing call against the last known-good one.
Authenticate with a bearer key
Authentication is the most common place a first call goes wrong, so it is worth doing deliberately.
The Authorization header
The HiAPI API expects your key in a standard bearer header:
Authorization: Bearer $HIAPI_API_KEY
That is the literal word Bearer, a single space, then the key. Common mistakes: omitting the word Bearer, including a stray newline from a copied value, or wrapping the key in quotes when the client already adds them.
Content type must be JSON
Requests carry a JSON body, so the content type header must match:
Content-Type: application/json
If this header is missing, some servers will still parse the body, but you should not rely on that — set it explicitly. A mismatched content type is a frequent cause of request-validation errors that look like body errors.
A minimal header set
You only need the two headers above:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
Keep the header set small. Adding speculative headers borrowed from other API examples is more likely to cause confusion than to help. Once a call succeeds with these two headers, you have a clean baseline to compare against later.
Avoid pasting your key directly into shell history or committed files. Referencing the environment variable, as above, keeps the secret out of your source and out of your terminal history.
Build the request body for gpt-6-sol
The request body is JSON, and its core is a list of messages. Start minimal; add fields only after a call succeeds.
The minimal payload
The smallest useful body names the model and provides one message:
{
"model": "gpt-6-sol",
"messages": [
{ "role": "user", "content": "Explain what an API bearer token is in one sentence." }
]
}
Two fields do the work here:
modelselectsgpt-6-solso the same endpoint can serve other models later.messagesis an ordered list of turns. Each entry has arole(system,user, orassistant) and acontentstring.
Safe defaults versus optional additions
Treat model and messages as required. Everything else is optional and should be added deliberately:
- A
systemmessage placed first inmessagessets behavior or tone for the conversation. This is a plain message, not a separate top-level field. - Output-length controls, if you need them, are set as parameters in the body. Add them only if the default output is too short or too long for your use case.
- Sampling-style parameters change output shape, not validity. Avoid changing them while debugging a failing call, because they will not fix authentication or body-shape errors.
A practical rule
When something fails, the payload should be as close to the minimal example as possible. Strip optional fields one at a time until the call succeeds, then re-add them. This isolates the problem fast: a bad parameter is much easier to find than a bad parameter buried among five good ones.
Make a working request with curl
Here is a complete command you can run as-is once your key is exported. It uses a placeholder endpoint path that matches the HiAPI API conventions described above.
curl -sS -X POST "$HIAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6-sol",
"messages": [
{ "role": "user", "content": "Explain what an API bearer token is in one sentence." }
]
}'
Set HIAPI_BASE_URL to the base endpoint from your HiAPI dashboard. The flags matter:
-X POSTsets the method; these calls are POSTs.-Hadds each header, one per line.-dsupplies the JSON body. Single quotes protect it from shell interpolation.-sSkeeps output quiet but still shows errors, which is what you want for scripting.
Reading the response
A successful response is JSON. You will typically see a top-level object containing the model name and a list of choices, each with a message whose content holds the generated text. Read the shape before reading the prose: confirm the object parses, then locate the content field.
For readability, pipe through a JSON formatter:
... | python -m json.tool
If your terminal instead prints an error object, the call did not succeed — skip ahead to the error section rather than tweaking the prompt. The prompt is not the problem when the request never reached the model.
The same request in Python
The payload you just validated in curl transfers directly. Keep the body identical so that a fix proven in the terminal also applies in code.
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "gpt-6-sol",
"messages": [
{"role": "user", "content": "Explain what an API bearer token is in one sentence."}
],
}
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
}
response = requests.post(
f"{base_url}/chat/completions",
headers=headers,
json=payload,
timeout=60,
)
response.raise_for_status()
data = response.json()
for choice in data.get("choices", []):
message = choice.get("message", {})
print(message.get("content", ""))
Why this version is safer in application code
- The body is a dict.
requestsserializes it and sets the content type for you when you passjson=payload, but keeping the explicit header avoids surprises if you switch clients. - The key comes from the environment. Nothing secret is hardcoded, so the file can be committed.
raise_for_status()runs first. A non-2xx response raises immediately, before you try to read fields that will not exist on an error body.- A timeout is set. Without one, a stalled connection can hang a worker indefinitely.
The loop over choices also guards against missing keys, which makes the example tolerant of responses that contain little or no output. Build your production wrapper around this skeleton: validate, send, check status, then parse.
Stream the response instead of waiting
By default, the API returns the full answer in a single JSON response. For long outputs or interactive interfaces, you can instead ask for the response to be delivered incrementally as it is generated.
The streaming switch
Streaming is enabled with a request-body flag rather than a different endpoint:
{
"model": "gpt-6-sol",
"messages": [
{ "role": "user", "content": "Write a short paragraph about HTTP status codes." }
],
"stream": true
}
Add the flag last, after the non-streaming call already works. It changes how the response is framed, not whether the request is valid.
Consuming incremental output
When streaming is on, the response is no longer a single JSON document. It arrives as a sequence of events, often line-delimited, each carrying a small piece of the output. Your client must read them as they arrive instead of calling .json() on the whole body.
with requests.post(
f"{base_url}/chat/completions",
headers=headers,
json=payload,
stream=True,
timeout=60,
) as response:
response.raise_for_status()
for line in response.iter_lines():
if line:
print(line.decode("utf-8"))
In the terminal, the same switch behaves differently from the non-streaming call: output appears progressively, so a truncated pipe may look like a failed request when it is only an interrupted stream.
Which to use
Use non-streaming for batch jobs, tests, and anything that needs the complete object at once. Use streaming when a human is waiting on the text, or when outputs are long enough that the delay is noticeable. Keep both paths in your codebase, since debugging is easier on the non-streaming path.
Read and fix common error codes
Diagnose by status code first, then by response body. Do not change the model or rewrite the prompt until you know which layer failed.
401 Unauthorized
Cause: missing, malformed, or revoked key. Fix: confirm the header reads exactly Authorization: Bearer <key>, check for hidden whitespace or a stale environment variable, and verify the key is still active in your dashboard. Echo the variable length rather than the value to catch empty-variable mistakes.
400 Bad Request
Cause: the body did not parse or a required field is missing. Fix: send the minimal payload again, with model and messages only. Validate your JSON with python -m json.tool before sending; a trailing comma or a typo in model is a common culprit. Confirm Content-Type is application/json.
403 Forbidden
Cause: the key is valid but lacks access to the requested resource. Fix: check that your account has access to gpt-6-sol, and that the model name in the body matches what your account is provisioned for.
404 Not Found
Cause: the URL path is wrong, usually a typo in the endpoint or a missing or doubled base path. Fix: compare the full URL against a working curl call, character by character.
429 Too Many Requests
Cause: you are sending requests faster than your account allows. Fix: back off and retry with increasing delays. Respect any retry guidance in the response headers, and never retry tightly in a loop — that makes the problem worse. Distinguish this from a 5xx, which indicates a server-side issue rather than your request rate.
5xx Server Errors
Cause: the service failed to process an otherwise valid request. Fix: retry with backoff; if it persists, capture the response body and request ID, and avoid changing your payload since it already worked.
A repeatable debugging order
- Status code — auth, path, or body?
- Response body — does it name the offending field?
- Payload shape — back to the minimal example.
- Only then prompt or parameters.
That order consistently shortens the time from failure to fix. Once your call is stable, keep the working curl and Python versions side by side so every future test starts from a known-good state.
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