Tutorial
How to Call claude-opus-5-5@aws via the HiAPI API: curl and Python Guide
On this page
What claude-opus-5-5@aws Looks Like Through HiAPI
HiAPI gives you one HTTP surface for many models. Instead of provisioning separate accounts, SDKs, and credential stores for each provider, you point a single request format at HiAPI and select the model you want with a model identifier. For this tutorial that identifier is claude-opus-5-5@aws — the @aws suffix is part of the model name, not a separate field, and it should be passed through exactly as written.
A request lifecycle looks like this:
- Authenticate — send your HiAPI API key in an
Authorizationheader with a bearer token. - Send a chat-style payload — a JSON body with
modeland amessagesarray, where each message has arole(system,user, orassistant) andcontent. - Receive a JSON response — the assistant's reply appears in the response
choicesarray, alongside usage metadata. - Continue the conversation — append the assistant message and your next user message to the same
messagesarray and send again. The API is stateless; the full conversation lives in your payload.
Because the shape is the same across models, working code you write for claude-opus-5-5@aws transfers to other models by changing the model string. Keep that field in one place in your code — a config value or environment variable — rather than hard-coding it across multiple files.
One naming note: the platform documents this model as claude-opus-5-5@aws. Use that exact string. Typos, extra spaces, or dropping the suffix will produce a model-not-found style error rather than a helpful warning.
Get Your Credentials and Authenticate
Before you can call the API you need an API key from your HiAPI account. Treat this key as a secret: store it in an environment variable or your platform's secret manager, never in source control, and never in client-side code that ships to browsers.
HiAPI authenticates requests with a bearer token in the Authorization header:
export HIAPI_API_KEY="your-api-key-here"
Every request must include:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
A few practical rules that prevent most authentication failures:
- Keep the literal
Bearerprefix followed by a single space, then the key. Missing the prefix or the space is a common copy-paste error. - Do not wrap the key in quotes inside the header value.
- If you rotate keys, update the environment variable and restart the process — long-running workers often cache the old value.
- Check for trailing whitespace or newlines when pasting keys into a
.envfile; some loaders do not trim them.
If your key is missing or malformed you will get an authentication error (401-class) rather than a model error, which makes this easy to distinguish from later problems. Once a request authenticates successfully, the same header works for streaming, tool calls, and every other pattern in this guide — you do not need a different credential per feature.
For server-side code, load the key once at startup and pass it into a shared client or a small wrapper function. That keeps the secret in one place and makes it trivial to swap between development and production credentials.
Build a Working Request in curl
Here is a complete, runnable request. Replace the placeholder key with your own, or run the export from the previous section first so the shell substitutes it.
curl -sS https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-opus-5-5@aws",
"messages": [
{
"role": "user",
"content": "Explain in three sentences why idempotent POST endpoints matter for payment APIs."
}
]
}'
Breaking it down:
- Endpoint —
POST https://api.hiapi.ai/v1/chat/completions. - Headers — the bearer token and the JSON content type. Both are required.
model— the exact identifierclaude-opus-5-5@aws.messages— an array of role and content objects. The last user message is what the model responds to.- Payload —
-dsends raw JSON, so quoting matters. Single-quote the whole body in a shell and use double quotes for JSON keys.
The response is JSON with a choices array. The generated text is at choices[0].message.content, and usage information (token counts) is included so you can monitor consumption. Response usage is billed by tokens, with current rates shown on the site's pricing panel.
Common adjustments:
{
"model": "claude-opus-5-5@aws",
"max_tokens": 512,
"temperature": 0.2,
"messages": [
{"role": "system", "content": "You are a terse technical editor."},
{"role": "user", "content": "Summarize the request body above in one line."}
]
}
Use max_tokens to cap runaway generations, temperature to control verbosity and variance, and a system message to set behavior once per conversation. The system message belongs inside the same messages array, before the user turns.
The Same Request in Python
The Python version uses the standard library's urllib, so the snippet runs without installing anything. If you prefer a client library, the request structure is identical — only the transport changes.
import json
import os
import urllib.request
API_URL = "https://api.hiapi.ai/v1/chat/completions"
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "claude-opus-5-5@aws"
def ask(user_message: str, system_message: str | None = None) -> str:
messages = []
if system_message:
messages.append({"role": "system", "content": system_message})
messages.append({"role": "user", "content": user_message})
payload = json.dumps({
"model": MODEL,
"messages": messages,
}).encode("utf-8")
request = urllib.request.Request(
API_URL,
data=payload,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(request) as response:
body = json.loads(response.read().decode("utf-8"))
return body["choices"][0]["message"]["content"]
if __name__ == "__main__":
print(ask("Say hello in exactly five words."))
Why this shape is worth keeping:
MODELandAPI_URLare module-level constants, so switching models or endpoints is a one-line change.- The key comes from the environment; the function never accepts a raw secret argument.
- Parsing is isolated at the end, so you can swap
urllibforhttpxorrequestswithout touching how you build the conversation.
To continue a multi-turn conversation, append the assistant's reply and the next user message to messages before sending again. Keep the array growing until you hit your context limit, then summarize older turns into a single system message to stay within budget. Usage in the response is token-based, and current rates are listed on the site's pricing panel.
Streaming Responses for Interactive Use
For chat UIs and long generations, streaming delivers partial output as it is produced instead of waiting for the full response. The request body is unchanged except for one field:
{
"model": "claude-opus-5-5@aws",
"messages": [{"role": "user", "content": "Write a short changelog for a library that just adopted streaming."}],
"stream": true
}
With stream: true, the endpoint responds with server-sent events: each chunk is a line prefixed with data: , and the stream terminates with a final sentinel line. Most chunks contain a delta with a fragment of text in the choices array rather than a complete message.
With curl, drop -sS's quietness and watch output arrive incrementally:
curl -N https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"claude-opus-5-5@aws","stream":true,"messages":[{"role":"user","content":"Count to five slowly."}]}'
The -N flag disables buffering so you see chunks as they land. In Python, read the response line by line:
with urllib.request.urlopen(request) as response:
for raw_line in response:
line = raw_line.decode("utf-8").strip()
if not line.startswith("data: "):
continue
data = line[len("data: "):]
if data == "[DONE]":
break
chunk = json.loads(data)
delta = chunk["choices"][0].get("delta", {})
text = delta.get("content")
if text:
print(text, end="", flush=True)
Practical notes:
- Always handle the
[DONE]sentinel and the empty/keepalive lines; do not assume every line is JSON. - Never block a UI thread on the whole stream — append deltas to a buffer as they arrive.
- If the client disconnects, close the response so the upstream generation can be released.
- Streaming does not change how usage is counted; the final chunk typically carries usage metadata. Billing follows output tokens, with the current rates on the site's pricing panel.
Adding Tool Calls to the Conversation
Tool use lets the model request structured actions from your code rather than only producing prose. The request gains a tools array; the conversation gains assistant messages carrying tool_calls and messages with role: "tool" carrying results.
Define a tool with a JSON Schema for its arguments:
{
"model": "claude-opus-5-5@aws",
"messages": [
{"role": "user", "content": "What is the weather in Lisbon right now?"}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Return current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name, e.g. Lisbon"}
},
"required": ["city"]
}
}
}
]
}
The model may respond with a message that includes tool_calls instead of final text. Each entry names the function and carries a JSON string of arguments. Your job is to execute that function against your own systems, then append the result:
- Append the assistant message containing
tool_callstomessagesverbatim. - Append one message per call with
role: "tool", the matchingtool_call_idfrom the assistant message, andcontentset to the serialized result. - Send the request again with the same
toolsarray. The model then produces a natural-language answer grounded in your result.
Guardrails worth building early:
- Validate arguments against the schema before executing anything — never pass model output directly into a shell or database query.
- Bound the loop. Cap tool-call rounds (three to five is typical) so a model that keeps requesting calls cannot loop indefinitely.
- Return errors as tool results. If your function fails, send a short error string with the matching
tool_call_id; the model can then retry or explain the failure instead of stalling. - Keep tool descriptions precise. Vague descriptions cause wrong tool selection far more often than wrong arguments.
Tool definitions are evaluated with the request and count toward your token usage. Current rates are published on the site's pricing panel.
Where to Go Next
Start with the minimal curl call, move it into a Python wrapper, then layer on streaming and tools only when your use case needs them. The model string claude-opus-5-5@aws stays the same throughout — everything else is a payload field.
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