Blog

Tutorial

How to Call gpt-5.6-sol@azure via the HiAPI API: curl and Python

Authentication, request body structure, working examples, and error handling

Nov 10, 2026 13 min read
Layered paper sheets in cream and graphite receding in shallow steps, with one terracotta sheet as accent — cover art for the gpt-5.6-sol@azure tutorial.
On this page

What gpt-5.6-sol@azure Means as a HiAPI Model Target

gpt-5.6-sol@azure is a model identifier, not a separate SDK, not a separate endpoint, and not a separate authentication scheme. It is the exact string you place in the model field of a chat completions request sent to HiAPI.

The @azure suffix tells you which backing provider serves that model variant. From your application's point of view this changes nothing about how you call it: same base URL, same bearer authentication, same request and response shape as any other chat model on the platform. You do not install anything extra, and you do not need provider-specific credentials — HiAPI holds the routing and provider relationship on its side.

The practical consequence is that any OpenAI-compatible client you already use can target this model with two edits: point the client's base URL at HiAPI, and set the model name to gpt-5.6-sol@azure. If you are currently hardcoding a model name somewhere in your config, that config value is the only thing that has to change to switch between models on the platform — which makes A/B comparisons cheap.

Throughout this tutorial, the identifier will always appear as the literal string gpt-5.6-sol@azure. Type it exactly: case matters and stray whitespace from copy-paste is a real cause of the "unknown model" errors covered later.

What you will need before starting

  • A HiAPI account with access to the platform.
  • An API key generated from your account.
  • A shell with curl, or Python 3 with the requests library installed.

No other tooling is required for the examples below.

Getting Your API Key and Configuring Authentication

Authentication on HiAPI is a bearer token: your API key goes into the Authorization header of every request, prefixed with the word Bearer and a single space.

Authorization: Bearer YOUR_API_KEY

You generate the key from your account dashboard. Treat it like a password — it is a live credential that can spend your balance, and it should never appear in a commit, a screenshot, a shared notebook, or a log line.

Store it in an environment variable

The baseline practice is to export the key once per shell session and read it from the environment everywhere else:

export HIAPI_API_KEY="your-key-here"

On a server, set it through your process manager or secret store rather than a checked-in .env file. If a .env file is genuinely the only option, add it to .gitignore before you write the first key into it.

Reference it, do not inline it

In curl, reference the shell variable so the key never appears in your command history or in the process list:

curl -H "Authorization: Bearer $HIAPI_API_KEY" ...

In Python, read it with os.environ at runtime:

import os

API_KEY = os.environ["HIAPI_API_KEY"]

Using os.environ["..."] rather than os.environ.get("...") is deliberate: if the variable is missing, you want a loud failure at startup rather than a confusing authentication error fifteen lines later.

Key hygiene rules worth internalizing now

  • One key per environment. A development key and a production key should be separate, so you can rotate or revoke one without breaking the other.
  • Rotate on exposure. If a key ever lands in a public place, revoke it and issue a new one — do not just delete the commit.
  • Do not log headers. Request-logging middleware that dumps all headers will happily write your bearer token to disk. Redact Authorization before logging.

If you get an authentication error on your first call, the cause is almost always one of: the variable was exported in a different shell than the one running the request, the Bearer prefix was omitted, or the key was copied with a trailing newline.

Anatomy of a Minimal Request Body

Every call to gpt-5.6-sol@azure is a POST with a JSON body. You can build a valid one with exactly two fields, which is the best way to start: get a response first, then add knobs.

Required fields

  • model — the string gpt-5.6-sol@azure. This is what routes the request to the right target.
  • messages — an array of message objects. Each object has a role and content. The conventional roles are system for instructions that shape behavior, user for the input, and assistant for prior turns in a multi-turn conversation.

A minimal body looks like this:

{
  "model": "gpt-5.6-sol@azure",
  "messages": [
    { "role": "user", "content": "Explain what an idempotency key is in one paragraph." }
  ]
}

That is enough. The response comes back in the chat completions shape: a choices array where the first element holds the assistant's reply under message.content, plus a usage block describing token consumption. Your code should read from choices[0].message.content rather than assuming any other field.

Optional fields worth knowing about

These are not required, but they are the ones you will reach for first:

  • temperature — sampling randomness. Lower values make output more deterministic and repetitive; higher values make it more varied. Pick a value deliberately rather than leaving it to habit.
  • max_tokens (or the equivalent output-length cap your client exposes) — an upper bound on generated length. Useful for both latency and cost control.
  • top_p — an alternative randomness control. In practice, adjust temperature or top_p, not both at once, or you will not be able to attribute a change in behavior to either one.
  • stream — when true, the response arrives incrementally as server-sent events instead of a single JSON document. Great for user-facing interfaces, more work to parse correctly.
  • stop — one or more sequences that end generation early.

A note on multi-turn conversations

The API is stateless. Nothing is remembered between requests. To continue a conversation you resend the whole messages array each time, appending the previous assistant reply and the new user message. Long conversations therefore grow the request body, and token usage grows with it — budget for that when you design a chat feature.

Keep the body small at first

Start with the two required fields and confirm you get a sane response. Then add one parameter at a time and observe the difference. Debugging is much easier when you have one recent known-good baseline.

A Working curl Request

Here is a complete, runnable request. Replace the base URL with the one shown on the platform's API documentation if it differs in your region or plan, and make sure HIAPI_API_KEY is exported in the current shell.

curl -sS -X POST "https://api.hiapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol@azure",
    "messages": [
      { "role": "system", "content": "You are a concise technical assistant." },
      { "role": "user", "content": "Give me three practical uses for idempotency keys." }
    ],
    "temperature": 0.3
  }'

What each flag is doing

  • -sS silences the progress meter but still prints errors — so a failure is not invisible.
  • -X POST sets the method explicitly, mostly for readability.
  • The Authorization header carries the bearer token from the environment.
  • Content-Type: application/json is mandatory; without it the server cannot know how to parse the body.
  • -d supplies the JSON payload. Wrap it in single quotes so the shell does not interpret the double quotes inside.

Reading the response

A successful call returns JSON with a choices array. The text you want is at choices[0].message.content. There is also a usage object with prompt and completion token counts — log it, because it is the only cheap way to see your consumption trending before it becomes a surprise.

If you want to eyeball the structure without fighting the terminal, pipe it through a formatter:

curl -sS -X POST "https://api.hiapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-sol@azure","messages":[{"role":"user","content":"Say hello."}]}' \
  | python3 -m json.tool

That single line is the fastest smoke test in existence for a new key. Run it before you touch any application code — if it fails, the problem is credentials or connectivity, not your program.

The Same Request in Python

The requests version is short but should be written carefully: check the status code before you parse the body, because an error response is not shaped like a success response and will produce a confusing KeyError if you go straight for choices.

import os
import json
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/chat/completions"

payload = {
    "model": "gpt-5.6-sol@azure",
    "messages": [
        {"role": "system", "content": "You are a concise technical assistant."},
        {"role": "user", "content": "Give me three practical uses for idempotency keys."},
    ],
    "temperature": 0.3,
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)

if response.status_code != 200:
    # Surface the status and the server's error body, not just the exception.
    print(f"HTTP {response.status_code}: {response.text}")
    response.raise_for_status()

data = response.json()
text = data["choices"][0]["message"]["content"]
print(text)
print(json.dumps(data.get("usage", {}), indent=2))

Three details that matter

Use json=payload, not data=json.dumps(payload). Passing a dict to json= sets the content type header for you and serializes correctly every time. Hand-serializing is where most malformed-body errors come from.

Always set a timeout. Without one, a stalled request hangs your worker indefinitely. A generous timeout is still far better than none.

Print response.text on failure. The error body carries the details you need — error type, code, and a human-readable message. Logging only raise_for_status()'s exception message throws that away, and you will be guessing.

Wrapping it in a function

Once the call works, lift it into a function that takes the messages array as an argument and returns the content string. That keeps your application code clean and gives you exactly one place to change the model name, the timeout, or the retry policy later.

Troubleshooting Common Errors

Almost every failed first call falls into one of four buckets. Here is how to tell them apart quickly.

Authentication failures

Symptom: a 401 response, or a 403 if the key is valid but lacks access to the requested resource.

Check, in order:

  1. Is HIAPI_API_KEY actually set in the shell or process that made the request? echo $HIAPI_API_KEY should print something.
  2. Does the header include the literal word Bearer and exactly one space before the key?
  3. Did the key pick up a trailing newline or quote from copy-paste? Re-export it cleanly.
  4. Has the key been revoked or rotated since you copied it? Issue a fresh one.

Unknown model identifier

Symptom: a 400 or 404 with a message naming the model.

The usual culprits are a typo, a case mismatch, or a stray space inside the string. gpt-5.6-sol@azure must be exact — the @, the hyphens, and the lowercase spelling all count. If you are reading the model name from a config file or environment variable, print the value and its length; invisible whitespace is a common offender.

Malformed request body

Symptom: a 400 complaining about JSON parsing or a missing field.

  • If the error mentions parsing, your body is not valid JSON. In curl, single-quote the payload and double-quote the keys. In Python, use json=payload.
  • If it mentions messages, check that you passed an array of objects with both role and content, not a bare string.
  • If it mentions model as missing, the key was spelled wrong or nested at the wrong level.

A quick sanity check: feed your payload to a JSON validator before sending it. It takes seconds and eliminates the entire category.

Rate limits and quota

Symptom: a 429 response, sometimes with a retry-after hint.

This means your request was well-formed and authenticated but arrived too fast or exceeded an allowance. The fix is not to retry immediately in a tight loop — that makes it worse. Use exponential backoff with jitter, cap the number of attempts, and treat a persistent 429 as a signal to look at your concurrency.

Server-side errors

A 500 or 502 is not your fault. Retry with backoff, and if it persists, capture the full request ID and response body before escalating — those details are what make a support conversation productive.

A general debugging habit

Log four things for every failed call: the HTTP status, the response body, the endpoint path, and the model name. Not the API key. That four-tuple distinguishes all of the buckets above within seconds, whereas a bare exception message rarely does.

Next Steps After Your First Successful Call

Once the smoke test returns content, you have a working integration. Here is how to make it a durable one.

Tune parameters deliberately

Pick a temperature for your use case and write down why. Extraction and classification tasks usually want low randomness; brainstorming wants more. Change one parameter per experiment so you can attribute the result. If you are considering streaming, prototype it early — response parsing differs enough that retrofitting it later is more work than starting with it.

Add retries and timeouts as policy, not afterthought

Wrap the call in a retry with exponential backoff for 429s and 5xx responses only. Never retry a 400 or 401 — the request or credentials are wrong, and retrying just burns time. Set a client timeout on every request, and consider an overall deadline for user-facing flows.

Instrument cost and latency from day one

Log the usage block alongside your own latency measurement. Token counts are the input to every cost conversation, latency is the input to every user-experience conversation. Without them you are optimizing blind.

Put the model name in configuration

Hardcoding gpt-5.6-sol@azure in three files is how migrations become painful. Keep it in one config value, and switching models becomes a one-line change — which is also how you make fair comparisons between models on the platform.

Move the key into proper secret management

If you started with an environment variable on your laptop, the production path is a managed secret store injected at runtime. Same code, safer custody.

Harden the output path

Model output is untrusted input. If you are rendering it into HTML, escape it. If you are parsing it as JSON, validate before acting. If you are routing it into a downstream system, decide explicitly what happens when the response is empty or truncated.

When you are ready to explore other model targets on the platform, they use the same request shape — only the model string changes, so everything you built above carries over unchanged.

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