OpenAI-compatible API quickstart
Make your first OpenAI-compatible API request with Suanliqiao. Check credits, copy a model ID, run Python or Node.js, and resolve common request errors.
This OpenAI-compatible API quickstart takes you from a Suanliqiao account to a first text response using Python or Node.js. You will use a server-side API key, an exact model ID, and the Chat Completions endpoint. Compatibility depends on the selected model and endpoint; it does not mean every OpenAI model or parameter is supported.
1. Sign in and check usable credit
Open the Suanliqiao Console, create an account if needed, and sign in. Check Wallet for your available balance before calling a model. If you use a subscription, confirm that it covers your selected model and has remaining allowance.
If trial credit is offered to your account, follow the Console's claim instructions and check that it has arrived. Do not assume registration alone grants usable credit. You do not need to pay again when your existing credit or eligible subscription covers the request.
If more credit is needed, use the payment options actually displayed in the Console. Methods, currencies, and checkout availability depend on the payment provider and your region; this guide does not guarantee a particular payment option. See Billing and usage for metering basics.
2. Create a key and copy a model ID
In API Keys, create a key for this test. Check its expiry, remaining key allowance, model restrictions, and any IP restriction. An API key's allowance is separate from your account's usable credit. Keep the key on your own machine or server; never put it in browser code, a public repository, or a support message.
Use the model catalog to find a text model that supports Chat Completions. Confirm access with your account and key, then copy its exact model ID from the Console. A display name or a model ID from another provider's example is not a substitute. Availability, prices, and supported parameters can change; see Models and capabilities.
Set these environment variables in the terminal where you will run the example. Replace both placeholders locally; do not run them unchanged or commit the key. The following syntax is for macOS/Linux shells:
export SUANLIQIAO_API_KEY='paste-your-api-key'
export OPENAI_BASE_URL='https://suanliqiao.cn/v1'
export OPENAI_MODEL='paste-the-exact-model-id'Commands containing a real key may be saved in shell history; avoid typing secrets into a shared or recorded terminal and do not share that history.
The base URL is https://suanliqiao.cn/v1. The examples append /chat/completions, sending a POST to https://suanliqiao.cn/v1/chat/completions. If configuring an OpenAI client instead, set its base URL to the /v1 address, not the full endpoint; do not append /v1 twice. See API reference for other endpoints.
3. Make one request with Python or Node.js
Choose either example. Both use built-in HTTP libraries, so no SDK installation is required. They send the same small, non-streaming request and set a 30-second timeout. Your selected model must support this request format; do not add optional parameters until you have checked its capabilities. Running either example makes a real request and may consume credit.
Python 3.10 or newer
Save as quickstart.py, then run python3 quickstart.py in the terminal with your environment variables:
import json
import os
import sys
import urllib.error
import urllib.request
url = os.environ["OPENAI_BASE_URL"].rstrip("/") + "/chat/completions"
payload = {
"model": os.environ["OPENAI_MODEL"],
"messages": [{"role": "user", "content": "Say hello in one sentence."}],
}
request = urllib.request.Request(
url,
data=json.dumps(payload).encode("utf-8"),
headers={
"Authorization": "Bearer " + os.environ["SUANLIQIAO_API_KEY"],
"Content-Type": "application/json",
"User-Agent": "docs-quickstart/1.0",
},
method="POST",
)
try:
with urllib.request.urlopen(request, timeout=30) as response:
result = json.load(response)
except urllib.error.HTTPError as error:
print(f"HTTP {error.code}: {error.read().decode('utf-8')}", file=sys.stderr)
sys.exit(1)
except (urllib.error.URLError, TimeoutError) as error:
print(f"Connection or timeout error: {error}", file=sys.stderr)
sys.exit(1)
print(result["choices"][0]["message"]["content"])Node.js 22 or newer
Save as quickstart.mjs, then run node quickstart.mjs in the same environment:
const url = process.env.OPENAI_BASE_URL.replace(/\/$/, '') + '/chat/completions';
const payload = {
model: process.env.OPENAI_MODEL,
messages: [{ role: 'user', content: 'Say hello in one sentence.' }],
};
try {
const response = await fetch(url, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.SUANLIQIAO_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
console.error(`HTTP ${response.status}: ${await response.text()}`);
process.exitCode = 1;
} else {
const result = await response.json();
console.log(result.choices[0].message.content);
}
} catch (error) {
console.error(`Connection or response error: ${error.message}`);
process.exitCode = 1;
}Check the result
A successful text response contains choices[0].message.content, which these examples print. The wording will vary. The response may also include usage information, depending on the upstream model. Check Usage Logs and your balance in the Console to inspect the request and its metering; a successful response is not evidence that the request was free.
4. Resolve a failed first request
Read the HTTP status and the returned error message or error.code. A status alone does not identify every cause. The examples show the error response and exit unsuccessfully rather than silently retrying.
401— key rejected or exhausted: check thatSUANLIQIAO_API_KEYcontains the key you just created, with no extra whitespace. Confirm that it is active, unexpired, and has remaining key allowance in API Keys. Replace a revoked or exposed key; do not send it to support.403withinsufficient_user_quota— account funding is insufficient: check Wallet or the applicable subscription allowance. Claim an offered credit or add funds only if needed, then confirm the updated balance before retrying. Repeating the same unfunded request will not fix it.- JSON
403withpre_consume_token_quota_failed— key allowance could not be reserved: a key may still have some allowance but not enough for this request's reservation. Check its remaining allowance separately from the account balance. Other gateway JSON403messages may indicate an IP, model, group, or account restriction; correct the specific restriction rather than assuming a payment is required. - Non-JSON
403, such as plain texterror code: 1010— possible edge rejection: this is different from a gateway JSON quota error and does not establish that more credit is needed. The Python example sends the honest application identifierUser-Agent: docs-quickstart/1.0; it does not impersonate a browser or guarantee acceptance. If blocked, save the HTTP status, request time, and edge request ID if present, then contact site support. Do not rotate networks or alter security controls to bypass the block. 400— invalid request: confirm that bothmodelandmessagesare present and that the chosen model supports Chat Completions. Start with the request above, remove unsupported optional parameters, and follow the returned message.503withmodel_not_found— no eligible model route: recopy the model ID and check current access and availability. Select another currently available Chat Completions model if appropriate. This code does not necessarily mean the ID is misspelled.429— inspect the cause before retrying: a request-rate limit can produce this status, but an upstream response may use it for another limit. For a temporary rate limit, reduce concurrency and use bounded exponential backoff with jitter, respectingRetry-Afterif provided. For an explicit quota or credit error, correct that condition first; do not treat every429as a Wallet balance problem.- Other
5xxor a connection timeout: check the service status and Console logs. Retry only a small, bounded number of times after a delay when the failure appears temporary. A timeout does not prove that the request was never processed; check Usage Logs before resending to avoid duplicate usage.
If the problem persists, share the timestamp, model ID, HTTP status, error code, and request ID if present. Remove API keys, authorization headers, and private prompt content from any diagnostic material.