Quickstart

Prepare your API address and key, list models, and send your first chat request.

This guide uses the OpenAI-compatible Chat Completions endpoint. Run the examples in a terminal or on a server; no SDK installation is required.

1. Prepare your API address and key

1. Sign in to the console provided by your administrator.
2. Open the API Keys page (console path /keys), then create and copy an API key.
3. Confirm that your account and key are active and can access the intended model.
4. Confirm your API base URL using the address supplied by your administrator or console.

The following commands work in Bash / Zsh on macOS, Linux, or WSL. Replace the example address with your own, then set the environment variables:

export API_BASE_URL='https://gateway.example.com/v1'
export API_KEY='YOUR_API_KEY'

In this guide, API_BASE_URL includes one /v1 and has no trailing /. If your deployment uses a path prefix, preserve it, for example https://example.com/gateway/v1. Do not use the documentation domain or add /v1 twice.

Replace YOUR_API_KEY locally. Do not commit a real key to Git, put it in browser code, or expose it in screenshots. Do not substitute a sign-in session or management credential for a model API key.

2. List available models

curl --fail-with-body --silent --show-error \
  "$API_BASE_URL/models" \
  -H "Authorization: Bearer $API_KEY"

The response contains model entries in the data array. Each entry’s id is the model ID to use in requests. Choose a chat model that supports Chat Completions and use its exact ID, not its display name.

Replace the placeholder below with that model ID. The following requests use this variable:

export API_MODEL='YOUR_CHAT_MODEL_ID'

If the list is empty or you are unsure which model supports chat, ask your deployment administrator to confirm the channel configuration, model capabilities, and key permissions.

3. Send your first chat request

Choose one of the three options below, using the environment variables you set above. Sending a request invokes the actual model.

cURL

Requires cURL 7.76 or later. Use the original model ID returned by the model list.

curl --fail-with-body --silent --show-error \
  "$API_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<EOF
{
  "model": "$API_MODEL",
  "messages": [
    { "role": "user", "content": "Say hello in one short sentence." }
  ]
}
EOF

Python

Requires Python 3 and uses only the standard library. Save the code as chat.py and run python3 chat.py in the terminal where you set the environment variables.

import json
import os
import urllib.error
import urllib.request

base_url = os.environ["API_BASE_URL"].rstrip("/")
payload = {
    "model": os.environ["API_MODEL"],
    "messages": [
        {"role": "user", "content": "Say hello in one short sentence."}
    ],
}
request = urllib.request.Request(
    f"{base_url}/chat/completions",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)

try:
    with urllib.request.urlopen(request, timeout=60) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise SystemExit(f"Request failed (HTTP {error.code}). Check the request logs.")
except urllib.error.URLError:
    raise SystemExit("Connection failed. Check the API address and network.")

print(result["choices"][0]["message"]["content"])

TypeScript

Requires Node.js 22.18 or later and uses built-in fetch; no dependencies are required. Save the code as chat.mts and run node chat.mts in the terminal where you set the environment variables.

const baseUrl = process.env.API_BASE_URL?.replace(/\/+$/, '');
const apiKey = process.env.API_KEY;
const model = process.env.API_MODEL;

if (!baseUrl || !apiKey || !model) {
  throw new Error('Set API_BASE_URL, API_KEY, and API_MODEL first.');
}

const response = await fetch(`${baseUrl}/chat/completions`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model,
    messages: [
      { role: 'user', content: 'Say hello in one short sentence.' },
    ],
  }),
  signal: AbortSignal.timeout(60_000),
});

if (!response.ok) {
  throw new Error(`Request failed (HTTP ${response.status}). Check the request logs.`);
}

const result = await response.json();
console.log(result.choices[0].message.content);

4. Check the result

On success, cURL prints JSON with the reply at choices[0].message.content. The Python and TypeScript examples print that text directly, for example:

Hello! How can I help you today?

The exact text varies by model. If a request fails, inspect its HTTP status and the request logs in your console. Do not include your complete API key when asking for help.

Troubleshooting

Symptom	What to check
401 or 403	Use a model API key; check its status, permissions, and other access restrictions
404, or an HTML response	Check the API domain and path for a missing or duplicated /v1
Model not found or no available channel	Use the exact model ID and confirm protocol support and deployment channel configuration
429	Inspect the response and request logs, reduce request frequency, and check applicable account limits
Connection failure or timeout	Check the network, API address, gateway, and upstream service status

These are troubleshooting directions; actual status codes and error messages can vary by upstream service.

Next steps

Configure the same API base URL, key, and model ID in your server-side application. When integrating an existing SDK, check whether it expects a base URL containing /v1 or a full endpoint URL.

About the project and address conventions · 切换到简体中文

Integration guides · API reference