AionRouter API Key Guide

For your first AionRouter call, prepare the API root URL, a model API key and the exact model ID, then verify them with a small request. The current API root is https://test.aionrouter.io.

This guide is for developers using the API from a terminal, backend application or third-party client. Follow “create a key → configure your environment → list models → test generation → check records”, then learn how to manage quotas, groups and key rotation before production.

Understand accounts, API keys and model access

Signing in to the console lets you manage your account, funds and keys. Model requests use an API key created in API Key management. Signing in on the website does not configure credentials for your local terminal, Python program or editor extension.

Check the public model catalog, key permissions and actual model availability separately. A model shown publicly may not be callable by every account or key, and a model does not necessarily accept every API protocol.

Create a key and verify your first connection

Create a key and verify the connection

1. Create a key in the console

Sign in, open API Key management and create a key. Use a descriptive name such as website-production, local-development or ci-review so you can identify its usage and revoke it later.

Set the quota, expiration, allowed models, IP allowlist and group as needed. Copy the complete key using the page's copy action.

Model endpoints require this API Key. Browser login credentials and personal access tokens for management APIs serve different purposes and should not replace it.

2. Set the service URL and key

Set AIONROUTER_BASE_URL to the service root without a trailing slash, using the API address provided by the console.

Terminal compatibility

Use the examples for your shell: macOS/Linux use Bash or Zsh; Windows uses PowerShell or CMD. Git Bash/WSL can use the Bash examples, but run all setup and requests in the same environment. The current API root is https://test.aionrouter.io.

Windows examples explicitly use curl.exe to avoid the curl alias in Windows PowerShell 5.1. Check curl --version or curl.exe --version; --fail-with-body requires cURL 7.76.0 or later. Microsoft: curl on Windows · cURL options

Run one shell variant only. Environment variables apply to that terminal and programs started from it. In CMD, run each line separately; at the AIONROUTER_BASE_URL prompt, paste the API root shown above, without a trailing slash. Then enter the actual key, model or voice when prompted. Do not paste Bash export, backslash continuations or heredocs into CMD or PowerShell.

macOS / Linux — Bash / Zsh

export AIONROUTER_BASE_URL='https://test.aionrouter.io'
export AIONROUTER_API_KEY='替换为控制台复制的完整密钥'

Windows — PowerShell

$env:AIONROUTER_BASE_URL = 'https://test.aionrouter.io'
$env:AIONROUTER_API_KEY = Read-Host 'AIONROUTER_API_KEY'

Windows — CMD

set "AIONROUTER_BASE_URL="
set /p "AIONROUTER_BASE_URL=AIONROUTER_BASE_URL: "
set "AIONROUTER_API_KEY="
set /p "AIONROUTER_API_KEY=AIONROUTER_API_KEY: "

The commands below read these variables. Setting them does not send a request or configure other SDKs and clients automatically.

3. List models visible to the key

macOS / Linux — Bash / Zsh

curl --fail-with-body --silent --show-error \
  "$AIONROUTER_BASE_URL/v1/models" \
  -H "Authorization: Bearer $AIONROUTER_API_KEY"

Windows — PowerShell

curl.exe --fail-with-body --silent --show-error "${env:AIONROUTER_BASE_URL}/v1/models" -H "Authorization: Bearer ${env:AIONROUTER_API_KEY}"

Windows — CMD

curl.exe --fail-with-body --silent --show-error "%AIONROUTER_BASE_URL%/v1/models" -H "Authorization: Bearer %AIONROUTER_API_KEY%"

In an OpenAI-compatible response, model IDs appear in data[].id. The following illustrates the structure; YOUR_MODEL_ID is not a claim that a particular model is available.

{
  "object": "list",
  "data": [
    {
      "id": "YOUR_MODEL_ID",
      "object": "model"
    }
  ]
}

Copy an actual returned ID, then review endpoint and pricing information in the Model Marketplace.

The list is filtered by key restrictions, accessible groups, enabled channels and billing configuration. A successful list request confirms that its credentials worked; it does not guarantee that every listed model works on every endpoint at all times.

Send credentials for each API format

JSON requests normally also need Content-Type: application/json. For multipart uploads, let the HTTP client generate the header and its boundary.

For this Messages example, replace the model ID with an accessible model that supports the Messages format.

macOS / Linux — Bash / Zsh

curl --fail-with-body --silent --show-error \
  "$AIONROUTER_BASE_URL/v1/messages" \
  -H "x-api-key: $AIONROUTER_API_KEY" \
  -H 'anthropic-version: 2023-06-01' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "model": "YOUR_MESSAGES_MODEL_ID",
    "max_tokens": 128,
    "messages": [
      {"role": "user", "content": "请用一句话介绍你能帮助我完成什么。"}
    ]
  }'

Windows request body: api-authentication-3.json

Save this JSON in the current directory as UTF-8 without BOM, replacing YOUR_... values with actual model IDs or other required values. JSON files do not expand environment variables: changing a terminal model variable does not change this file. Do not use Windows PowerShell 5.1 > to create it, because that defaults to UTF-16LE. Both Windows commands below read the same file. Microsoft: character encoding

{
  "model": "YOUR_MESSAGES_MODEL_ID",
  "max_tokens": 128,
  "messages": [
    {
      "role": "user",
      "content": "请用一句话介绍你能帮助我完成什么。"
    }
  ]
}

Windows — PowerShell

curl.exe --fail-with-body --silent --show-error "${env:AIONROUTER_BASE_URL}/v1/messages" -H "x-api-key: ${env:AIONROUTER_API_KEY}" -H 'anthropic-version: 2023-06-01' -H 'Content-Type: application/json' --data-binary '@api-authentication-3.json'

Windows — CMD

curl.exe --fail-with-body --silent --show-error "%AIONROUTER_BASE_URL%/v1/messages" -H "x-api-key: %AIONROUTER_API_KEY%" -H "anthropic-version: 2023-06-01" -H "Content-Type: application/json" --data-binary "@api-authentication-3.json"

Use the required authentication method without sending conflicting keys in different headers. Do not place the key in business URLs, public pages or downloadable client code.

Verify generation before integrating your application. Listing models mainly checks the URL and authentication. Also run a minimal request appropriate to your task from text generation, image generation, video generation or text-to-speech. Listing an image model does not verify a text endpoint. Do not copy a console session credential into model API requests.

With an SDK, inspect the final URL it constructs. The root is https://test.aionrouter.io; clients requiring an OpenAI-compatible API prefix usually need the root plus /v1. See Base URLs and client configuration for client-specific guidance.

Manage quotas, models, IPs and groups by project

What each key setting controls

Key quota and account funds are separate limits. A key with quota remaining can still lack sufficient account funds. Unlimited key quota does not bypass funding, model or group restrictions.

For automatic groups, configure the allowed candidate groups and cross-group retries in the console. Automatic grouping grants no additional group permissions, and the group ultimately used can affect the price.

Separate development and production. Restrict a local test key to the models you are validating. Give production its own key so you can distinguish requests and revoke access. Set explicit expiration dates for temporary automation or external collaborators.

Allowlist the actual outbound IP. Your computer, office network, cloud server and containers may use different egress addresses. Opening the console in a browser does not prove that backend calls use the same IP. Recheck after changing servers, proxies or networks instead of broadly expanding access.

Groups affect available models and prices. After changing a group or automatic grouping strategy, check the model list, details and usage records again. Do not copy another account's groups, discounts or prices into your configuration, or calculate each charge from a discount badge.

A spending quota does not control concurrency. A key limit does not manage your job queue, output length or retries. Production applications still need request concurrency and task-size controls.

Store, rotate and respond to exposed keys

Store and rotate keys safely

Server applications can read keys from environment variables or a secrets service. Keep complete keys out of Git repositories, screenshots, tickets, usage logs and browser frontend code. Use a key name or masked identifier for troubleshooting.

Use separate keys for projects and environments. This makes limits, usage attribution and individual revocation easier to manage.

Routine rotation

1. Create key B with the required groups and model permissions.
2. Switch the application to B and deploy or restart it as needed.
3. Check the new configuration with a small request and review usage records.
4. After every instance has switched, disable key A.
5. Delete A when a rollback is no longer needed.

Rotation means creating a new key and changing the application's credential, not editing the string of an existing key.

If a key has leaked

Disable or delete the exposed key first, then create a replacement and update the application. Review unusual requests and charges, and remove plaintext copies from repositories, logs and configuration. A previously public key remains compromised even after its current file copy is removed.

Keep production keys out of browser code. A key in JavaScript, frontend build variables or a downloadable application can be read by users. Store the platform key on your backend and apply separate authentication and permissions to your own users.

After changing environment variables, check the running process. Terminal programs, background services, containers and apps launched from the Start menu or Dock may read different configuration. Verify rotation with a new request, not just a saved file.

Diagnose failures using errors and usage records

Troubleshoot authentication and unavailable models

Do not diagnose solely from the HTTP status. Read the response error, then check the actual URL, key, model and group.

Expired, disabled and exhausted keys can all return 401 during authentication; it does not always mean a copying error. An unavailable channel can return 503, so 404 alone cannot establish whether a model exists.

For support investigations, retain the time, endpoint, model ID, HTTP status and error body, plus X-Oneapi-Request-Id if present. Remove full keys, personal information and sensitive business content.

Start where the failure occurs. For DNS, connection or TLS failures, check the address, certificate and local network first. Once an HTTP response arrives, inspect its body and request parameters. Missing usage records do not prove that no request occurred; it may have been rejected before logging during network, authentication or routing checks.

Distinguish RPM (request frequency) from TPM (token throughput). If a response includes Retry-After, respect it and your retry limit. Avoid unlimited retries at the SDK, application and job-system layers simultaneously. Smaller context and sensible output limits reduce request size but do not remove account or model limits.

Keep a business task ID, timestamp, model, endpoint, HTTP status and available request ID for each call. Mask authentication headers and remove sensitive user content from error logs.

FAQ and next steps

Frequently asked questions

Can one key call models from multiple providers?

Yes, if the account group has suitable channels and the key's model restrictions allow access. Models may require different endpoints and parameters; consult their respective guides.

Does unlimited quota remove the need for funds or a budget?

No. The actual funding source must still meet its requirements. Unlimited quota removes only the key's own cap; it does not make requests free or account funds unlimited.

Why does authentication still fail after creating a new key?

Check that the running client reads the new value. Shell variables usually reach only that shell and programs launched from it. Existing desktop apps, containers or services may need their own configuration update and restart.

Why can I see a model but not generate a result?

The list reflects model visibility for that query, not guaranteed channel capacity, request compatibility, funding or upstream health. Inspect the generation request's error body.

Does replacing a key change the API address?

Usually not. For the same service, update the credential. If the URL, group or model also changes, verify those settings separately.

Why does the website work while my API key fails? The console and external API use different identity and request flows. Check the external key's status, model scope and group, then test that exact key. A successful web request is not proof of its authorization.

Can the same key work on macOS and Windows? The operating system does not change key permissions. Adjust environment variables, shell syntax, file paths and client settings. IP restrictions must also allow the actual egress of each environment.

Related guides

• API Key page instructions
• Text generation: Chat Completions, Responses and Messages
• Image generation API
• Video generation API
• Text-to-speech API
• Client integration tutorial